@gramlot/gramlot-examples 0.2.15 → 0.3.0

package/src/gramlot_examples/pages/components/19_formlet.js

@@ -0,0 +1,26 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+export class Page extends BasePage {
+    static title = 'Formlet and shared labels';
+    static devices = ['desktop', 'tablet', 'phone'];
+    static css = ['/themes/gramlot-base/theme.css'];
+    main(root) {
+        const pane = root.main({class:'example-page stack'});
+        pane.h1('One layout, shared label settings');
+        pane.p('Change the columns. The fields keep their values and their own label overrides.');
+        const controls = pane.formlet({class:'card stack',max_width:'24rem'});
+        controls.html_label('Columns',{for:'columns'});
+        const select = controls.select({id:'columns',value:'^columns',width:'6rem'});
+        select.option('One',{value:'1'});select.option('Two',{value:'2'});
+        const fields = pane.formlet({id:'fields',columns:'^columns:=Number({})',datapath:'customer',
+            lbl_position:'L',lbl_text_align:'right',box_c_width:'100%',max_width:'44rem',gap:'10px 16px'});
+        fields.textbox({id:'first-name',value:'^.name',lbl:'Name'});
+        fields.textbox({value:'^.surname',lbl:'Surname'});
+        fields.textbox({value:'^.city',lbl:'City'});
+        fields.checkbox({value:'^.enabled',lbl:'Active',mode:'switch'});
+        fields.textBoxArea({value:'^.notes',lbl:'Notes (override)',lbl_position:'TL',rows:2});
+        pane.p('^customer.name',{id:'accepted-name'});
+        for(const [destination_path,value] of [['columns','2'],['customer.name','Ada'],['customer.surname','Lovelace'],
+            ['customer.city','London'],['customer.enabled',true],['customer.notes','A shared layout']]) pane.dataSetter({destination_path,value});
+    }
+}
+export class Logic {}

package/src/gramlot_examples/pages/components/19_formlet.md

@@ -0,0 +1,12 @@
+# 19 · Formlet and shared labels
+
+Arrange fields in columns and share label settings. Changing the layout preserves each field and its draft.
+
+**Uses:** the 0.3 inputs and layout collections, labelbox and Source/Data bindings. No database, form-save service or endpoints.
+
+<details>
+<summary>More detail</summary>
+
+`formlet` automatically sizes left labels to the widest label in each rendered column, without fixed label widths. It supplies a grid and shared `lbl_*` / `box_*` defaults. A field's own declaration wins. Defaults that contain pointers resolve in the formlet's Data scope. Layout updates preserve the same controls, focus and uncommitted text. `columns` accepts an integer or CSS track list; `col_min_width` selects a responsive grid, as demonstrated by GroupBox. Use the gallery settings to preview other label positions.
+
+</details>

package/src/gramlot_examples/pages/components/20_group_box.js

@@ -0,0 +1,26 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+export class Page extends BasePage {
+    static title = 'GroupBox and typed copy';
+    static devices = ['desktop', 'tablet', 'phone'];
+    static css = ['/themes/gramlot-base/theme.css'];
+    static locale = 'it-IT';
+    async main(root) {
+        const {Bag} = await import('@gramlot/gramlot');
+        const pane = root.main({class:'example-page stack'});
+        pane.h1('A group with its own Data scope');
+        pane.p('The copy icon writes TYTX. Use the arrow beside it to choose JSON instead.');
+        const group = pane.groupBox({id:'customer-group',lbl:'Customer',datapath:'customer',copy:true,max_width:'44rem'});
+        const fields = group.formlet({col_min_width:'18rem',lbl_position:'L',box_c_width:'100%'});
+        fields.textbox({value:'^.name',lbl:'Name'});
+        fields.dateTextBox({value:'^.date',lbl:'Date',format:'short'});
+        fields.numberTextBox({value:'^.amount',lbl:'Exact amount',dtype:'N'});
+        fields.checkbox({value:'^.enabled',lbl:'Active',mode:'switch'});
+        const other = pane.groupBox({lbl:'Outside the copied group',datapath:'other',lbl_variant:'underline',max_width:'24rem'});
+        other.textbox({value:'^.note',lbl:'Note',box_c_width:'100%'});
+        pane.p('JSON is values-only: use TYTX when types and Bag node attributes must survive the round trip.');
+        const typed = Bag.fromTytx('{"date":"2026-10-17::D","amount":"1234.50::N"}');
+        for(const [destination_path,value] of [['customer.name','Ada'],['customer.date',typed.getItem('date')],
+            ['customer.amount',typed.getItem('amount')],['customer.enabled',true],['other.note','This text is not copied']]) pane.dataSetter({destination_path,value});
+    }
+}
+export class Logic {}

