@gramlot/gramlot-examples 0.2.10 → 0.2.12

package/src/gramlot_examples/pages/html_svg/01_hello_world.md

@@ -1,9 +1,53 @@
 # 01 · Hello world
 
-The smallest Gramlot page: one main landmark, heading and paragraph.
+A small page with a heading and a greeting. You learn how to create elements and nest them to build a page.
 
-`main(root)` declares each element as a typed Source node. The Python and JavaScript Pages produce the same visible structure.
+**Uses:** Source and native HTML/SVG — core 0.1.x. No Data binding.
 
-**Try it:** Add a second paragraph and compare the two Page modules.
+<details>
+<summary>More detail</summary>
 
-**Limit:** The page has no state or interaction.
+
+**Release stage:** Source foundation (core 0.1.x); maintained syntax is used here.
+
+**Goal:** Explain how a Page produces a Source tree, then add one visible element.
+
+**Before this lesson:** [setup and release sequence](https://github.com/gramlot-org/gramlot/blob/main/docs/public/025-try.md). These prerequisites support the release sequence; later comparisons are explicitly labelled below.
+
+**Open and edit:** select **e01 · Hello World** 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
+
+`Page` extends `BasePage`; the adapter calls `main(root)`. Each element call adds a typed Source node. The browser renders that tree; the Python code does not manipulate DOM. `Page.css` selects the shared theme.
+
+```python
+page.h1("Hello, Gramlot!")
+page.p("This heading and paragraph come from a Source tree.")
+```
+
+Here `page` is the local variable holding the main element, not the Page instance (`self`).
+
+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. Open the page: expect one main landmark, one heading and one paragraph.
+2. Compare Python and JavaScript source: both declare that same hierarchy. There is no input or application state to change.
+
+## Change it and check yourself
+
+Add `page.p("My second paragraph")` immediately after the existing paragraph. Predict the count, save and reload.
+
+**Answer:** two paragraphs appear below the same heading. The new call created another Source child; no separate DOM insertion code is needed.
+
+## The same example across stages
+
+Keep this static stage. Later, b01 replaces literal text with a Data pointer; the heading can then change without re-running `main`. That adds reactivity rather than making this two-line static example shorter.
+
+## Limits and next step
+
+An element call inside `main` builds structure once. Changing the source file is not a live Data update. Text is literal, not HTML markup.
+
+Continue with [e02 · Text and links](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/02_text_and_links.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/html_svg/02_text_and_links.md

@@ -1,9 +1,47 @@
 # 02 · Text and links
 
-Text hierarchy, mixed inline content, quotation, code and two kinds of link.
+Paragraphs, emphasis and links in one page. You learn how to combine text and elements, while keeping ordinary text safe to display.
 
-A paragraph combines literal text with strong, emphasis, span and anchor children. The pre/code pair displays escaped text.
+**Uses:** Source and native HTML/SVG — core 0.1.x. No Data binding.
 
-**Try it:** Add an abbreviation and another local destination.
+<details>
+<summary>More detail</summary>
 
-**Limit:** The external standards link needs network access; the page itself fetches nothing.
+
+**Release stage:** Source foundation (core 0.1.x); maintained syntax is used here.
+
+**Goal:** Compose mixed text and links while preserving literal text.
+
+**Before this lesson:** [e01 · Hello World](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/01_hello_world.md). These prerequisites support the release sequence; later comparisons are explicitly labelled below.
+
+**Open and edit:** select **e02 · Text and links** 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 paragraph has text and `strong`, `em`, `span` and `a` children. The `pre().code(...)` pair presents code as text. A fragment link uses the HTML `id`, not a Source label.
+
+```python
+page.h3("A local destination", id="destination")
+page.a("Jump back to the heading", href="#destination")
+```
+
+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. Find the literal `<tag>` text: it is displayed, not turned into an element.
+2. Activate “Jump back to the heading”: the browser moves to “A local destination”. The standards link opens an external page separately.
+
+## Change it and check yourself
+
+Add `page.h3("More", id="more")` and `page.a("Read more", href="#more")`.
+
+**Answer:** the new link jumps to the new heading. Changing only `href` to `#missing` does not create a destination: the two names must match.
+
+## Limits and next step
+
+The external link needs a network connection. Local links are native browser navigation, not a Gramlot router or a request for remote Source.
+
+Continue with [e03 · Lists](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/03_lists.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/html_svg/03_lists.md

@@ -1,9 +1,50 @@
 # 03 · Lists
 
-Ordered, unordered and description lists built from local data.
+Bullet lists, numbered lists and terms with descriptions. You learn how a loop builds several elements from a set of values when the page is created.
 
-Loops add ordered steps, definition pairs and a nested list while Source preserves their structure.
+**Uses:** Source and native HTML/SVG — core 0.1.x. No Data binding.
 
-**Try it:** Add a fourth step and another glossary term.
+<details>
+<summary>More detail</summary>
 
-**Limit:** The list content is fixed when the Page builds Source.
+
+**Release stage:** Source foundation (core 0.1.x); maintained syntax is used here.
+
+**Goal:** Distinguish a Python build-time loop from reactive Data.
+
+**Before this lesson:** [e01 · Hello World](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/01_hello_world.md), [e02 · Text and links](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/02_text_and_links.md). These prerequisites support the release sequence; later comparisons are explicitly labelled below.
+
+**Open and edit:** select **e03 · Lists** 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
+
+`STEPS` drives an ordered list, `TERMS` drives paired `dt`/`dd` nodes, and a nested `ul` is a child of one `li`.
+
+```python
+ordered = page.ol()
+for step in STEPS:
+    ordered.li(step)
+```
+
+The loop runs when the host builds Source; the list on screen is its result.
+
+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. Count three ordered steps, two definition pairs and a nested list.
+2. Reload: the same constants produce the same nodes; no timer or subscription appends rows.
+
+## Change it and check yourself
+
+Append `"Explain the result"` to `STEPS` and `("DOM", "The browser representation.")` to `TERMS`.
+
+**Answer:** after reload there are four ordered items and three definition pairs. Existing nested items are unaffected because their loop uses another collection.
+
+## Limits and next step
+
+A Python list constant is not a Data Bag subscription. Later changing a Data value does not rerun this Python loop.
+
+Continue with [e04 · Semantic page](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/04_semantic_page.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/html_svg/04_semantic_page.md

@@ -1,9 +1,49 @@
 # 04 · A semantic page
 
-Landmarks and sections give a small page a meaningful reading order.
+A page with a header, navigation, main content and footer. You learn how HTML gives each part a role and how links lead to sections within the page.
 
-Header, navigation, main, article, aside and footer are authored as HTML Source. Section IDs serve as anchor targets.
+**Uses:** Source and native HTML/SVG — core 0.1.x. No Data binding.
 
-**Try it:** Add another article and a matching navigation link.
+<details>
+<summary>More detail</summary>
 
-**Limit:** Navigation uses native anchors; there is no client router.
+
+**Release stage:** Source foundation (core 0.1.x); maintained syntax is used here.
+
+**Goal:** Build semantic regions and connect navigation to their IDs.
+
+**Before this lesson:** [e02 · Text and links](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/02_text_and_links.md), [e03 · Lists](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/03_lists.md). These prerequisites support the release sequence; later comparisons are explicitly labelled below.
+
+**Open and edit:** select **e04 · Semantic page** 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 Source declares `header`, `nav`, a main landmark, an `article`, an `aside` and `footer`. `aria_label` names the navigation. The Story and Notes links target `id="story"` and `id="notes"`.
+
+```python
+nav.a("Story", href="#story")
+article = main.article(id="story", class_="stack")
+```
+
+Here `main` is an element variable, distinct from the Page method `main(root)`.
+
+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. Activate Notes, then Story. Each link targets its section inside the preview.
+2. Inspect the Source: visual cards and semantic landmarks are declarations, not a separate HTML template.
+
+## Change it and check yourself
+
+Add `main.article(id="references").h2("References")` and a navigation link with `href="#references"`.
+
+**Answer:** a third destination appears; the browser handles the jump. Adding a link alone would not create an article.
+
+## Limits and next step
+
+Landmark markup does not by itself prove accessibility of an entire application. This lesson has no client router or database.
+
+Continue with [e05 · Tables](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/05_tables.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/html_svg/05_tables.md

@@ -1,9 +1,51 @@
 # 05 · Tables
 
-A data table with a caption, scoped headings and a calculated total.
+A table with headings, rows and a total. You learn how to turn a small dataset into a readable table without repeating the row declarations.
 
-One local row set feeds the table body and footer arithmetic.
+**Uses:** Source and native HTML/SVG — core 0.1.x. No Data binding.
 
-**Try it:** Add a region and confirm the total changes in both languages.
+<details>
+<summary>More detail</summary>
 
-**Limit:** Values are fixed when Source is built.
+
+**Release stage:** Source foundation (core 0.1.x); maintained syntax is used here.
+
+**Goal:** Derive rows and totals from one fixed dataset.
+
+**Before this lesson:** [e03 · Lists](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/03_lists.md). These prerequisites support the release sequence; later comparisons are explicitly labelled below.
+
+**Open and edit:** select **e05 · Tables** 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
+
+`ROWS` contains North (12, 8), South (9, 11) and West (15, 6). `thead`, `tbody` and `tfoot` give the table structure; `scope` identifies row/column headings. Python computes `q1 + q2` before writing each cell.
+
+```python
+for value in (q1, q2, q1 + q2):
+    row.td(str(value))
+```
+
+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. Check row totals: 20, 20 and 21.
+2. Check the footer: Q1 = 36, Q2 = 25, total = 61. Explain why both totals use the same tuples.
+
+## Change it and check yourself
+
+Add `("East", 2, 3)` to `ROWS` and reload.
+
+**Answer:** the new row totals 5; the footer becomes 38, 28 and 66. No cell-specific arithmetic needs editing, because the loop and sums read the enlarged dataset.
+
+## The same example across stages
+
+In the later 0.2.0 c01 lesson, the same idea of a computed total becomes `dataFormula`: inputs change Data and the framework schedules recomputation. The old static calculation remains valid for a fixed report.
+
+## Limits and next step
+
+The totals are fixed in the built Source. Editing a constant requires a rebuild/reload; it does not establish live formulas.
+
+Continue with [e06 · Forms](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/06_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/html_svg/06_forms.md

@@ -1,9 +1,53 @@
 # 06 · Native forms
 
-Native fields, choices and buttons grouped in fieldsets.
+A form with text fields, choices and a Reset button. Change the values and reset them to see what native HTML controls already do on their own. Later, **Forms with binding** revisits this form and connects its fields to shared Data.
 
-The browser owns editing and Reset. The Source grammar authors the HTML label with `html_label(...)`, because `label` is also a node property.
+**Uses:** Source and native HTML controls — core 0.1.x. No Data binding or controllers.
 
-**Try it:** Change a default value, use Reset and add a select option.
+<details>
+<summary>More detail</summary>
 
-**Limit:** Submit is disabled because this page has no save endpoint or declared form handler.
+
+**Release stage:** Source foundation (core 0.1.x); maintained syntax is used here.
+
+**Goal:** Understand native editing and Reset before adding Data binding.
+
+**Before this lesson:** [e04 · Semantic page](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/04_semantic_page.md). These prerequisites support the release sequence; later comparisons are explicitly labelled below.
+
+**Open and edit:** select **e06 · Forms** 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 `field` helper declares a label and input. `html_label` selects the HTML element without confusing it with the Source node’s label. Initial values belong to HTML attributes/content in this stage.
+
+```python
+self.field(identity, "Name", "name", "text", value="Ada Lovelace", required=True)
+options.input(type="checkbox", id="updates", name="updates", checked=True)
+```
+
+The select marks its initial option with `selected`; the textarea has literal content.
+
+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. Change Name and uncheck Receive updates. The controls change natively; there is no Data record display.
+2. Click Reset values: Name returns to Ada Lovelace and Receive updates is checked. Submit stays disabled.
+
+## Change it and check yourself
+
+Change the Name default to `"Grace Hopper"`, reload, type another name, then Reset.
+
+**Answer:** Reset now restores Grace Hopper, because that is the new native default. It does not call an endpoint or restore a Gramlot Data Bag.
+
+## The same example across stages
+
+Return in **core 0.2.0** at [b09 · Forms with binding](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/09_forms.md). The same fieldsets move their defaults into one Data record and replace literal values/checked/selected flags with pointers. The control and the record display share that state; no separate display-update handler is authored. The bound version adds a capability, so the whole file is not claimed to be shorter. Keep this native Reset example as the earlier stage.
+
+## Limits and next step
+
+File selection remains native. No persistence, upload, save endpoint or record/form framework is provided. Reset is safe here because there are no Data bindings.
+
+Continue with [e07 · Native disclosure](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/07_native_disclosure.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/html_svg/07_native_disclosure.md

@@ -1,9 +1,46 @@
 # 07 · Disclosure and measures
 
-Expandable questions with static progress and meter values.
+Expandable details, a progress bar and a meter. You learn how to declare controls whose basic behavior is already supplied by the browser.
 
-A loop creates details/summary pairs. Native browser behavior handles expansion; the measurements have explicit values and labels.
+**Uses:** Source and native HTML/SVG — core 0.1.x. No Data binding.
 
-**Try it:** Add a question and change the fixed meter value.
+<details>
+<summary>More detail</summary>
 
-**Limit:** The measurements do not update automatically.
+
+**Release stage:** Source foundation (core 0.1.x); maintained syntax is used here.
+
+**Goal:** Recognize behavior supplied by native HTML rather than application code.
+
+**Before this lesson:** [e03 · Lists](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/03_lists.md), [e04 · Semantic page](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/04_semantic_page.md). These prerequisites support the release sequence; later comparisons are explicitly labelled below.
+
+**Open and edit:** select **e07 · Native disclosure** 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
+
+Each `details` contains a `summary` and answer paragraph. The browser toggles the disclosure. `progress(value=70, max=100)` and `meter(value=8, max=10)` are fixed measurements, with explicit labels.
+
+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. Open and close “What is Source?”. The answer changes visibility without an authored controller.
+2. Wait: Preparation remains 70% and Quality remains 8 of 10.
+
+## Change it and check yourself
+
+Add another question/answer to the tuple and change the progress value to 80 **and** its label to “Preparation: 80%”.
+
+**Answer:** another disclosure and an 80% bar appear after reload. Updating only the bar would leave a misleading label; this stage has no binding to keep them synchronized.
+
+## The same example across stages
+
+Later b11 revisits the FAQ with `open="^.faq_open"`: one bound checkbox controls both disclosures. The framework projects that one value to each declaration; no list of manual open/close operations is needed.
+
+## Limits and next step
+
+No live task or background progress is being measured. Native disclosure is not Data binding.
+
+Continue with [e08 · SVG shapes](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/08_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/html_svg/08_svg_shapes.md

@@ -1,9 +1,50 @@
 # 08 · SVG shapes
 
-Six SVG primitives in one accessible viewport.
+Six SVG shapes with different sizes, fills and strokes. You learn how to describe a drawing alongside HTML. Later, **SVG shapes with binding** makes these shapes respond to controls.
 
-The SVG dialect nests below an HTML figure. Coordinates, fill and stroke are declared as SVG attributes.
+**Uses:** Source and native HTML/SVG — core 0.1.x. No Data binding.
 
-**Try it:** Move a shape and compare its coordinates in both languages.
+<details>
+<summary>More detail</summary>
 
-**Limit:** This illustration has no animation or pointer behavior.
+
+**Release stage:** Source foundation (core 0.1.x); maintained syntax is used here.
+
+**Goal:** Read SVG geometry and distinguish Source attributes from CSS.
+
+**Before this lesson:** [e01 · Hello World](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/01_hello_world.md). These prerequisites support the release sequence; later comparisons are explicitly labelled below.
+
+**Open and edit:** select **e08 · SVG shapes** 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
+
+An HTML `figure` contains one SVG viewport (`viewBox="0 0 480 200"`), six shapes and a label. The SVG title supplies the accessible name. `cx`, `cy` and `r` describe the circle in viewBox coordinates.
+
+```python
+art.circle(cx=172, cy=58, r=38, fill="var(--gramlot-warning)")
+```
+
+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. Locate the circle between the rectangle and ellipse.
+2. Compare its radius 38 with the ellipse’s separate `rx=26` and `ry=38`: a circle has one radius, an ellipse has two.
+
+## Change it and check yourself
+
+Change only the circle’s `cx` from 172 to 182 and reload.
+
+**Answer:** its center moves ten viewBox units right; its radius and fill do not change. This is a new Source build, not animation.
+
+## The same example across stages
+
+In **0.2.0**, [b10 · SVG shapes with binding](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/10_svg_shapes.md) returns to these six shapes. `r=38` becomes `r="^.radius"`; a range and the circle share `.radius`. A pointer replaces explicit Source-attribute updates for each edit. The initial drawing is comparable, but interaction is new.
+
+## Limits and next step
+
+Coordinates and SVG presentation attributes are not HTML style shortcuts. This stage has no controls or animation.
+
+Continue with [e09 · SVG composition](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/09_svg_composition.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/html_svg/09_svg_composition.md

@@ -1,9 +1,49 @@
 # 09 · SVG composition
 
-A scene assembled from repeated groups, paths and helper methods.
+An SVG scene assembled from smaller parts. You learn how groups and reusable page-building methods keep a larger drawing easy to follow.
 
-House, tree and flower helpers add grouped shapes. Loops place repetitions, while theme tokens color the scene.
+**Uses:** Source and native HTML/SVG — core 0.1.x. No Data binding.
 
-**Try it:** Add a third house or vary flower positions.
+<details>
+<summary>More detail</summary>
 
-**Limit:** The scene is decorative and static.
+
+**Release stage:** Source foundation (core 0.1.x); maintained syntax is used here.
+
+**Goal:** Reuse Source-building methods to compose a scene.
+
+**Before this lesson:** [e03 · Lists](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/03_lists.md), [e08 · SVG shapes](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/08_svg_shapes.md). These prerequisites support the release sequence; later comparisons are explicitly labelled below.
+
+**Open and edit:** select **e09 · SVG composition** 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
+
+`house`, `tree` and `flower` populate a group in the same SVG. A transform moves the whole group, so its child coordinates stay local.
+
+```python
+for x in (115, 330):
+    self.house(drawing, x)
+# Inside house:
+group = drawing.g(transform=f"translate({x} 0)")
+```
+
+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. Count two houses, three trees and three flowers.
+2. Compare the two houses: their child declarations are shared; only the group translation differs.
+
+## Change it and check yourself
+
+Change the house positions to `(115, 330, 210)` and reload.
+
+**Answer:** three houses are built. The added one can overlap existing scenery: a loop reuses declarations but does not automatically solve layout. Try a wider viewBox or deliberate repositioning.
+
+## Limits and next step
+
+These are ordinary Page helper methods building Source, not a recipe registry or component API. The scene is static.
+
+Continue with [e10 · Cards with icons](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/10_cards_with_icons.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/html_svg/10_cards_with_icons.md

@@ -1,21 +1,48 @@
 # 10 · Cards with icons and live Source
 
-Responsive HTML cards with SVG drawings. Click a card's × button to remove it
-without reloading the page.
+Three cards, each with an SVG icon. You learn how to combine text and drawings. The × buttons add a later step: removing a card from Source also removes it from the screen. Return to the buttons after **Events**.
 
-The Builder gives the page, card container and each card a stable `node_label`.
-The button's short JavaScript action finds `main.page.cards` in the browser
-Builder's Source and calls `popNode` with the card label. Gramlot observes the
-Source deletion and removes the corresponding DOM branch, including its SVG.
-The action never removes a DOM element directly.
+**Uses:** Source, HTML and SVG (0.1.x); removal uses browser actions (0.2.0) and the `src` name from 0.2.10.
 
-Python and JavaScript declare the same page and browser action. It also works
-in the static gallery of `gramlot-serverless gallery <folder>`, opened from disk,
-offline.
+<details>
+<summary>More detail</summary>
 
-**Try it:** Remove the middle card, then the others. Reload to restore all three.
-Add a fourth card to the local dataset and give it a matching icon branch.
 
-**Limit:** This is a small, explicit JavaScript action demonstrating live Source,
-not Data binding, persistence or server synchronization. The icons are decorative;
-card text and the labelled remove buttons carry the meaning.
+**Release stage:** Source foundation (core 0.1.x); maintained syntax is used here. The interactive controls are a later 0.2.0 layer; return to them after c07. The src proxy spelling is from 0.2.10.
+
+**Goal:** Remove a Source branch and let Gramlot remove the corresponding DOM.
+
+**Before this lesson:** [e09 · SVG composition](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/09_svg_composition.md), [c07 · Events](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/controllers/07_events.md). These prerequisites support the release sequence; later comparisons are explicitly labelled below.
+
+**Open and edit:** select **e10 · Cards with icons** 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. This lesson executes authored inline JavaScript and needs the gallery’s permissive CSP profile; a strict named-Logic starter needs the corresponding named form.
+
+## Read the page
+
+Three cards use Source `node_label` values `structure`, `drawing` and `reading`. The inline click declaration finds the Source container `main.page.cards` and calls `popNode` with the selected card label. Its SVG disappears with the card.
+
+`node_label` is a Bag path segment, `node_id` is a Source lookup identity, and HTML `id` identifies a DOM element; they are not interchangeable. `main` here is a **Source** path, not a Data prefix.
+
+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. Click × on Drawing. Exactly that card disappears and the two others remain.
+2. Remove the others, then reload: all three return because the host builds the initial Source again.
+
+## Change it and check yourself
+
+Add a fourth tuple to `CARDS` and a matching branch in `icon`. Give the tuple a new Source label, then reload and remove it.
+
+**Answer:** four cards appear and removal still targets one label. Reusing another card’s label would not give it an independent stable identity.
+
+## The same example across stages
+
+At the later binding stage, b08 and c08 wrap related Source operations in named Logic and combine them with Data. For values that merely change geometry/text, b07 replaces repeated Source writes with pointers; removing structure still uses Source operations.
+
+## Limits and next step
+
+Changes are local, not persisted or synchronized to a server. The cards are Source-only; the button declaration is a later inline-behavior layer. The installed companion Logic is empty here.
+
+Continue with [e11 · Static report](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/11_static_report.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/html_svg/11_static_report.md

@@ -1,9 +1,42 @@
 # 11 · Static report
 
-A summary, SVG bar chart, visible legend and table from one dataset.
+A report with a summary, chart and table, all built from the same data. You learn how to reuse those values to create consistent views.
 
-Page methods build each section. Chart lengths and exact figures derive from the same local values.
+**Uses:** Source and native HTML/SVG — core 0.1.x. No Data binding.
 
-**Try it:** Add a region, then check summary, legend, chart and table.
+<details>
+<summary>More detail</summary>
 
-**Limit:** The report has no data service or live refresh.
+
+**Release stage:** Source foundation (core 0.1.x); maintained syntax is used here.
+
+**Goal:** Keep a summary, chart and table consistent with one dataset.
+
+**Before this lesson:** [e05 · Tables](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/05_tables.md), [e08 · SVG shapes](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/08_svg_shapes.md), [e09 · SVG composition](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/09_svg_composition.md). These prerequisites support the release sequence; later comparisons are explicitly labelled below.
+
+**Open and edit:** select **e11 · Static report** 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
+
+`REGIONS` drives the summary, SVG bars, legend and table. Initially North = 12, South = 9 and West = 15, total 36. Each bar width is `value * 23`; the label’s position also uses that value. The SVG title is separate literal text.
+
+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. Check the total 36 and region count 3.
+2. Compare the longest bar with the table: West has 15, so its bar is 345 viewBox units wide.
+
+## Change it and check yourself
+
+Change North from 12 to 14. Update the literal SVG title from “North 12” to “North 14”, then reload.
+
+**Answer:** total 38, still three regions, and North’s bar width 322. The visible table/chart recompute from the tuple; the accessible title needed an explicit edit because it is literal.
+
+## Limits and next step
+
+This is a static report. Do not call it a live data service, and do not leave the accessible description stale when changing its dataset.
+
+Continue with [e12 · Complete page](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/12_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>