@gramlot/gramlot-examples 0.2.2

package/src/gramlot_examples/pages/binding/11_complete_page.js

@@ -0,0 +1,127 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+const SESSIONS = [
+    ['09:00', 'A first Source tree', 'Mira', 'mira', 'Describe a page with semantic HTML.'],
+    ['10:30', 'Drawing with SVG', 'Theo', 'theo', 'Build a small scene from SVG shapes.'],
+    ['13:00', 'Putting it together', 'Mira & Theo', null, 'Compose cards, a schedule and a summary.'],
+];
+const SPEAKERS = [['mira', 'Mira', 'Page authoring'], ['theo', 'Theo', 'SVG composition']];
+const STOPS = [['entrance', 80, 110, 'Entrance'], ['studio', 300, 65, 'Studio'], ['hall', 510, 65, 'Hall']];
+const QUESTIONS = [['Do I need a service?', 'This local example has no remote data.'],
+    ['Is the map interactive?', 'The highlighted stop follows the radio buttons above it.']];
+
+export class Page extends BasePage {
+    static title = 'A complete page with binding';
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const shell = root.div({class: 'example-page complete-page', datapath: 'event'});
+        this.header(shell);
+        const main_content = shell.html_main({class: 'stack'});
+        this.hero(main_content);
+        this.schedule(main_content);
+        this.speakers(main_content);
+        this.map(main_content);
+        this.faq(main_content);
+        shell.footer().small('^.footer');
+        shell.dataSetter({destination_path: '.title', value: 'A day of small interfaces'});
+        shell.dataSetter({destination_path: '.footer', value: 'Gramlot binding examples · Data-driven content'});
+        shell.dataSetter({destination_path: '.show', value: {mira: true, theo: true}});
+        shell.dataSetter({destination_path: '.stop', value: {entrance: false, studio: true, hall: false}});
+        shell.dataSetter({destination_path: '.faq_open', value: false});
+    }
+
+    header(shell) {
+        const header = shell.header({class: 'complete-header'});
+        header.p('GRAMLOT FIELD NOTES', {class: 'eyebrow'});
+        header.h1('^.title', {id: 'title'});
+        header.html_label('Event title', {for: 'title-field'});
+        header.input({value: '^.title', live: true, id: 'title-field'});
+        const nav = header.nav({aria_label: 'Page sections'});
+        for (const [label, target] of [['Schedule', 'schedule'], ['Speakers', 'speakers'], ['Map', 'map'], ['FAQ', 'faq']]) {
+            nav.a(label, {href: `#${target}`});
+        }
+    }
+
+    hero(main_content) {
+        const hero = main_content.section({class: 'card complete-hero', aria_label: 'Illustration'});
+        const drawing = hero.svg({viewBox: '0 0 720 180', role: 'img', aria_labelledby: 'complete-art-title', class: 'example-art'});
+        drawing.title('Three connected steps', {id: 'complete-art-title'});
+        drawing.line({x1: 125, y1: 90, x2: 595, y2: 90, stroke: 'var(--gramlot-border)', stroke_width: 8});
+        for (const [x, label, color] of [[125, 'WRITE', 'var(--gramlot-action)'],
+            [360, 'COMPOSE', 'var(--gramlot-warning)'],
+            [595, 'REVIEW', 'var(--gramlot-success)']]) {
+            const group = drawing.g({transform: `translate(${x} 90)`});
+            group.circle({cx: 0, cy: 0, r: 47, fill: color});
+            group.text(label, {x: 0, y: 6, text_anchor: 'middle', font_size: 15,
+                font_weight: 'bold', fill: 'var(--gramlot-background)'});
+        }
+        hero.p('^.title');
+    }
+
+    schedule(main_content) {
+        const section = main_content.section({id: 'schedule', class: 'stack'});
+        section.h2('Schedule');
+        const filters = section.div();
+        for (const [key, name] of SPEAKERS) {
+            filters.input({type: 'checkbox', value: `^.show.${key}`, id: `show-${key}`});
+            filters.html_label(`Sessions of ${name}`, {for: `show-${key}`});
+        }
+        const table = section.table();
+        table.caption('Three short sessions');
+        const heading = table.thead().tr();
+        for (const title of ['Time', 'Session', 'Speaker', 'Focus']) heading.th(title, {scope: 'col'});
+        const body = table.tbody();
+        SESSIONS.forEach(([time, title, speaker, key, focus], index) => {
+            const row = key ? body.tr({visible: `^.show.${key}`, id: `session-${index}`}) : body.tr({id: `session-${index}`});
+            row.th(time, {scope: 'row'});
+            for (const text of [title, speaker, focus]) row.td(text);
+        });
+    }
+
+    speakers(main_content) {
+        const section = main_content.section({id: 'speakers', class: 'stack'});
+        section.h2('Speakers');
+        const cards = section.div({class: 'grid complete-grid'});
+        for (const [key, name, specialty] of SPEAKERS) {
+            const card = cards.article({class: 'card', visible: `^.show.${key}`});
+            card.h3(name);
+            card.p(specialty);
+        }
+    }
+
+    map(main_content) {
+        const section = main_content.section({id: 'map', class: 'stack'});
+        section.h2('A schematic venue map');
+        const choice = section.div();
+        for (const [key, , , label] of STOPS) {
+            choice.input({type: 'radio', group: 'stop', value: `^.stop.${key}`, id: `stop-${key}`});
+            choice.html_label(label, {for: `stop-${key}`});
+        }
+        const figure = section.figure({class: 'card'});
+        const drawing = figure.svg({viewBox: '0 0 600 210', role: 'img', aria_labelledby: 'venue-title', class: 'example-art'});
+        drawing.title('Entrance, studio and hall connected by a path', {id: 'venue-title'});
+        drawing.path({d: 'M80 110 H300 V65 H510', fill: 'none', stroke: 'var(--gramlot-action)', stroke_width: 8});
+        for (const [key, x, y, label] of STOPS) {
+            const stop = drawing.g({transform: `translate(${x} ${y})`});
+            stop.circle({cx: 0, cy: 0, r: 25, fill: 'none', stroke: 'var(--gramlot-success)', stroke_width: 5,
+                visible: `^.stop.${key}`, id: `ring-${key}`});
+            stop.circle({cx: 0, cy: 0, r: 15, fill: 'var(--gramlot-warning)'});
+            stop.text(label, {x: 0, y: 45, text_anchor: 'middle', font_size: 17, fill: 'currentColor'});
+        }
+        figure.figcaption('The ring marks the stop chosen above the map.');
+    }
+
+    faq(main_content) {
+        const section = main_content.section({id: 'faq', class: 'stack'});
+        section.h2('Frequently asked questions');
+        const toggle = section.div();
+        toggle.input({type: 'checkbox', value: '^.faq_open', id: 'faq-open'});
+        toggle.html_label('Open all answers', {for: 'faq-open'});
+        for (const [question, answer] of QUESTIONS) {
+            const details = section.details({class: 'card', open: '^.faq_open'});
+            details.summary(question);
+            details.p(answer);
+        }
+    }
+}