package/src/gramlot_examples/pages/components/20_group_box.md

@@ -0,0 +1,12 @@
+# 20 · GroupBox and typed copy
+
+Group customer data under a heading. Copy TYTX with its types or choose plain JSON from the copy menu.
+
+**Uses:** the 0.3 inputs and layout collections, labelbox and Source/Data bindings. No database, form-save service or endpoints.
+
+<details>
+<summary>More detail</summary>
+
+`groupBox` supplies a heading around slotted Source children. `lbl_variant="underline"` gives a lighter heading. `copy=True` reads the current Bag at the group's explicit `datapath`, including nested data. The default clipboard text is TYTX, preserving supported types and node attributes. The menu's JSON choice uses Bag values as an ordinary object; it omits node attributes and can lose type distinctions. It does not copy rendered text, rejected drafts or unrelated Data. The browser must permit clipboard writing; a denied operation is reported beside the copy action without changing Data.
+
+</details>

package/src/gramlot_examples/pages/components/21_switch.js

@@ -0,0 +1,19 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+export class Page extends BasePage {
+    static title = 'Checkbox as a switch';
+    static devices = ['desktop', 'tablet', 'phone'];
+    static css = ['/themes/gramlot-base/theme.css'];
+    main(root) {
+        const pane = root.main({class:'example-page stack'});
+        pane.h1('One boolean, two presentations');
+        pane.p('Click a caption or focus the switch and press Space. Both controls share the same Data.');
+        const fields = pane.formlet({columns:1,max_width:'26rem',lbl_position:'L'});
+        fields.checkbox({id:'notifications-switch',value:'^enabled',lbl:'Notifications',label:'Email updates',mode:'switch',switch_color:'^switch_color',readonly:'^readonly',disabled:'^disabled'});
+        fields.checkbox({id:'notifications-check',value:'^enabled',lbl:'Same boolean',label:'Email updates',readonly:'^readonly',disabled:'^disabled'});
+        fields.checkbox({value:'^readonly',lbl:'Read only',mode:'switch'});
+        fields.checkbox({value:'^disabled',lbl:'Disabled',mode:'switch'});
+        pane.p('^enabled',{id:'enabled-value'});
+        for(const [destination_path,value] of [['switch_color','purple'],['enabled',true],['readonly',false],['disabled',false]]) pane.dataSetter({destination_path,value});
+    }
+}
+export class Logic {}

package/src/gramlot_examples/pages/components/21_switch.md

@@ -0,0 +1,12 @@
+# 21 · Checkbox as a switch
+
+A switch and a checkbox share one boolean. Compare their appearance, captions and read-only state.
+
+**Uses:** the 0.3 inputs and layout collections, labelbox and Source/Data bindings. No database, form-save service or endpoints.
+
+<details>
+<summary>More detail</summary>
+
+`checkbox(mode="switch")` retains the existing boolean value, labelbox, validation and native checkbox editing. Its internal input exposes `role="switch"`; Space toggles it. `readonly` and `disabled` prevent changes. The default mode remains `checkbox`. The first switch uses `switch_color="^switch_color"`, initially purple. Change that Data value to change its active track color; set it to null to restore the theme. The off state and the other switches keep their theme colors. Otherwise colors follow the theme and the touch mode enlarges the clickable caption area.
+
+</details>

