@gramlot/gramlot-examples 0.2.10 → 0.2.12

package/src/gramlot_examples/pages/binding/02_variable_datapath.md

@@ -1,9 +1,55 @@
 # 02 · Variable datapath
 
-A `datapath` can itself be a pointer. `datapath='^current'` reads the Data path `current` and uses its value as the context of the card.
+One card can show different records. Change its Data context and watch all its fields switch together: you learn how a variable `datapath` avoids rebuilding the card.
 
-The select writes `people.ada`, `people.alan` or `people.grace` into `current`. Every `.name`, `.field` and `.born` pointer in the card then reads the chosen record, and the field below edits it.
+**Uses:** Source, Data, pointers and native binding — core 0.2.0. No endpoint calls.
 
-The `people` records come from one `dataSetter` with a dictionary (Python) or a plain object (JavaScript): it becomes a Bag in the Data.
+<details>
+<summary>More detail</summary>
 
-**Try it:** Rename Alan, choose Grace, then choose Alan again: his record keeps the new name.
+
+**Release stage:** Data binding and browser behavior (core 0.2.0).
+
+**Goal:** Retarget a whole card by changing its Data context.
+
+**Before this lesson:** [b01 · Pointers](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/01_pointers.md), [b04 · Native editing](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/04_native_editing.md). These prerequisites support the release sequence; later comparisons are explicitly labelled below.
+
+**Open and edit:** select **b02 · Variable datapath** 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
+
+The select stores a **path string**, such as `people.alan`, in `current`. The card’s `datapath="^current"` follows that choice; all `.name`, `.field` and `.born` references resolve within the selected record.
+
+```python
+card = pane.article(datapath="^current", class_="card stack")
+card.h2("^.name", id="name")
+card.input(value="^.name", id="name-field")
+```
+
+The dictionary becomes a nested Data Bag through `dataSetter`.
+
+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.
+
+## Try it and predict the result
+
+1. Start with Ada Lovelace, Mathematics, 1815.
+2. Choose Alan, edit his name to “A. M. Turing”, and leave the field.
+3. Choose Grace, then Alan again: his edited name remains; Grace’s record is unchanged.
+
+## Change it and check yourself
+
+Add another person to `PEOPLE` with `name`, `field` and `born`; reload and choose them.
+
+**Answer:** the existing select loop adds an option and the same card shows the new record. No separate handlers are needed for the three displays or edit field.
+
+## The same example across stages
+
+Compared with b01’s fixed context, one variable `datapath` retargets the same declarations together. In the later 0.2.16 c13 lesson this very technique selects a product while remote rules depend only on its category.
+
+## Limits and next step
+
+The selected value must be a Data path, not a record object. Reload reconstructs the initial records; local edits are not persistence. Empty/null contexts are an advanced reference case, not a new record editor.
+
+Continue with [b03 · Setters and defaults](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/03_setters_and_defaults.md). The [authoring reference](https://github.com/gramlot-org/gramlot/blob/main/docs/public/095-writing-pages.md) explains the full contract.
+
+</details>

package/src/gramlot_examples/pages/binding/03_setters_and_defaults.md

@@ -1,10 +1,49 @@
 # 03 · Setters and defaults
 
-`dataSetter` writes a value in the Data. All the setters of a branch run before its first render, wherever they sit: here they come after the form and in a later section, yet the first DOM already shows their values.
+Fields start with values supplied by setters and defaults. You learn when those values are applied and why an existing zero differs from a missing value.
 
-- Setters run parents before descendants, in document order. Two setters write `.customer`; the one in the later section runs last, so the customer is Grace Hopper.
-- A dictionary (Python) or a plain object (JavaScript) becomes a Bag: `.shipping.city` reads inside it.
-- A control fills an empty value path with its `default`. `default_value` wins over `default`. Only a null or missing value is empty: `0`, `false` and `''` are values.
-- `attr_currency='EUR'` sets the attribute `currency` on the Data node of the control's value, after the defaults. `^.price?currency` reads it.
+**Uses:** Source, Data, pointers and native binding — core 0.2.0. No endpoint calls.
 
-**Try it:** Remove the setter in the later section: the customer becomes Ada Lovelace. Add a setter of `.quantity` with `0`: the default no longer applies.
+<details>
+<summary>More detail</summary>
+
+
+**Release stage:** Data binding and browser behavior (core 0.2.0).
+
+**Goal:** Predict initialization order and distinguish an absent value from zero.
+
+**Before this lesson:** [b01 · Pointers](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/01_pointers.md). These prerequisites support the release sequence; later comparisons are explicitly labelled below.
+
+**Open and edit:** select **b03 · Setters and defaults** 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
+
+Setters run before first render, parents before descendants in Source order. The later `.customer` setter wins, so the first display is Grace Hopper. The nested shipping dictionary supplies London.
+
+```python
+form.input(type="number", value="^.quantity", default=1, id="quantity")
+form.input(value="^.note", default_value="No note", default="Never used", id="note")
+```
+
+`default_value` wins over `default`; defaults fill null/missing paths, not `0`, `False` or `""`. `attr_currency="EUR"` sets metadata on the price Data node; `^.price?currency` reads it.
+
+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.
+
+## Try it and predict the result
+
+1. Before editing, predict Customer = Grace Hopper, Quantity = 1, Note = No note, Price = 12.5, Currency = EUR and City = London.
+2. Find the later setter below the form: visual position does not delay initialization.
+
+## Change it and check yourself
+
+Remove only the later `.customer` setter and add `pane.dataSetter(".quantity", 0)`.
+
+**Answer:** after reload Customer is Ada Lovelace and Quantity is 0. The earlier customer setter now wins; the quantity default cannot overwrite a real zero.
+
+## Limits and next step
+
+These are build-time defaults, not record/new-record defaults or automatic refill whenever a user clears a control. Destination paths are bare Data paths, not `^` pointers or `?attr` destinations.
+
+Continue with [b04 · Native editing](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/04_native_editing.md). The [authoring reference](https://github.com/gramlot-org/gramlot/blob/main/docs/public/095-writing-pages.md) explains the full contract.
+
+</details>

package/src/gramlot_examples/pages/binding/04_native_editing.md

@@ -1,11 +1,53 @@
 # 04 · Native editing
 
-A control whose `value` is a `^` pointer shows the Data and writes it back when you edit.
+A form displays the Data written by each control. Switch **live** on and off: you learn when typing updates Data and whether each control writes text, a number or a list.
 
-- Text and textarea write a string; number and range write a number, or null when the field is empty; date writes its text such as `2026-09-30`; color writes the color string.
-- A single select writes the chosen value; a multiple select writes a list.
-- With `live` false a field writes at `change`, when you leave it or press Enter. With `live` true text, textarea, number and range write at every `input`. Here `live='^.live'` follows the checkbox, without rebuilding the fields.
+**Uses:** Source, Data, pointers and native binding — core 0.2.0. No endpoint calls.
 
-The list on the right reads the same Data paths.
+<details>
+<summary>More detail</summary>
 
-**Try it:** Type in the text field with the checkbox off, then on, and compare when the list changes.
+
+**Release stage:** Data binding and browser behavior (core 0.2.0).
+
+**Goal:** Observe when a control writes Data and which type it writes.
+
+**Before this lesson:** [e06 · Forms](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/06_forms.md), [b01 · Pointers](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/01_pointers.md). These prerequisites support the release sequence; later comparisons are explicitly labelled below.
+
+**Open and edit:** select **b04 · Native editing** 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
+
+Text and textarea write strings; number/range write numbers or null for an empty value; dates keep their string representation. Single select writes one value, multiple select a list. The checkbox controls `live` for the other fields.
+
+```python
+form.input(type=kind, value=f"^.{key}", live="^.live", id=key)
+```
+
+The right-hand values read those same paths. There is no application input-scraping handler.
+
+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.
+
+## Try it and predict the result
+
+1. With live unchecked, type in Text without leaving it: the Data display stays “Edit me”. Leave the field: it updates.
+2. Check live and type again: the display follows each input event.
+3. Choose size L and change Topics: the Data stores a value and a list respectively.
+
+## Change it and check yourself
+
+Clear Number while live is on, then enter 7.
+
+**Answer:** the empty control writes null (its display is empty), then numeric 7. It does not write the strings `"null"` or `"7"`. A date is still a date string; editing does not make it a Python datetime.
+
+## The same example across stages
+
+In e06 the browser edits native control values only. Here `value="^.text"` plus a Data setter replaces the literal default and connects editing to application state. The mirrored display needs only another pointer; no per-control copying routine is introduced.
+
+## Limits and next step
+
+Use `change`/leaving the field for the non-live trial; do not rely on Enter having identical behavior in every native control. Browser validation and picker presentation vary.
+
+Continue with [b05 · Checkbox and radio](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/05_checkbox_radio.md). The [authoring reference](https://github.com/gramlot-org/gramlot/blob/main/docs/public/095-writing-pages.md) explains the full contract.
+
+</details>

package/src/gramlot_examples/pages/binding/05_checkbox_radio.md

@@ -1,9 +1,49 @@
 # 05 · Checkbox and radio
 
-A checkbox bound with `value='^path'` reads a boolean and writes `true` or `false`, never the text `on`.
+Checkboxes and radio buttons control boolean values. You learn how to represent yes/no choices and how radio buttons keep a single choice selected.
 
-Radio buttons with the same `group` form one choice. Each button owns its own boolean path. Choosing one writes `true` in its path and `false` in the path of the button that was on. Gramlot generates the DOM `name` of the group, so two pages or two groups never mix.
+**Uses:** Source, Data, pointers and native binding — core 0.2.0. No endpoint calls.
 
-Only `plan.plus` has a setter. `plan.basic` and `plan.team` start empty; a button that is already off is not written, so an empty path stays empty until its button is chosen once.
+<details>
+<summary>More detail</summary>
 
-**Try it:** Choose Team, then Basic, and watch which Data values change; then add a fourth plan.
+
+**Release stage:** Data binding and browser behavior (core 0.2.0).
+
+**Goal:** Model checkboxes and a radio group as boolean Data.
+
+**Before this lesson:** [b04 · Native editing](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/04_native_editing.md). These prerequisites support the release sequence; later comparisons are explicitly labelled below.
+
+**Open and edit:** select **b05 · Checkbox and radio** 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
+
+A checkbox’s bound `value` is boolean. Each radio has a separate boolean path; `group="plan"` makes them mutually exclusive. The runtime supplies the DOM group name.
+
+```python
+row.input(type="radio", group="plan", value=f"^.plan.{key}", id=key)
+```
+
+Only `.plan.plus` starts true. Basic and Team begin null; selecting one writes it true and writes the previously selected path false.
+
+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.
+
+## Try it and predict the result
+
+1. Newsletter is checked, Paper invoice is off and Plus is selected.
+2. Choose Team: Plus becomes false, Team true, Basic remains empty.
+3. Choose Basic: Basic becomes true, Team false, Plus stays false.
+
+## Change it and check yourself
+
+Add `("pro", "Pro")` to `PLANS` and include `plan.pro` in the displayed key list.
+
+**Answer:** the new radio joins the same group. On selection it becomes true and the old selection becomes false. No manual loop clearing all radio paths is necessary.
+
+## Limits and next step
+
+A radio’s bound value is not a string enum. Unselected paths need not all have been written false. Use the existing `group` contract rather than assigning a shared native name manually.
+
+Continue with [b06 · Style and visibility](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/06_style_and_visibility.md). The [authoring reference](https://github.com/gramlot-org/gramlot/blob/main/docs/public/095-writing-pages.md) explains the full contract.
+
+</details>

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

@@ -1,11 +1,45 @@
 # 06 · Style and visibility
 
-Every attribute of the box is a `^` pointer, so the controls restyle it through the Data.
+Controls change an element’s appearance and visibility. You learn how Data drives styles and classes, and how hiding content differs from removing its space in the layout.
 
-- `class` and `style` take a string, or null to remove the attribute.
-- The style shortcuts `color`, `background_color`, `font_size`, `padding` and the macro `rounded` compose one `style` attribute with `style` itself. A shortcut wins over the same property written in `style`; a null shortcut drops only its own property.
-- `visible` false sets `visibility: hidden`: the box disappears and keeps its space. `hidden` is the native attribute: the box leaves the layout.
+**Uses:** Source, Data, pointers and native binding — core 0.2.0. No endpoint calls.
 
-Values need their CSS unit: `font_size='1.5rem'`, not `1.5`.
+<details>
+<summary>More detail</summary>
 
-**Try it:** Write `color: red` in the style field: the shortcut `color` still wins. Then clear the visible checkbox, and afterwards check hidden.
+
+**Release stage:** Data binding and browser behavior (core 0.2.0).
+
+**Goal:** Predict attribute precedence and distinguish visibility from layout removal.
+
+**Before this lesson:** [b04 · Native editing](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/04_native_editing.md), [b05 · Checkbox and radio](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/05_checkbox_radio.md). These prerequisites support the release sequence; later comparisons are explicitly labelled below.
+
+**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
+
+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`.
+
+`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 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.
+
+## Try it and predict the result
+
+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.
+
+## Change it and check yourself
+
+Restore visible, clear hidden and choose 2rem with 24px corners.
+
+**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.
+
+## 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.
+
+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.
+
+</details>

package/src/gramlot_examples/pages/binding/07_bound_svg.md

@@ -1,7 +1,52 @@
 # 07 · Bound SVG
 
-SVG attributes take `^` pointers as HTML attributes do. The circle's `r` and `fill`, the bar's `width` and `fill`, and the label text read Data paths edited by the controls.
+Controls and an SVG drawing share the same values. Change a value and watch the shape follow: binding works for SVG geometry as well as HTML text.
 
-The ranges have `live` true, so the drawing follows the slider while you drag it. SVG has no style shortcuts: `fill` and `stroke` are SVG presentation attributes.
+**Uses:** Source, Data, pointers and native binding — core 0.2.0. No endpoint calls.
 
-**Try it:** Bind the circle's `cy` to a third range.
+<details>
+<summary>More detail</summary>
+
+
+**Release stage:** Data binding and browser behavior (core 0.2.0).
+
+**Goal:** Use the same Data value for a native control and SVG geometry.
+
+**Before this lesson:** [e08 · SVG shapes](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/08_svg_shapes.md), [b04 · Native editing](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/04_native_editing.md). These prerequisites support the release sequence; later comparisons are explicitly labelled below.
+
+**Open and edit:** select **b07 · Bound SVG** 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
+
+The circle’s radius/fill and bar’s width/fill are pointers; their controls write the same paths. Radius and width ranges are live. SVG `fill` and `stroke` are presentation attributes, not HTML style shortcuts.
+
+```python
+controls.input(type="range", min=5, max=80, value="^.radius", live=True, id="radius")
+art.circle(cx=100, cy=100, r="^.radius", fill="^.fill", id="circle")
+art.text("^.radius", x=100, y=190, text_anchor="middle", fill="currentColor", id="radius-label")
+```
+
+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.
+
+## Try it and predict the result
+
+1. The circle begins at radius 40; its numeric label also shows 40. The bar width is 160.
+2. Drag Radius to 60: both circle and label follow, while the bar remains unchanged.
+
+## Change it and check yourself
+
+Add a range bound to `.cy` (min 40, max 160), initialize it with `pane.dataSetter(".cy", 100)`, and replace the circle’s `cy=100` with `cy="^.cy"`.
+
+**Answer:** moving the new range moves the same circle vertically; radius remains controlled independently. There is no new Source lookup or attribute-setting action.
+
+## The same example across stages
+
+Earlier e13 explicitly called `setAttr` on a Source node for each animated coordinate. For user-controlled geometry here, one pointer replaces repeated update calls. The two lessons solve different triggers: this is a simplification of value synchronization, not an identical animation.
+
+## Limits and next step
+
+The range has to remain compatible with the viewBox; a large radius near an edge can be clipped. This lesson changes geometry, not SVG structure.
+
+Continue with [b08 · Freeze](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/08_freeze.md). The [authoring reference](https://github.com/gramlot-org/gramlot/blob/main/docs/public/095-writing-pages.md) explains the full contract.
+
+</details>

package/src/gramlot_examples/pages/binding/08_freeze.js

@@ -8,7 +8,7 @@ export class Page extends BasePage {
         const pane = root.div({class: 'example-page stack', datapath: 'board'});
         pane.h1('Freeze');
         const actions = pane.div({class: 'actions'});
-        for (const [label, method] of [['Freeze', 'freeze'], ['Add one', 'add'],
+        for (const [label, method] of [['Freeze', 'freeze'], ['Increment Data count', 'add'],
             ['Remove last item', 'removeLast'], ['Thaw', 'thaw']]) {
             actions.button(label, {id: method}).dataController({func: method});
         }

package/src/gramlot_examples/pages/binding/08_freeze.md

@@ -1,11 +1,49 @@
 # 08 · Freeze
 
-`renderer.freeze(node)` suspends the DOM work of a branch; `renderer.unfreeze(node)` resumes it and builds the current Source of the branch once.
+Freeze a list, add or remove items, then thaw it. You learn that structural changes can wait while existing Data bindings keep working. Return here after **Named logic** and **Button controller**.
 
-The four buttons call methods of the `Logic` class in `08_freeze.js`, through a `dataController` nested in each button.
+**Uses:** Source freeze/thaw, Data binding and local controllers (0.2.0); shared Page/Logic module layout from 0.2.5.
 
-- While the board is frozen, **Add one** still changes the counter: the elements already built keep following the Data.
-- **Remove last item** removes a Source node at once, but its `<li>` stays on screen until the thaw.
-- **Thaw** builds the branch once, with every removal applied.
+<details>
+<summary>More detail</summary>
 
-**Try it:** Freeze, remove two items, add one, then thaw.
+
+**Release stage:** Data binding and browser behavior (core 0.2.0). The maintained Page/Logic module arrangement is from 0.2.5; it does not move the original behavior into a later release.
+
+**Goal:** Observe immediate Data updates and deferred structural rendering separately.
+
+**Before this lesson:** [e10 · Cards with icons](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/10_cards_with_icons.md), [b01 · Pointers](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/01_pointers.md), [c03 · Named logic](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/03_named_logic.md), [c06 · Button controller](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/06_button_controller.md). These prerequisites support the release sequence; later comparisons are explicitly labelled below.
+
+**Open and edit:** select **b08 · Freeze** 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
+
+The buttons call named `Logic` methods through nested `dataController` declarations. Freeze targets the `board` Source node. `add` increments `.count`; despite the method’s short name, it does **not** create a list item. `removeLast` deletes a Source child.
+
+```python
+actions.button(label, id=method).dataController(func=method)
+```
+
+Existing Data bindings continue while the branch is frozen. Source removal takes effect semantically at once; DOM rebuilding waits until unfreeze.
+
+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. Read the gallery’s **logic.js** tab (the Logic class from `08_freeze.js`) beside the Python source.
+
+## Try it and predict the result
+
+1. Start with count 0, frozen false and three items. Click Freeze.
+2. Click Increment Data count: count becomes 1 immediately. Remove last item twice: three items are still visible.
+3. Click Thaw: only Item 1 remains; count is still 1 and frozen is false.
+
+## Change it and check yourself
+
+Reload, freeze, increment twice, remove once, then thaw.
+
+**Answer:** count 2 is visible before thaw; two list items are visible after thaw. The Data counter is deliberately independent of list length, so it must not be used as an item count.
+
+## Limits and next step
+
+Freeze is not a transaction, a Data pause or a persistence mechanism. Removed nodes stop participating even while old DOM waits for thaw. Avoid adding arbitrary DOM operations to “force” the visual change.
+
+Continue with [b09 · Forms with binding](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/09_forms.md). The [authoring reference](https://github.com/gramlot-org/gramlot/blob/main/docs/public/095-writing-pages.md) explains the full contract.
+
+</details>

package/src/gramlot_examples/pages/binding/09_forms.js

@@ -1,7 +1,7 @@
 import {Page as BasePage} from '@gramlot/gramlot/page';
 
 const RECORD = {name: 'Ada Lovelace', quantity: 3, accent: '#456bc4', intensity: 60,
-    region: 'south', topics: ['html'], note: 'A native multiline field.', updates: true};
+    region: 'south', note: 'A native multiline field.', updates: true};
 const SHOWN = ['name', 'email', 'search', 'website', 'telephone', 'quantity', 'date', 'time', 'month',
     'week', 'accent', 'intensity', 'region', 'topics', 'note', 'updates'];
 
@@ -69,6 +69,7 @@ export class Page extends BasePage {
         facts.dd('^.frequency.weekly', {id: 'out-weekly'});
 
         pane.dataSetter({destination_path: 'form', value: RECORD});
+        pane.dataSetter({destination_path: '.topics', value: ['html']});
         pane.dataSetter({destination_path: '.frequency.weekly', value: true});
     }
 

package/src/gramlot_examples/pages/binding/09_forms.md

@@ -1,12 +1,58 @@
 # 09 · Forms with binding
 
-The fieldsets of HTML / SVG example 06, with each `value` bound to a field of the Data record `form`.
+The form from **Native forms** returns with its fields connected to one Data record. Edit a value and watch other views follow. You learn how binding replaces code that would otherwise copy values between controls and displays.
 
-- One `dataSetter` writes the whole record from a dictionary (Python) or a plain object (JavaScript); a second setter adds `frequency.weekly`.
-- Each field writes its own type: numbers for quantity and intensity, a list for the topics, booleans for the checkbox and the two radio buttons.
-- The record on the right reads the same paths, so it changes while you edit. Intensity has `live` true and follows the slider.
-- The password is bound but not shown, and the file field stays native: a file has no Data value.
+**Uses:** Source, Data, pointers and native binding — core 0.2.0. No endpoint calls.
 
-**Limit:** Reset is not offered: a native reset changes the fields without an input event, so the Data would not follow.
+<details>
+<summary>More detail</summary>
 
-**Try it:** Compare this page with example 06: the fieldsets are the same, and the initial values moved from the attributes to the Data record.
+
+**Release stage:** Data binding and browser behavior (core 0.2.0).
+
+**Goal:** Revisit the native form with one authoritative Data record.
+
+**Before this lesson:** [e06 · Forms](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/06_forms.md), [b03 · Setters and defaults](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/03_setters_and_defaults.md), [b04 · Native editing](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/04_native_editing.md), [b05 · Checkbox and radio](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/05_checkbox_radio.md). These prerequisites support the release sequence; later comparisons are explicitly labelled below.
+
+**Open and edit:** select **b09 · Forms with binding** 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
+
+The fieldsets are inherited conceptually from e06. Most initial values now live in `RECORD`; `dataSetter("form", RECORD)` populates it. The multiple select needs a list: `dataSetter(".topics", ["html"])` sets it directly. Putting that list inside `RECORD` would convert it recursively into a Bag. Each control and each summary entry bind to the same relative path. Intensity is live; ordinary text fields update on change.
+
+```python
+parent.input(type=kind, id=key, name=key, value=f"^.{key}", **attrs)
+record.h2("The Data record")
+```
+
+Password is bound but deliberately absent from the summary; the file input stays native. Boolean radio paths use the `frequency` group.
+
+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.
+
+## Try it and predict the result
+
+1. Compare initial Name, Quantity, Region and Topics with e06. They still describe Ada, 3, South and HTML.
+2. Change Name and leave the field: the Data record shows the edit. Drag Intensity: its summary follows live.
+3. Choose daily: weekly becomes false in Data.
+
+## Change it and check yourself
+
+Change `RECORD["quantity"]` from 3 to 5 and reload.
+
+**Answer:** both Quantity and its summary begin at 5. You edit the initial record once; neither the input declaration nor its summary contains another copied numeric default.
+
+## The same example across stages
+
+**Earlier, e06:** the field call supplies `value="Ada Lovelace"`; checkbox/option declarations carry `checked`/`selected` flags.
+
+**Later, 0.2.0:** the shared field helper supplies `value=f"^.{key}"`; defaults move to `RECORD`. A select supplies `value="^.region"` and its options no longer choose the selection individually.
+
+The same initial information is declared centrally and reflected in multiple places. This removes duplicated state/update responsibility; it does not claim fewer total lines after adding the summary and interaction.
+
+## Limits and next step
+
+No native Reset is offered: native reset does not emit the input/change events needed to synchronize Data. Submit remains disabled. File selection has no bound Data value or upload; this is not a record/form persistence framework.
+
+Continue with [b10 · SVG shapes with binding](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/10_svg_shapes.md). The [authoring reference](https://github.com/gramlot-org/gramlot/blob/main/docs/public/095-writing-pages.md) explains the full contract.
+
+</details>

package/src/gramlot_examples/pages/binding/10_svg_shapes.md

@@ -1,9 +1,54 @@
 # 10 · SVG shapes with binding
 
-The SVG of HTML / SVG example 08, with six attributes turned into `^` pointers.
+The six shapes from **SVG shapes** now have editable dimensions and stroke settings. You learn how pointers connect controls to the drawing without a separate update routine for each shape.
 
-- The ranges change the rectangle width, the circle radius, the ellipse height and one `stroke_width` shared by the line and the polyline.
-- The color field paints the triangle; the text field rewrites the label.
-- Every control has `live` true, so the drawing follows while you drag or type.
+**Uses:** Source, Data, pointers and native binding — core 0.2.0. No endpoint calls.
 
-**Try it:** Bind the circle's `cx` to a new range and move the circle along the row.
+<details>
+<summary>More detail</summary>
+
+
+**Release stage:** Data binding and browser behavior (core 0.2.0).
+
+**Goal:** Revisit the six-shape SVG with bound dimensions and shared stroke state.
+
+**Before this lesson:** [e08 · SVG shapes](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/08_svg_shapes.md), [b04 · Native editing](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/04_native_editing.md), [b07 · Bound SVG](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/07_bound_svg.md). These prerequisites support the release sequence; later comparisons are explicitly labelled below.
+
+**Open and edit:** select **b10 · SVG shapes with binding** 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
+
+The six shapes retain their positions. Width, radius, ellipse height, shared stroke, triangle color and caption now read Data. The ranges and caption text use `live=True`; the color field uses its native change behavior.
+
+```python
+art.circle(cx=172, cy=58, r="^.radius", fill="var(--gramlot-warning)", id="circle")
+pane.dataSetter(".radius", 38)
+```
+
+Line and polyline both read `.stroke`. Their initial shared width is 7; e08 originally used 8 for the line and 7 for the polyline, so this is an explicit small visual change, not exact pixel identity.
+
+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.
+
+## Try it and predict the result
+
+1. Begin with rectangle width 95, radius 38 and ellipse height 38.
+2. Move Stroke width to 10: both line and polyline change together.
+3. Type a new Label: the SVG caption follows each keystroke; changing Triangle color changes only the polygon.
+
+## Change it and check yourself
+
+Add a range for `.cx`, initialize it to 172, and replace only the circle’s `cx=172` with `cx="^.cx"`.
+
+**Answer:** the control moves that circle without moving the ellipse or rectangle. No code for finding/updating the circle in DOM is needed.
+
+## The same example across stages
+
+Compare e08’s `r=38` with this page’s `r="^.radius"` and one setter. Static structure stays; the range and circle now share Data. For stroke, one `.stroke` replaces two independently authored widths. The additional controls add code, while the binding removes the need to author separate synchronization behavior.
+
+## Limits and next step
+
+Not every control is live: the color field uses change. SVG presentation values retain their own types/units. This is a maintained current-API comparison, not an old-package installation exercise.
+
+Continue with [b11 · Complete page with binding](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/11_complete_page.md). The [authoring reference](https://github.com/gramlot-org/gramlot/blob/main/docs/public/095-writing-pages.md) explains the full contract.
+
+</details>