package/src/gramlot_examples/pages/binding/11_complete_page.md

@@ -0,0 +1,12 @@
+# 11 · A complete page with binding
+
+The event page of HTML / SVG example 12, with its visible state in the Data record `event`.
+
+- The heading, the hero caption and the footer read `^.title` and `^.footer`; the field in the header edits the title while you type.
+- The two checkboxes write `show.mira` and `show.theo`. Schedule rows and speaker cards bind `visible` to them; the joint session has no pointer and stays.
+- The radio buttons above the map own `stop.entrance`, `stop.studio` and `stop.hall`; each map stop shows its ring through `visible`.
+- The FAQ `details` bind `open` to one checkbox.
+
+The main landmark is written `html_main`, held in the variable `main_content`, because the page also has a header and a footer.
+
+**Try it:** Hide Theo, move to the hall, then open all answers.

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

@@ -0,0 +1,9 @@
+# Binding
+
+The pages of this family keep their content in the Data and let the DOM follow it.
+
+A `^` pointer in a text or an attribute reads a Data path and keeps the element up to date. A native control whose `value` is a `^` pointer also writes the Data when you edit it. `dataSetter` puts the initial values in the Data before the first render.
+
+Start with **Pointers**, then follow the order of the list: a context that changes, initial values and defaults, editing, booleans, style and SVG, freeze. The last three pages take the content of HTML / SVG examples 06, 08 and 12 and add the binding, so the same page shows the difference.
+
+Each example has a Python page and its JavaScript equivalent. Both run on the same packaged runtime.