package/src/gramlot_examples/pages/components/22_button.js

@@ -0,0 +1,18 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+export class Page extends BasePage {
+    static title = 'Button commands';
+    static devices = ['desktop', 'tablet', 'phone'];
+    static css = ['/themes/gramlot-base/theme.css'];
+    main(root) {
+        const pane=root.main({class:'example-page stack'});
+        pane.h1('One shared command engine');
+        pane.p('Confirm the action, or click the delayed command several times: only the last burst is delivered.');
+        const actions=pane.div({class:'card stack',max_width:'26rem'});
+        actions.button('Confirm action',{id:'command-confirm',icon:'✓',action:"this.SET('result', 'Confirmed')",ask:'Run this command?'});
+        actions.button('Delayed command',{id:'command-delay',_delay:300,action:"this.SET('result', 'Delayed: ' + _counter)"});
+        actions.html_button('Plain HTML',{type:'button',id:'command-native',connect_onclick:"this.SET('result', 'Explicit HTML event')"});
+        pane.p('^result',{id:'command-result'});
+        pane.dataSetter({destination_path:'result',value:'No command yet'});
+    }
+}
+export class Logic {}

package/src/gramlot_examples/pages/components/22_button.md

@@ -0,0 +1,12 @@
+# 22 · Button commands
+
+Compare the Gramlot command button with plain HTML. Try confirmation and a delayed command.
+
+**Uses:** built-in command components, Source, Data and the shared action engine; the toggle example also uses inputs and layout. No endpoints or database.
+
+<details>
+<summary>More detail</summary>
+
+`button` is a Web Component with an internal native button. It reuses action, ask, fire, nested controllers and _delay. `html_button` stays plain HTML, including native form submission. Here its explicit click connection updates Data. Gramlot command buttons do not implicitly submit forms.
+
+</details>

package/src/gramlot_examples/pages/components/23_toggle_button.js

@@ -0,0 +1,18 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+export class Page extends BasePage {
+    static title = 'Toggle button with LED';
+    static devices = ['desktop', 'tablet', 'phone'];
+    static css = ['/themes/gramlot-base/theme.css'];
+    main(root) {
+        const pane=root.main({class:'example-page stack'});
+        pane.h1('A boolean command with an LED');
+        const fields=pane.formlet({columns:1,max_width:'26rem',lbl_position:'L'});
+        fields.toggleButton('Enabled',{id:'toggle-command',value:'^enabled',readonly:'^readonly',disabled:'^disabled',action:"this.SET('result', this.GET('enabled') ? 'Enabled' : 'Disabled')"});
+        fields.checkbox({value:'^enabled',lbl:'Same Data',id:'toggle-checkbox'});
+        fields.checkbox({value:'^readonly',lbl:'Read only'});
+        fields.checkbox({value:'^disabled',lbl:'Disabled'});
+        pane.p('^result',{id:'toggle-result'});
+        for(const [destination_path,value] of [['enabled',false],['readonly',false],['disabled',false],['result','No command yet']]) pane.dataSetter({destination_path,value});
+    }
+}
+export class Logic {}

package/src/gramlot_examples/pages/components/23_toggle_button.md

@@ -0,0 +1,12 @@
+# 23 · Toggle button with LED
+
+A command button and a checkbox share a boolean. The LED and aria-pressed follow Data.
+
+**Uses:** built-in command components, Source, Data and the shared action engine; the toggle example also uses inputs and layout. No endpoints or database.
+
+<details>
+<summary>More detail</summary>
+
+`toggleButton(value="^enabled")` writes a boolean through the shared Data adapter. The LED and aria-pressed expose the current state; Space and Enter activate the native internal button. The state changes before its optional action; an action confirmation does not undo the state change. Readonly and disabled block user toggling, while external Data can still change the state.
+
+</details>

package/src/gramlot_examples/pages/components/24_dropdown_button.js

