@gramlot/gramlot-examples 0.2.11 → 0.2.14

package/src/gramlot_examples/pages/html_svg/12_complete_page.md

@@ -1,9 +1,46 @@
 # 12 · A complete page
 
-An event page with schedule, speakers, schematic map and FAQ.
+A complete event page that combines the HTML and SVG pieces from this section. You learn how to organize a larger page into small building methods. Later, **Complete page with binding** makes the same page follow shared Data.
 
-Page methods divide the sections; nested loops compose rows, speaker cards and map labels from local data.
+**Uses:** Source and native HTML/SVG — core 0.1.x. No Data binding.
 
-**Try it:** Add a session, speaker and FAQ, then add a map stop.
+<details>
+<summary>More detail</summary>
 
-**Limit:** The event content is illustrative; there is no booking or routing service.
+
+**Release stage:** Source foundation (core 0.1.x); maintained syntax is used here.
+
+**Goal:** Assemble a complete static page from already understood Source sections.
+
+**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), [e07 · Native disclosure](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/07_native_disclosure.md), [e09 · SVG composition](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/09_svg_composition.md), [e11 · Static report](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/11_static_report.md). These prerequisites support the release sequence; later comparisons are explicitly labelled below.
+
+**Open and edit:** select **e12 · Complete 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
+
+`main` calls helpers for header, hero, highlights, schedule, speakers, map and FAQ. The schedule and speaker cards read local tuples. Native anchor links connect the navigation to section IDs; the map is an SVG illustration.
+
+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. Follow Schedule and count three sessions; Speakers shows Mira and Theo.
+2. Open the FAQ about the map: it says the map is not interactive. There is no booking action.
+
+## Change it and check yourself
+
+Add a fourth session tuple, then change the table caption from “Three short sessions” to “Four short sessions”.
+
+**Answer:** four rows appear after reload; the caption requires its own edit because it is literal. Adding a speaker to a session does not automatically add a speaker card: `SPEAKERS` is a separate dataset.
+
+## The same example across stages
+
+Keep this page as the earlier stage. In **0.2.0**, [b11 · Complete page with binding](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/11_complete_page.md) revisits the event page: one Data title drives multiple texts, one speaker flag controls both row and card, and one FAQ flag controls every answer. These shared pointers eliminate separate update code for each destination; the new controls make the later page richer rather than universally shorter.
+
+## Limits and next step
+
+“Complete” means a composed example of the features at this stage, not a booking application or coverage of all Gramlot APIs.
+
+Continue with [e13 · Live Source playground](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/html_svg/13_live_source.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/13_live_source.md

@@ -1,18 +1,49 @@
 # 13 · Live Source playground
 
-Try the buttons: add list items, remove the last one, clear the list and change
-the heading. Builder.wrapSource creates new elements; Source node and Bag methods
-update or remove them. The renderer updates only the affected DOM branches.
-
-The SVG circle moves because a short script calls setInterval every 50 ms and
-changes its Source cx attribute. Change its color while it moves. Remove animation
-deletes the entire section and runs the renderer.onDispose callback, clearing the
-timer. Disposing the page also clears it. Reload restores the initial content.
-
-Python and JavaScript pages declare the same structure and browser actions.
-Named Source paths make the target of each operation explicit. Methods divide
-the page into sections and loops construct the initial items and buttons.
-
-This example demonstrates live Source, not Data binding, persistence or server
-synchronization. Its scripts and actions run in every gallery command, and in the
-static gallery of `gramlot-serverless gallery <folder>` opened from disk, offline.
+A playground for adding, removing and changing parts of a running page, including a small SVG animation. You learn how Source changes affect the screen and why a timer must stop when its page is removed. Try this after **Events** and **Lifecycle**.
+
+**Uses:** Live Source and browser actions (0.2.0), with the `src` name from 0.2.10. No Data binding.
+
+<details>
+<summary>More detail</summary>
+
+
+**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:** Separate live Source changes from Data reactivity and release an owned timer.
+
+**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), [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 **e13 · Live Source playground** 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
+
+Buttons declare browser actions on Source: `wrapSource(...).li(...)` adds an item; `popNode`/`clear` remove children; `setValue` changes text; `setAttr` changes the circle. They never build application DOM directly.
+
+The authored script schedules a 50 ms interval updating the Source `cx`. `renderer.onDispose(motion, ...)` clears it when its section is removed. The script is browser JavaScript, including when declared by Python; the Logic class in the module is empty.
+
+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 two list items. Add one: expect three. Remove last: expect two. Clear list: expect none.
+2. Change heading: it becomes “Source is alive!”. Change ball color while it moves.
+3. Remove animation: the entire motion section disappears and its disposal callback clears the interval. Reload restores the original list and animation.
+
+## Change it and check yourself
+
+Change the interval delay from 50 to 100 ms in the authored script. Keep the same `onDispose` cleanup.
+
+**Answer:** updates occur about half as often; the position still depends on elapsed time, so the motion becomes less smooth, not half-speed. Removing the section must still release the interval.
+
+## The same example across stages
+
+In **0.2.0**, [b07 · Bound SVG](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/07_bound_svg.md) makes geometry follow Data (`r="^.radius"`), while c02 supplies declarative timing for a controller. A repeated task can then use `_timing` with lifecycle managed by its provider. That reduces timer/setup/cleanup code for that task; it does not mean the existing Source animation has secretly become a binding.
+
+## Limits and next step
+
+This advanced bridge uses a Source script and inline actions, so it is not a pure 0.1.x executable snapshot. No Data persistence or server synchronization is present. Do not copy the timer without its cleanup.
+
+Continue with [b01 · Pointers](https://github.com/gramlot-org/gramlot-examples/blob/main/src/gramlot_examples/pages/binding/01_pointers.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/README.md

@@ -1,5 +1,17 @@
 # HTML / SVG
 
+Build pages from text, lists, tables, forms and drawings, then combine those pieces into a complete page.
+
+**This section uses only Source to declare native HTML and SVG: the core 0.1.x foundation, before Data binding and controllers.** Forms already allow typing and Reset because those are browser features.
+
+Start with **Hello World**. The Binding section later revisits the same forms, drawings and complete page to show what binding adds.
+
+**Later follow-ups:** the × buttons in **Cards with icons** and the **Live Source playground** use browser actions from 0.2.0 and the `src` name from 0.2.10. Return to these parts after **Events** and **Lifecycle**.
+
+<details>
+<summary>More detail</summary>
+
+
 Learn to build a page with Gramlot: each instruction adds an element, and nested instructions describe its structure.
 
 Start with **Hello World**, then explore text, lists, tables and form controls. Continue with SVG shapes and combine them with HTML. The final examples use methods and loops to compose larger pages from simple parts.
@@ -8,3 +20,27 @@ Compare each preview with its code, then try the small change suggested in the e
 
 Finish with **Live Source playground**: change the page while it is running and
 watch a small SVG animation driven by Source attributes. The live examples also run in the static gallery of `gramlot-serverless gallery <folder>`, opened from disk, offline.
+
+## Prerequisites within the release sequence
+
+Start with e01/e03 for structure. HTML details (e02/e04/e05/e06/e07) and
+SVG (e08/e09/e11) are optional branches. e10/e13 are advanced live Source lessons:
+read c07's event explanation first and learn removal/cleanup before adapting the
+animation. A loop in main builds Source once; it is not reactive Data. See the
+[release-by-release route](https://github.com/gramlot-org/gramlot/blob/main/docs/public/025-try.md#gc-025-015). Prerequisites support the
+chronological sequence; they do not replace it. The maintained files may use
+later APIs, so they are not snapshots of the earliest release.
+
+## How to work through a lesson
+
+Read its core release stage first, then its goal and prerequisites. Open the
+existing preview, predict the guided result, and only then try the source-change
+exercise in your own editable page. Each exercise includes an answer. Follow
+"The same example across stages" links to compare earlier/later declarations;
+keep both stages visible. A newer interactive page can contain more total code
+while requiring less explicit state synchronization or request coordination.
+
+e10/e13 contain inline actions/scripts; their empty Logic class is not the source
+of those actions. They are advanced bridges to the 0.2.0 behavior lessons.
+
+</details>