package/src/gramlot_examples/pages/controllers/01_formula.js

@@ -0,0 +1,34 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = 'Formula';
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const pane = root.div({class: 'example-page stack', datapath: 'order'});
+        pane.h1('Formula');
+        const form = pane.form({class: 'card stack'});
+        for (const [label, key] of [['Price', 'price'], ['Quantity', 'quantity'], ['VAT rate', 'vat']]) {
+            form.html_label(label, {for: key});
+            form.input({type: 'number', step: 'any', value: `^.${key}`, live: true, id: key});
+        }
+
+        const result = pane.section({class: 'card stack'});
+        result.h2('Results');
+        const facts = result.dl();
+        for (const [label, key] of [['Total (price × quantity)', 'total'], ['Gross (total × (1 + VAT), = vat)', 'gross'],
+            ['Size (_if / _else)', 'size']]) {
+            facts.dt(label);
+            facts.dd(`^.${key}`, {id: key});
+        }
+
+        pane.dataFormula({result_path: '.total', formula: 'price * quantity', price: '^.price', quantity: '^.quantity', _init: true});
+        pane.dataFormula({result_path: '.gross', formula: 'Math.round(total * (1 + vat) * 100) / 100', total: '^.total', vat: '=.vat',
+            _init: true});
+        pane.dataFormula({result_path: '.size', formula: "'large order'", total: '^.total', _if: 'total > 100', _else: "'small order'",
+            _init: true});
+        pane.dataSetter({destination_path: '.price', value: 12.5});
+        pane.dataSetter({destination_path: '.quantity', value: 4});
+        pane.dataSetter({destination_path: '.vat', value: 0.2});
+    }
+}

package/src/gramlot_examples/pages/controllers/01_formula.md

@@ -0,0 +1,12 @@
+# 01 · Formula
+
+`dataFormula(result_path, formula, **parameters)` computes an expression and writes the result at `result_path`. The names of the parameters are the names inside the expression.
+
+- A `^` parameter triggers the formula when its Data changes: editing the price or the quantity recomputes the total.
+- A `=` parameter is read at each run but does not trigger it. The gross uses `vat='=.vat'`: changing the rate alone does not recompute it; the next change of the total does.
+- `_if` is a condition: when it is false the formula writes the `_else` expression instead.
+- `_init=True` runs each formula once when the page starts, after the setters.
+
+A formula result is itself Data: the gross and the size are formulas of the total.
+
+**Try it:** Change the VAT rate, then the quantity, and watch when the gross follows.

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