@@ -0,0 +1,21 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+export class Page extends BasePage {
+    static title = 'Dropdown commands and persistence';
+    static devices = ['desktop', 'tablet', 'phone'];
+    static css = ['/themes/gramlot-base/theme.css'];
+    main(root) {
+        const pane=root.main({class:'example-page stack'});
+        pane.h1('Execute, or execute and remember');
+        pane.p('Click a menu entry to execute it. Hold Shift while selecting it to also change the main action and caption. Reload to verify persistence.');
+        const actions=pane.div({class:'card stack',max_width:'26rem'});
+        const dropdown=actions.dropDownButton('Export',{id:'export-command',icon:'↓',persist:true,action:"this.SET('result', 'Default export')"});
+        const menu=dropdown.menu();
+        menu.menuline('Export CSV',{code:'csv',id:'export-csv',action:"this.SET('result', 'CSV export')"});
+        menu.menuline('Export PDF',{code:'pdf',id:'export-pdf',action:"this.SET('result', 'PDF export')"});
+        menu.menuline('-');
+        menu.menuline('Unavailable',{code:'unavailable',disabled:true,action:"this.SET('result', 'Unavailable')"});
+        pane.p('^result',{id:'dropdown-result'});
+        pane.dataSetter({destination_path:'result',value:'No command yet'});
+    }
+}
+export class Logic {}

package/src/gramlot_examples/pages/components/24_dropdown_button.md

@@ -0,0 +1,12 @@
+# 24 · Dropdown commands and persistence
+
+The main surface executes; the arrow opens the menu. Shift-select a command to run it and make it the default.
+
+**Uses:** built-in command components, Source, Data and the shared action engine; the toggle example also uses inputs and layout. No endpoints or database.
+
+<details>
+<summary>More detail</summary>
+
+`dropDownButton` is one split command: the main surface never opens its menu. The arrow opens it; arrow keys, Home/End and Escape navigate or close it. Normal selection only executes; Shift+selection executes and changes the default action/caption. `persist=True` requires a stable id and saves the item code for this page URL in browser storage. Nothing executable is stored. On touch, ordinary selection executes; setting a default currently requires Shift. This is a local flat menu, without nested menus or button bars.
+
+</details>

package/src/gramlot_examples/pages/components/25_validation_engine.js

