@gramlot/gramlot-examples 0.2.15 → 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.15.
+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
@@ -36,7 +40,7 @@ same-name README:
   end-to-end story, `dataRpc` calls to the endpoints of the page, `remote` fragments and
   `dataRemote` values (`c01`–`c21`). Later lessons introduce topics, authored references, native ask,
   parent/child messages, plain HTML buttons and delayed Gramlot clicks. The package
-  requires core 0.2.19 or later; each lesson states which features it uses.
+  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.15",
+  "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.19"
+    "@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",
@@ -323,6 +323,12 @@
           "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/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.