@@ -0,0 +1,44 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = 'Controller';
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const pane = root.div({class: 'example-page stack', datapath: 'demo'});
+        pane.h1('Controller');
+
+        const check = pane.section({class: 'card stack'});
+        check.h2('React to a value');
+        check.html_label('Name', {for: 'name'});
+        check.input({value: '^.name', live: true, id: 'name'});
+        check.p('The name is empty', {id: 'warning', class: 'status status--warning', visible: '^.invalid'});
+        check.dataController({script: "this.SET('.invalid', !name.trim())", name: '^.name', _init: true});
+
+        const fired = pane.section({class: 'card stack'});
+        fired.h2('React to a fired path');
+        fired.button('Send a request', {fire: '.request', id: 'request'});
+        fired.p('^.requests', {id: 'requests'});
+        fired.dataController({script: "this.SET('.requests', requests + 1)", _fired: '^.request', requests: '=.requests'});
+
+        const delayed = pane.section({class: 'card stack'});
+        delayed.h2('Wait for a pause (_delay)');
+        delayed.html_label('Search', {for: 'query'});
+        delayed.input({value: '^.query', live: true, id: 'query'});
+        delayed.p('^.searched', {id: 'searched'});
+        delayed.dataController({script: "this.SET('.searched', 'Searching for ' + query)", query: '^.query', _delay: 400});
+
+        const timed = pane.section({class: 'card stack'});
+        timed.h2('Run at start and at intervals (_onStart, _timing)');
+        timed.html_label('Interval in seconds', {for: 'interval'});
+        const interval = timed.select({value: '^.interval', id: 'interval'});
+        for (const seconds of [0, 1, 5]) interval.option(String(seconds), {value: String(seconds)});
+        timed.p('^.ticks', {id: 'ticks'});
+        timed.dataController({script: "this.SET('.ticks', (ticks ?? 0) + 1)", ticks: '=.ticks', _timing: '^.interval',
+            _onStart: true});
+
+        pane.dataSetter({destination_path: '.name', value: 'Ada'});
+        pane.dataSetter({destination_path: '.requests', value: 0});
+        pane.dataSetter({destination_path: '.interval', value: '1'});
+    }
+}

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

@@ -0,0 +1,10 @@
+# 02 · Controller
+
+`dataController(script, **parameters)` runs code for its effects. Inside the script `this` is the controller's Source node: `this.SET('.path', value)` writes the Data relative to its context.
+
+- **React to a value.** `name='^.name'` triggers the controller at every change; it writes `.invalid`, and the warning binds `visible` to it. `_init=True` runs it once at the start.
+- **React to a fired path.** The button's `fire='.request'` fires the path at every click, also with an equal value. The controller counts the requests; `requests='=.requests'` is read without triggering.
+- **Wait for a pause.** `_delay=400` runs the controller 400 ms after the last change, once.
+- **Run at start and at intervals.** `_onStart=True` runs the controller when the page has started; `_timing='^.interval'` repeats it every *n* seconds, and 0 stops it.
+
+**Try it:** Clear the name, type a search quickly, then change the interval to 5.

package/src/gramlot_examples/pages/controllers/03_named_logic.js

@@ -0,0 +1,28 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = 'Named logic';
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const pane = root.div({class: 'example-page stack', datapath: 'cart'});
+        pane.h1('Named logic');
+        pane.p('The formula and the controller name methods of class Logic in 03_named_logic_aux.js.',
+            {class: 'muted'});
+        const form = pane.form({class: 'card stack'});
+        form.html_label('Price', {for: 'price'});
+        form.input({type: 'number', value: '^.price', live: true, id: 'price'});
+
+        const result = pane.section({class: 'card stack'});
+        const facts = result.dl();
+        for (const [label, key] of [["Final price (func='finalPrice')", 'final'], ["Changes seen (func='countChange')", 'changes'],
+            ['Last reason', 'reason']]) {
+            facts.dt(label);
+            facts.dd(`^.${key}`, {id: key});
+        }
+
+        pane.dataFormula({result_path: '.final', func: 'finalPrice', price: '^.price', threshold: 100, _init: true});
+        pane.dataController({func: 'countChange', price: '^.price'});
+        pane.dataSetter({destination_path: '.price', value: 80});
+    }
+}

package/src/gramlot_examples/pages/controllers/03_named_logic.md

@@ -0,0 +1,12 @@
+# 03 · Named logic
+
+The code of this page lives in its companion `03_named_logic_aux.js`, a JavaScript module beside the page that exports `class Logic`. The minimal FileHost serves it for the Python page and for the JavaScript page alike.
+
+- `func='finalPrice'` names a method of `Logic`. A formula method receives one object with the resolved parameters and returns the result: 10% off from the `threshold`.
+- A controller method receives its Source node and the parameters. `node.SET('.changes', …)` writes relative to the node's context.
+- `this` is the logic group: `this.changes` keeps a count between calls, and `this.page` is the Gramlot page.
+- The parameters also carry `_reason`, `_node` and `_triggerpars`.
+
+Named logic compiles nothing at run time, so it also works under a Content Security Policy without `'unsafe-eval'`.
+
+**Try it:** Raise the price above 100, then add a second formula that names `finalPrice` with another threshold.