@@ -0,0 +1,51 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = 'Validation rules and callbacks';
+    static devices = ['desktop', 'tablet', 'phone'];
+    static css = ['/themes/gramlot-base/theme.css'];
+    main(root) {
+        const pane = root.main({class:'example-page stack'});
+        pane.h1('Validation playground');
+        pane.p('Leave a field to validate it. Invalid drafts stay visible; the accepted values below change only after success.');
+        const group = pane.groupBox({id:'validation-group',datapath:'profile',copy:true,lbl:'Profile · field validations',max_width:'36rem'});
+        const fields = group.formlet({id:'validation-fields',lbl_position:'L',box_c_width:'100%'});
+        fields.textbox({id:'full-name',value:'^.full_name',lbl:'Name (2–30)',validate_notnull:true,validate_len:'2:30',validate_notnull_error:'Please enter a name.',validate_len_error:'Use 2–30 characters.'});
+        fields.textbox({id:'code',value:'^.code',lbl:'Code (2–6 letters)',validate_case:'upper',validate_regex:'(?:^[A-Z]{2,6}$)',validate_regex_error:'Use 2–6 letters.'});
+        fields.textbox({id:'fallback',value:'^.fallback',lbl:'Empty becomes Guest',validate_empty:'Guest'});
+        fields.numberTextBox({id:'quantity',value:'^.quantity',lbl:'Quantity: 0–10',validate_min:0,validate_max:10});
+        fields.checkbox({id:'strict',value:'^.strict',lbl:'Email',label:'Make the warning blocking'});
+        fields.textbox({id:'email',value:'^.email',lbl:'Email format',validate_email:true,validate_email_iswarning:'^.strict:=!{}'});
+        fields.checkbox({value:'^.check_length',lbl:'Length',label:'Require at least four characters'});
+        fields.textbox({id:'conditional',value:'^.conditional',lbl:'Conditional length',validate_len:'4:',validate_len_if:'enabled',validate_enabled:'^.check_length'});
+        fields.textbox({id:'nickname',value:'^.nickname',lbl:'Nickname',validate_call:'checkNickname',validate_onAccept:'accepted',validate_onReject:'rejected'});
+        fields.textbox({id:'remote-name',value:'^.remote_name',lbl:'Remote name',validate_remote:'check_name',validate_timeout:5000});
+        fields.textBoxArea({id:'notes',value:'^.notes',lbl:'Notes (max 40)',rows:2,validate_len:':40',validate_len_error:'Use at most 40 characters.'});
+        fields.dateTextBox({id:'appointment',value:'^.appointment',lbl:'Appointment',format:'short',validate_notnull:true,validate_notnull_error:'Choose a date or type a date expression.'});
+        fields.filteringSelect({id:'delivery',value:'^.delivery',lbl:'Delivery',values:'standard:Standard,express:Express,pickup:Pick up',validate_notnull:true,validate_notnull_error:'Choose a delivery option.'});
+        group.p('Try an empty name, quantity 11, a malformed email, or a long note. The local callback rejects admin; the asynchronous endpoint rejects taken.');
+        const accepted = pane.details({max_width:'36rem',open:true});
+        accepted.summary('Accepted Data · invalid drafts do not overwrite these values');
+        const values = accepted.dl();
+        for (const [label,path] of [['Name','full_name'],['Code','code'],['Quantity','quantity'],['Email','email'],['Notes','notes'],['Delivery code','delivery'],['Remote name','remote_name']]) {
+            values.dt(label);
+            values.dd('^profile.'+path, {id: {code:'code-result',email:'email-result',remote_name:'remote-result'}[path]});
+        }
+        values.dt('Appointment');
+        values.dd('^profile.appointment',{format:'short'});
+        accepted.p('^profile.validation_status',{id:'validation-status'});
+        for (const [destination_path,value] of [['full_name','Ada Lovelace'],['notes','Please ring the bell.'],['appointment',new Date('2026-10-17T00:00:00Z')],['delivery','standard'],['code','AB'],['fallback','Guest'],['quantity',2],['email',''],['strict',false],['check_length',false],['conditional','Ada'],['nickname','Ada'],['remote_name','AVAILABLE'],['validation_status','Edit a nickname.']]) pane.dataSetter({destination_path:'profile.'+destination_path,value});
+    }
+    check_name({value}) {
+        return value.toLowerCase() === 'taken' ? {errorcode:'reserved',message:'That name is reserved.'} : {value:value.toUpperCase()};
+    }
+}
+Page.registerEndpoint('check_name');
+
+export class Logic {
+    checkNickname(node, {value}) {
+        return value.toLowerCase() === 'admin' ? {errorcode:'reserved',message:'Choose a nickname other than admin.'} : true;
+    }
+    accepted(node, {value}) { node.SET('.validation_status', 'Accepted: ' + value); }
+    rejected(node, {result}) { node.SET('.validation_status', 'Rejected: ' + result.error); }
+}

package/src/gramlot_examples/pages/components/25_validation_engine.md

@@ -0,0 +1,26 @@
+# 25 · Validation rules and callbacks
+
+A labelled groupBox contains a compact formlet with text, multiline text, number, date, selection and boolean controls. Try required values, length, normalization, conditional rules, warnings and asynchronous validation. The group copy icon copies the accepted `profile` Bag as TYTX; its menu also offers JSON. Invalid drafts are not copied. The expandable accepted-Data panel shows what actually changed.
+
+**Uses:** shared input validation, Source conditions, named Logic and typed RPC. The endpoint also runs in the serverless Worker. No database or form-save service.
+
+<details><summary>More detail</summary>
+
+```python
+group = pane.groupBox(datapath="profile", copy=True, lbl="Profile")
+pane = group.formlet(lbl_position="L")
+pane.textbox(value="^.code", validate_case="upper", validate_regex="(?:^[A-Z]{2,6}$)")
+pane.textbox(value="^.email", validate_email=True, validate_email_iswarning="^.strict:=!{}")
+pane.textbox(value="^.nickname", validate_call="checkNickname")
+pane.textbox(value="^.remote_name", validate_remote="check_name")
+```
+
+Clear Name or Appointment to test required values. Write more than 40 characters in Notes. Delivery accepts a listed choice and cannot be empty. The groupBox declares `datapath="profile"` once; its formlet inherits it and fields use relative `^.field` pointers. The formlet automatically aligns left labels without fixed label widths.
+
+Try `abc` in Code: the accepted value becomes `ABC`. Clear the fallback: it becomes Guest. Quantity rejects values outside 0–10. A malformed email is accepted with a warning unless the blocking switch is on. The length condition reads the resolved `validate_enabled` parameter as `enabled`.
+
+The local callback reserves `admin`. The endpoint reserves `taken` and normalizes accepted names to uppercase. It returns a validation result; it does not write Data. While a request is pending, Data retains its last value. Editing again, changing the rules or removing the field makes the old response obsolete. Timeout and transport errors reject the candidate.
+
+`validate_onAccept` runs after the Data write. `validate_onReject` sees the rejected candidate while Data still contains its previous value. Named Logic receives `(node, {value, result, validations, userChange, ...parameters})`; small inline conditions/bodies must originate in activated Source. Full syntax is documented in the core component guide.
+
+</details>

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

@@ -0,0 +1,40 @@
+# Input components
+
+This section uses only the first input components, their shared labelbox, Source,
+Data and bindings. It revisits native forms and binding with `textbox`, `checkbox`,
+`radioButtonText`, multiline/password fields, single radios, colors and sliders;
+endpoint calls and stores are outside this section; the final lesson introduces basic validation.
+
+The gallery activates the `inputs` collection once in its application configuration.
+Python uses its generated JSON grammar; the browser loads its JavaScript implementation.
+The widget names are the same in Python and JavaScript.
+
+Start with Textbox, then compare the boolean checkbox and the single-choice radio
+group. All controls use `lbl`, the same reactive `lbl_position` and the `lbl_`/`box_`
+style prefixes. The controls belong to the shared inputs collection.
+
+
+Continue with **Filtering select** for searchable local code/caption pairs, then
+**Callback select** for the same interaction backed by 100 stable random records
+in a Data Bag. These lessons add named browser Logic, with no endpoint calls.
+
+
+**Combo box** allows free text as well as suggestions; **Checkbox group** stores
+several selected codes together. Compare them with Filtering select and
+RadioButtonText to understand the different value contracts.
+
+
+**Date calendar (w17):** one civil date shared by an inline calendar, a popup field and a text-only field. Compare `dateCalendar`, the default `dateTextBox(calendar=True)` and `calendar=False`. The same labelbox and compact sizes apply.
+
+
+**Required values and length (w18):** compare a rejected draft with the last accepted Data value. Shared validation covers required text, text length and a required number, with compact labelbox fields and a live-edit switch.
+
+Use **Settings (⚙)** in the gallery footer to compare themes, light/dark and label positions across components. **As in the example** restores the lesson's own layout. The first lesson keeps a local position selector to explain its Data binding; later lessons focus on their particular input behavior.
+
+**Formlet and shared labels (w19):** Arrange fields in columns and share label settings. Changing the layout preserves each field and its draft.
+
+**GroupBox and typed copy (w20):** Group customer data under a heading. Copy TYTX with its types or choose plain JSON from the copy menu.
+
+**Checkbox as a switch (w21):** A switch and a checkbox share one boolean. Compare their appearance, captions and read-only state.
+
+- `w25`: complete local validation engine, conditional rules, warnings, Logic callbacks and RPC validation. DB/grid rules remain in their own integration scope.

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,9 +9,9 @@ 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.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.p('^.name', {mask: 'Hello, {}', id: 'greeting'});
+        pane.div('Hover to read the title', {customer: '^.name', title: '^.name:Customer: {customer}', id: 'card'});
+        pane.p('The pointer template reads customer from Source; the customer attribute remains projected.');
         pane.h2('0.2.3: a separate HTML preview');
         pane.html_label('Preview HTML', {for: 'html'});
         pane.textarea({value: '^.html', live: true, id: 'html'});

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