package/src/gramlot_examples/pages/controllers/03_named_logic_aux.js

@@ -0,0 +1,19 @@
+/**
+ * Companion of 03_named_logic.py and 03_named_logic.js. The minimal FileHost serves it as the
+ * root group of the page logic: `func='finalPrice'` names the method below.
+ */
+export class Logic {
+    /** A formula method receives the resolved parameters and returns the result. */
+    finalPrice(kwargs) {
+        const {price, threshold} = kwargs;
+        if (price == null) return null;
+        return price >= threshold ? Math.round(price * 90) / 100 : price;
+    }
+
+    /** A controller method receives its node and the parameters; `this` is the group. */
+    countChange(node, kwargs) {
+        this.changes = (this.changes ?? 0) + 1;
+        node.SET('.changes', this.changes);
+        node.SET('.reason', `${kwargs._reason}: price ${kwargs.price}`);
+    }
+}

package/src/gramlot_examples/pages/controllers/04_inline_expressions.js

@@ -0,0 +1,38 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = 'Inline expressions';
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const pane = root.div({class: 'example-page stack', datapath: 'player'});
+        pane.h1('Inline expressions');
+        const form = pane.form({class: 'card stack'});
+        for (const [label, key] of [['First name', 'first'], ['Last name', 'last']]) {
+            form.html_label(label, {for: key});
+            form.input({value: `^.${key}`, live: true, id: key});
+        }
+        form.html_label('Score', {for: 'score'});
+        form.input({type: 'range', min: 0, max: 100, value: '^.score', live: true, id: 'score'});
+        const row = form.div();
+        row.input({type: 'checkbox', value: '^.accepted', id: 'accepted'});
+        row.html_label('I accept the rules', {for: 'accepted'});
+
+        const result = pane.section({class: 'card stack'});
+        result.h2("==first + ' ' + last", {first: '^.first', last: '^.last', id: 'full-name'});
+        result.p("==score >= 50 ? 'Passed' : 'Not yet'", {score: '^.score', id: 'verdict',
+            class: "==score >= 50 ? 'status status--success' : 'status status--error'",
+            title: "=='Score ' + score + ' of 100'"});
+        const bar = result.svg({viewBox: '0 0 300 20', role: 'img', aria_label: 'Score bar', class: 'example-art'});
+        bar.rect({x: 0, y: 0, height: 20, width: '==score * 3', score: '^.score', fill: 'var(--gramlot-action)', id: 'bar'});
+        result.button('Start', {disabled: '==!accepted', accepted: '^.accepted', id: 'start',
+            action: "this.SET('.started', true)"});
+        result.p('Started', {visible: '^.started', id: 'started', class: 'muted'});
+
+        pane.dataSetter({destination_path: '.first', value: 'Ada'});
+        pane.dataSetter({destination_path: '.last', value: 'Lovelace'});
+        pane.dataSetter({destination_path: '.score', value: 40});
+        pane.dataSetter({destination_path: '.accepted', value: false});
+        pane.dataSetter({destination_path: '.started', value: false});
+    }
+}

package/src/gramlot_examples/pages/controllers/04_inline_expressions.md

@@ -0,0 +1,12 @@
+# 04 · Inline expressions
+
+A text or an attribute that starts with `==` is a JavaScript expression. Its names are the other attributes of the same node, which are often `^` pointers: the expression is computed again when one of them changes.
+
+- The heading is `==first + ' ' + last`, with `first='^.first'` and `last='^.last'`.
+- The verdict computes its text, its `class` and its `title` from `score`.
+- The SVG bar computes its `width`; the button computes `disabled` from the checkbox.
+- The button's `action` is an inline script run at the click, with `this` = the button node.
+
+Inline code needs a Content Security Policy that allows `'unsafe-eval'`; under a strict policy it stops with a clear error naming the node and the attribute. The legacy macros `SET path = value` and `$1` still work and log a deprecation warning: write `this.SET(path, value)` and `arguments[0]`.
+
+**Try it:** Move the score across 50, accept the rules, then press Start.