@@ -2,13 +2,13 @@
 
 One name appears in a greeting and a tooltip with different formatting. You learn how templates and masks reuse a bound value without copying text. The later **0.2.3** section previews HTML in a separate sandboxed frame.
 
-**Uses:** Data binding, attribute templates and text masks (0.2.0); sandboxed Data `srcdoc` only in the later part (0.2.3).
+**Uses:** Data binding, explicit pointer templates and text masks; sandboxed Data `srcdoc` only in the later part (0.2.3).
 
 <details>
 <summary>More detail</summary>
 
 
-**Release stage:** core 0.2.0 templates/masks, followed by the separate 0.2.3 Data-srcdoc sandbox step.
+**Release stage:** maintained explicit pointer syntax; Data-srcdoc sandboxing was introduced in 0.2.3.
 
 **Goal:** Reuse one Data value in text and attributes, then distinguish text from a sandboxed HTML document.
 
@@ -22,28 +22,28 @@ 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")
+         title="^.name:Customer: {customer}")
+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.
+`:` opens the pointer template. `{customer}` reads the current Source attribute; `customer` remains a normal projected DOM attribute. Ordinary `${customer}` is literal text. `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.
 
 ## Try it and predict the result
 
 1. Initially the greeting is “Hello, Ada”; hover the card and expect title “Customer: Ada”.
-2. Type Grace: both follow the same Data value. Inspect the card: it has `title`, but no `customer` attribute.
+2. Type Grace: both follow the same Data value. Inspect the card: it has both the formatted `title` and the resolved `customer` attribute.
 3. Clear Name: the greeting becomes empty; the title retains its authored prefix.
 4. Replace Preview HTML with `<h2>Preview two</h2><p>Only this frame changes.</p>`. The heading appears inside the frame; the outer page stays intact. Inspect the iframe's `sandbox` attribute: it is present with an empty value.
 
 ## 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 `^.name: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.
 
-Separate invalid-edit exercise: rename only the template reference to `${missing}`, then reload. Expect an unknown-template-parameter error, not a blank substitute. Restore it. A preceding backslash escapes `${`; an `==` attribute cannot supply a template parameter, and `==` expressions cannot contain a template. See the reference for the permitted expression/template dependency order.
+Separate invalid-edit exercise: rename only the template slot to `{missing}`, then reload. Expect a missing Source-attribute error. Restore it. Use `:=` for an expression with typed slots; ordinary `${...}` text is not interpolated or consumed.
 
 ## The same example across stages
 

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

@@ -71,3 +71,6 @@ 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.

package/src/gramlot_examples/pages/html_svg/06_forms.js

@@ -51,9 +51,9 @@ export class Page extends BasePage {
         options.html_label('Attachment', {for: 'attachment'});
         options.input({type: 'file', id: 'attachment', name: 'attachment'});
         const actions = form.div({class: 'form-actions'});
-        actions.button('Button without an action', {type: 'button'});
-        actions.button('Reset values', {type: 'reset'});
-        actions.button('Submit unavailable', {type: 'submit', disabled: true});
+        actions.html_button('Button without an action', {type: 'button'});
+        actions.html_button('Reset values', {type: 'reset'});
+        actions.html_button('Submit unavailable', {type: 'submit', disabled: true});
     }
 
     field(parent, label, key, kind, attrs = {}) {