package/src/gramlot_examples/pages/controllers/05_node_methods.css

@@ -0,0 +1 @@
+.actions { display: flex; flex-wrap: wrap; gap: .5rem; }

package/src/gramlot_examples/pages/controllers/05_node_methods.js

@@ -0,0 +1,39 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+const ACTIONS = [
+    ['SET: add 1', 'set', "this.SET('.value', this.GET('.value') + 1)"],
+    ['PUT: add 10 silently', 'put', "this.PUT('.value', this.GET('.value') + 10)"],
+    ["FIRE 'now'", 'fire', "this.FIRE('.ping', 'now')"],
+    ["FIRE_AFTER 'later', 1 s", 'fire-after', "this.FIRE_AFTER('.ping', 'later', 1000)"],
+];
+
+export class Page extends BasePage {
+    static title = 'Node methods';
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const pane = root.div({class: 'example-page stack', datapath: 'methods'});
+        pane.h1('Node methods');
+        const actions = pane.div({class: 'actions'});
+        for (const [label, key, script] of ACTIONS) actions.button(label, {action: script, id: key});
+
+        const result = pane.section({class: 'card stack'});
+        const facts = result.dl();
+        for (const [label, pointer, key] of [['value (^.value)', '^.value', 'value'],
+            ['Changes notified', '^.notified', 'notified'],
+            ['Pings received', '^.pings', 'pings'],
+            ['Last ping', '^.last', 'last']]) {
+            facts.dt(label);
+            facts.dd(pointer, {id: key});
+        }
+        result.button('GET value', {action: "this.SET('.read', this.GET('.value'))", id: 'get'});
+        result.p('^.read', {id: 'read', class: 'muted'});
+
+        pane.dataController({script: "this.SET('.notified', notified + 1)", value: '^.value', notified: '=.notified'});
+        pane.dataController({script: "this.SET('.pings', pings + 1); this.SET('.last', ping)", ping: '^.ping',
+            pings: '=.pings'});
+        pane.dataSetter({destination_path: '.value', value: 0});
+        pane.dataSetter({destination_path: '.notified', value: 0});
+        pane.dataSetter({destination_path: '.pings', value: 0});
+    }
+}

package/src/gramlot_examples/pages/controllers/05_node_methods.md

@@ -0,0 +1,11 @@
+# 05 · Node methods
+
+Every Source node offers five methods for the Data. A path starting with `.` is relative to the node's context; here each button's `action` calls them with `this` = the button node.
+
+- `this.SET(path, value)` writes and notifies: the value on screen changes and the observer counts one change.
+- `this.GET(path)` reads. **GET value** copies the current value into `.read`.
+- `this.PUT(path, value)` writes silently: nothing is notified, so the value on screen keeps the old number until the next SET. **GET value** shows the real one.
+- `this.FIRE(path, value)` writes the value and resets the path silently afterwards, so every FIRE is delivered, also with an equal value.
+- `this.FIRE_AFTER(path, value, delay)` fires after `delay` ms. The timer belongs to the node: removing the node cancels it.
+
+**Try it:** Press PUT, then GET value, then SET, and compare the three numbers.

package/src/gramlot_examples/pages/controllers/06_button_controller.js

@@ -0,0 +1,36 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+const KEYS = "[button_shift && 'Shift', button_ctrl && 'Ctrl', button_alt && 'Alt', button_meta && 'Meta']" +
+    ".filter(Boolean).join('+') || 'none'";
+
+export class Page extends BasePage {
+    static title = 'Button controller';
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const pane = root.div({class: 'example-page stack', datapath: 'buttons'});
+        pane.h1('Button controller');
+
+        const nested = pane.section({class: 'card stack'});
+        nested.h2('A controller nested in the button');
+        const button = nested.button('Press me, also with Shift or Alt', {id: 'press'});
+        button.dataController({script: `this.SET('.clicks', button_counter); this.SET('.keys', ${KEYS})`});
+        const facts = nested.dl();
+        for (const [label, key] of [['button_counter', 'clicks'], ['Modifier keys', 'keys']]) {
+            facts.dt(label);
+            facts.dd(`^.${key}`, {id: key});
+        }
+
+        const fired = pane.section({class: 'card stack'});
+        fired.h2('fire and fire_<name>');
+        fired.button('Save (fire)', {fire: '.saved', id: 'save'});
+        fired.p('^.saved_with', {id: 'saved-with'});
+        fired.button('Save and close (fire_save, fire_close)', {fire_save: '.command', fire_close: '.command',
+            id: 'save-close'});
+        fired.p('^.log', {id: 'log'});
+
+        pane.dataController({script: "this.SET('.saved_with', 'fired with ' + saved)", saved: '^.saved'});
+        pane.dataController({script: "this.SET('.log', (log ? log + ', ' : '') + command)", command: '^.command', log: '=.log'});
+        pane.dataSetter({destination_path: '.clicks', value: 0});
+    }
+}

package/src/gramlot_examples/pages/controllers/06_button_controller.md

@@ -0,0 +1,11 @@
+# 06 · Button controller
+
+A button runs one click mechanism: a nested `dataController`, an `action`, or the `fire` family. Declaring two of them on one button is an error.
+
+- **Nested controller.** The `dataController` inside the button runs once per click. Its code reads `button_counter`, which counts the clicks of this button and survives a rebuild, and `button_shift`, `button_ctrl`, `button_alt`, `button_meta`; `_evt` is the DOM event.
+- **fire.** `fire='.saved'` fires the path at each click. The value is the modifier string, such as `Shift`, or `true` without modifiers.
+- **fire_<name>.** `fire_save` and `fire_close` fire their paths with the values `save` and `close`, in attribute order: the log gets two entries per click.
+
+A button with a mechanism gets `type="button"`, so it never submits a form by itself.
+
+**Try it:** Press the first button with Shift, then Save with Alt.

package/src/gramlot_examples/pages/controllers/07_events.js

@@ -0,0 +1,38 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = 'Events';
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const pane = root.div({class: 'example-page stack', datapath: 'events'});
+        pane.h1('Events');
+
+        const clicks = pane.section({class: 'card stack', id: 'click-area',
+            connect_onclick: "this.SET('.clicked', event.target.id || event.target.localName)"});
+        clicks.h2('connect_onclick on a section');
+        clicks.p('Click anywhere in this card, or on one of the chips.');
+        for (const name of ['red', 'green', 'blue']) clicks.span(name, {id: `chip-${name}`, class: 'status'});
+        clicks.p('^.clicked', {id: 'clicked', class: 'muted'});
+
+        const typing = pane.section({class: 'card stack'});
+        typing.h2('connect_oninput and connect_onkeydown');
+        typing.html_label('Type here', {for: 'typing'});
+        typing.input({id: 'typing', connect_oninput: "this.SET('.length', event.target.value.length)",
+            connect_onkeydown: "this.SET('.key', event.key)"});
+        const facts = typing.dl();
+        for (const [label, key] of [['Length', 'length'], ['Last key', 'key']]) {
+            facts.dt(label);
+            facts.dd(`^.${key}`, {id: key});
+        }
+
+        const hover = pane.section({class: 'card stack'});
+        hover.h2('connect_onmouseover and connect_onmouseout');
+        hover.div('Move the pointer over this box', {id: 'hover-box', class: '^.hover_class',
+            connect_onmouseover: "this.SET('.hover_class', 'card status status--success')",
+            connect_onmouseout: "this.SET('.hover_class', 'card')"});
+
+        pane.dataSetter({destination_path: '.hover_class', value: 'card'});
+        pane.dataSetter({destination_path: '.length', value: 0});
+    }
+}

package/src/gramlot_examples/pages/controllers/07_events.md

@@ -0,0 +1,10 @@
+# 07 · Events
+
+`connect_on<event>` adds one DOM listener to the element of its node. The event name is the part after `connect_on`, lower-cased: `connect_onclick` listens to `click`, `connect_onkeydown` to `keydown`.
+
+- The value is inline code with `this` = the declaring node and the parameter `event`. `this.SET('.path', …)` writes relative to the node's context.
+- The handler runs with the declaring node also when the event hits a descendant: a click on a chip reaches the section's handler, and `event.target` names the chip.
+- A value of dotted names, such as `gui.focused`, is named logic of a `js_requires` group instead. The minimal FileHost serves only the companion root group, so this page uses inline code.
+- Removing the node removes its listeners.
+
+**Try it:** Click the green chip, type a word, then add `connect_onfocus` to the field.

package/src/gramlot_examples/pages/controllers/08_remote_source.js

@@ -0,0 +1,34 @@
+import {Page as BasePage, source} from '@gramlot/gramlot/page';
+
+const TOPICS = {
+    binding: ['Binding', 'Pointers connect the DOM to the Data in both directions.'],
+    controllers: ['Controllers', 'Formulas and controllers run code when the Data changes.'],
+    svg: ['SVG', 'SVG attributes follow the Data like HTML attributes.'],
+};
+
+export class Page extends BasePage {
+    static title = 'Remote Source';
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const pane = root.div({class: 'example-page stack', datapath: 'remote'});
+        pane.h1('Remote Source');
+        pane.html_label('Topic', {for: 'topic'});
+        const topic = pane.select({value: '^.topic', id: 'topic'});
+        for (const [key, [title]] of Object.entries(TOPICS)) topic.option(title, {value: key});
+        pane.button('Load from the server', {id: 'load'}).dataController({func: 'load', topic: '=.topic'});
+        const target = pane.section({node_id: 'details', class: 'card stack', id: 'details'});
+        target.p('Nothing loaded yet.', {class: 'muted'});
+        pane.dataSetter({destination_path: '.topic', value: 'binding'});
+    }
+
+    details(root, {topic = 'binding'} = {}) {
+        const [title, summary] = TOPICS[topic];
+        const branch = root.div({datapath: `topics.${topic}`, class: 'stack'});
+        branch.h2('^.title', {id: 'remote-title'});
+        branch.p('^.summary', {id: 'remote-summary'});
+        branch.dataSetter({destination_path: '.title', value: title});
+        branch.dataSetter({destination_path: '.summary', value: summary});
+    }
+}
+source(Page.prototype.details);

package/src/gramlot_examples/pages/controllers/08_remote_source.md

@@ -0,0 +1,10 @@
+# 08 · Remote Source
+
+`gramlot.remoteSource(target, method, params)` asks the host to run a Source method of the Page and replaces the children of `target` with the returned branch.
+
+- The Page declares the method with `@source` in Python and `source(Page.prototype.details)` in JavaScript. It builds into its own `root` and runs on the server.
+- The button's nested controller names `load` in the companion `08_remote_source_aux.js`. It finds the target by its `node_id` and passes the chosen topic.
+- The new branch carries its own `dataSetter` nodes. They run before the branch is built, so its heading and summary show their values at the first render.
+- The request lives as long as the target: if the target is removed first, the late answer is ignored. When two requests overlap, the latest wins.
+
+**Try it:** Choose SVG and load it, then add a third `dataSetter` to the remote branch.

package/src/gramlot_examples/pages/controllers/08_remote_source_aux.js

@@ -0,0 +1,8 @@
+/** Companion of 08_remote_source.py and 08_remote_source.js. */
+export class Logic {
+    /** The button's controller: ask the server for the Source method `details` of this Page. */
+    load(node, kwargs) {
+        const target = this.page.source.getNodeByAttr('node_id', 'details');
+        return this.page.remoteSource(target, 'details', {topic: kwargs.topic});
+    }
+}

package/src/gramlot_examples/pages/controllers/09_end_to_end.css

@@ -0,0 +1 @@
+.actions { display: flex; flex-wrap: wrap; gap: .5rem; }