@gramlot/gramlot-examples 0.2.15 → 0.3.0

package/src/gramlot_examples/gallery/gallery-page.js

@@ -16,20 +16,50 @@ export class GalleryPage extends IndexPage {
         intro.p('This gallery shows each example page beside the code that creates it. ' +
             'The Python and JavaScript integrations have the same examples.');
         intro.p('Choose an example from the list. Its tab stays open so you can return to it. ' +
-            'Enable Keyboard navigation in the footer to move through tabs by keyboard. ' +
-            'Drag the dividers to resize the sidebar or the preview and code. ' +
-            'Choose Base or Compact independently of the color mode.');
+            'Open Settings (⚙) in the footer and enable Keyboard navigation to move through tabs by keyboard. ' +
+            'Use the top bar to show or hide Navigation and Code; drag their dividers to resize them. ' +
+            'Choose Base, Compact, mimi or joanna independently of the color mode.');
 
     }
     groupPanel(pane, group) { pane.div(group.readme, {id: `readme-${group.key}`}); }
     footer(footer) {
-        super.footer(footer);
-        const inspector = footer.button({type: 'button', id: 'gallery-inspector', class: 'gallery-inspector',
+        footer.html_button('⚙', {type: 'button', id: 'gallery-settings-toggle', class: 'gallery-settings-toggle',
+            title: 'Settings', aria_label: 'Settings', popovertarget: 'gallery-settings'});
+        const settings = footer.div({id: 'gallery-settings', popover: 'auto', aria_labelledby: 'gallery-settings-title'});
+        const heading = settings.div({class: 'gallery-settings-heading'});
+        heading.h2('Settings', {id: 'gallery-settings-title'});
+        heading.html_button('×', {type: 'button', aria_label: 'Close settings', popovertarget: 'gallery-settings', popovertargetaction: 'hide'});
+        super.footer(settings);
+        const labels = settings.div({class: 'index-theme'});
+        labels.html_label('Label position', {for: 'gallery-label-position'});
+        const position = labels.select({id: 'gallery-label-position', value: 'example'});
+        position.option('As in the example', {value: 'example', selected: true});
+        for (const code of ['TL', 'TC', 'TR', 'L', 'R', 'BL', 'BC', 'BR']) position.option(code, {value: code});
+        settings.p("Label position applies to input components in the previews. Choose As in the example to restore the lesson's layout.");
+        const inspector = footer.html_button({type: 'button', id: 'gallery-inspector', class: 'gallery-inspector',
             title: 'Open inspector', aria_label: 'Inspector', aria_pressed: 'false', disabled: true});
         inspector.span('🔍', {aria_hidden: 'true'});
 
     }
-    behavior(shell) { shell.script({src: this.constructor.galleryScript}); }
+    header(shell) {
+        const header = shell.header({class: 'gallery-toolbar'});
+        header.html_button('☰ Navigation', {type: 'button', id: 'index-navigation-toggle',
+            aria_controls: 'index-sidebar', aria_expanded: 'true'});
+        header.h1(this.constructor.title);
+        header.html_button('Code ⟨/⟩', {type: 'button', id: 'index-code-toggle',
+            aria_controls: 'index-code', aria_expanded: 'false', disabled: true});
+    }
+    behavior(shell) {
+        shell.div({class: 'index-divider', id: 'index-code-divider', hidden: true,
+            title: 'Drag to resize code', role: 'separator', aria_orientation: 'vertical',
+            tabindex: 0, aria_label: 'Resize code', aria_controls: 'index-code',
+            aria_valuemin: 200, aria_valuemax: 800, aria_valuenow: 420});
+        const code = shell.aside({id: 'index-code', aria_label: 'Example source code', hidden: true});
+        for (const family of this.constructor.navigation) {
+            for (const example of family.children) this.codePanel(code, example);
+        }
+        shell.script({src: this.constructor.galleryScript});
+    }
 
     panel(parent, example) {
         const key = example.key;
@@ -38,21 +68,23 @@ export class GalleryPage extends IndexPage {
         const explanation = panel.header({class: 'gallery-explanation'});
         explanation.div(example.readme, {id: `readme-${key}`});
 
-        const split = panel.div({class: 'gallery-split', id: `split-${key}`,
-            style: '--split-position: 65%'});
-        const preview = split.div({class: 'gallery-preview', id: `preview-${key}`});
-        preview.iframe({title: `${example.title} preview`, name: `example-${key}`,
+        const preview = panel.div({class: 'gallery-preview', id: `preview-${key}`});
+        const modes = preview.div({class: 'gallery-preview-modes', role: 'group', aria_label: 'Preview mode'});
+        for (const [mode, caption] of [['normal', 'Normale'], ['mobile', 'Mobile']]) {
+            modes.html_button(caption, {type: 'button', id: `preview-${mode}-${key}`, aria_pressed: mode === 'normal' ? 'true' : 'false'});
+        }
+        const stage = preview.div({class: 'gallery-preview-stage', id: `preview-stage-${key}`});
+        stage.iframe({title: `${example.title} preview`, name: `example-${key}`,
             id: `frame-${key}`});
-        split.div({class: 'gallery-divider', id: `divider-${key}`,
-            role: 'separator', aria_orientation: 'vertical', tabindex: 0,
-            aria_label: 'Resize preview and code', aria_valuemin: 20,
-            aria_valuemax: 80, aria_valuenow: 65});
-        const codepane = split.div({class: 'gallery-codepane', id: `codepane-${key}`});
+    }
+    codePanel(parent, example) {
+        const key = example.key;
+        const codepane = parent.div({class: 'gallery-codepane', id: `codepane-${key}`, hidden: true});
         const tabs = codepane.div({class: 'gallery-source-tabs', role: 'tablist', aria_label: 'Source files'});
-        tabs.button('JavaScript', {title: `${example.folder}.js`, type: 'button', role: 'tab',
+        tabs.html_button('JavaScript', {title: `${example.folder}.js`, type: 'button', role: 'tab',
             id: `code-tab-${key}`, aria_controls: `code-panel-${key}`, aria_selected: 'true', tabindex: 0});
         if (example.logic != null) {
-            tabs.button('logic.js', {hidden: true, title: `${example.folder}_aux.js`, type: 'button', role: 'tab',
+            tabs.html_button('logic.js', {hidden: true, title: `${example.folder}_aux.js`, type: 'button', role: 'tab',
                 id: `logic-tab-${key}`, aria_controls: `logic-panel-${key}`, aria_selected: 'false', tabindex: -1});
         }
         codepane.pre({id: `code-panel-${key}`, role: 'tabpanel', aria_labelledby: `code-tab-${key}`, tabindex: 0})

package/src/gramlot_examples/gallery/gallery.css

@@ -1,3 +1,25 @@
+/* The source viewer is a sibling of navigation and content, never an iframe overlay. */
+#gallery.index-shell {
+  grid-template-rows: auto minmax(0, 1fr) auto;
+  grid-template-columns: var(--navigation-size, min(var(--sidebar-width, 240px), 60vw))
+    var(--navigation-divider, 8px) minmax(0, 1fr) var(--code-divider, 0px) var(--code-size, 0px);
+}
+.gallery-toolbar { grid-column: 1 / -1; grid-row: 1; display: flex; align-items: center;
+  gap: .6rem; padding: .35rem .6rem; background: var(--gramlot-surface-subtle);
+  border-block-start: 3px solid var(--gramlot-brand-yellow); border-block-end: 1px solid var(--gramlot-border); }
+.gallery-toolbar h1 { flex: 1; min-inline-size: 0; margin: 0; font-size: 1rem;
+  text-align: center; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.gallery-toolbar button { margin: 0; padding: .25rem .5rem; min-block-size: 28px; font-size: .875rem; }
+#gallery > .index-sidebar { grid-column: 1; grid-row: 2; border-block-start: 0; }
+#gallery > .index-sidebar header h1 { display: none; }
+#gallery > #index-sidebar-divider { grid-column: 2; grid-row: 2; }
+#gallery > .index-main { grid-column: 3; grid-row: 2; }
+#gallery > #index-code-divider { grid-column: 4; grid-row: 2; }
+#index-code { grid-column: 5; grid-row: 2; min-inline-size: 0; min-block-size: 0; overflow: hidden; background: #1e1e1e; }
+#gallery > .index-footer { grid-row: 3; }
+#gallery[data-navigation-hidden="true"] { --navigation-size: 0px; --navigation-divider: 0px; }
+#gallery[data-code-visible="true"] { --code-size: min(var(--code-width, 420px), 60vw); --code-divider: 8px; }
+#gallery [hidden] { display: none; }
 .gallery-panel { block-size: 100%; min-block-size: 0; display: grid; grid-template-rows: auto minmax(0, 1fr); }
 .gallery-explanation { max-block-size: 28dvh; overflow: auto; padding: .5rem .75rem; background: var(--gramlot-surface); border-block-end: 1px solid var(--gramlot-border); font-size: 1rem; }
 .gallery-explanation h1 { font-size: 1.25rem; margin-block: 0 .35rem; }
@@ -7,11 +29,10 @@
 .gallery-explanation :last-child { margin-block-end: 0; }
 .gallery-description { font-weight: 600; }
 .gallery-resources { display: flex; gap: .6rem; font-size: .95rem; }
-.gallery-split { min-inline-size: 0; min-block-size: 0; display: grid; grid-template-columns: minmax(0, calc(var(--split-position) - 4px)) 8px minmax(0, 1fr); background: var(--gramlot-surface); }
 .gallery-preview { min-inline-size: 0; min-block-size: 0; overflow: hidden; }
 .gallery-preview iframe { display: block; inline-size: 100%; block-size: 100%; min-block-size: 0; border: 0; background: var(--gramlot-surface); }
-.gallery-codepane { min-inline-size: 0; min-block-size: 0; display: grid; grid-template-rows: auto minmax(0, 1fr); background: #1e1e1e; }
-.gallery-codepane pre { min-inline-size: 0; min-block-size: 0; margin: 0; padding: .4rem .4rem .4rem 0; border: 0; border-radius: 0; overflow: auto; font: 12px/1.4 var(--gramlot-font-code); background: #1e1e1e; color: #dcdcdc; }
+.gallery-codepane { block-size: 100%; min-inline-size: 0; min-block-size: 0; display: grid; grid-template-rows: auto minmax(0, 1fr); background: #1e1e1e; }
+.gallery-codepane pre { min-inline-size: 0; min-block-size: 0; margin: 0 8px 8px; padding: 12px 16px 16px 10px; border: 0; border-radius: 0; overflow: auto; font: 11px/1.5 var(--gramlot-font-code); background: #1e1e1e; color: #dcdcdc; }
 .gallery-codepane code { white-space: pre; font-size: inherit; }
 .gallery-codepane .hljs { color: #dcdcdc; counter-reset: code-line; }
 .gallery-codepane .code-line::before { counter-increment: code-line; content: counter(code-line); display: inline-block; inline-size: 2.5em; margin-inline-end: .75em; padding-inline-end: .25em; text-align: end; color: #6e7681; user-select: none; }
@@ -28,7 +49,7 @@
 .gallery-codepane :is(.hljs-attr, .hljs-attribute) { color: #9cdcfe; }
 .gallery-codepane > pre[hidden] { display: none; }
 .gallery-source-tabs { display: flex; min-inline-size: 0; overflow-x: auto; background: #2d2d30; }
-.gallery-source-tabs button { flex: none; min-block-size: 28px; margin: 0; padding: .2rem .6rem; border: 0; border-radius: 0; background: transparent; color: #ccc; font: 600 12px/1.35 var(--gramlot-font-code); white-space: nowrap; }
+.gallery-source-tabs button { flex: none; min-block-size: 28px; margin: 0; padding: .2rem .6rem; border: 0; border-radius: 0; background: transparent; color: #ccc; font: 600 11px/1.35 var(--gramlot-font-code); white-space: nowrap; }
 .gallery-source-tabs button[aria-selected="true"] { background: #1e1e1e; color: #fff; box-shadow: inset 0 2px var(--gramlot-brand-blue); }
 .gallery-source-tabs button:focus-visible { outline: 2px solid var(--gramlot-focus-ring); outline-offset: -2px; }
 .gallery-source-tabs button[hidden] { display: none; }
@@ -37,3 +58,28 @@
 .gallery-inspector:hover { background: var(--gramlot-surface); }
 .gallery-inspector:focus-visible { outline: 2px solid var(--gramlot-focus-ring); outline-offset: 2px; }
 .gallery-inspector[aria-pressed="true"] { background: var(--gramlot-action); color: var(--gramlot-navigation-text); }
+
+/* Native popover keeps settings out of both the footer and lesson layout. */
+.gallery-settings-toggle { inline-size: 28px; block-size: 28px; min-block-size: 28px;
+  padding: 0; margin: 0; border: 0; background: transparent; color: inherit; font-size: 18px; }
+#gallery-settings { inset: auto auto 42px 10px; margin: 0; box-sizing: border-box;
+  inline-size: min(320px, calc(100vw - 20px)); max-block-size: calc(100dvh - 60px); overflow: auto;
+  padding: 12px; border: 1px solid var(--gramlot-border); border-radius: var(--gramlot-radius);
+  background: var(--gramlot-surface); color: var(--gramlot-ink); box-shadow: 0 4px 20px #0003; }
+#gallery-settings:popover-open { display: grid; gap: 10px; }
+.gallery-settings-heading { display: flex; align-items: center; justify-content: space-between; gap: 8px; }
+.gallery-settings-heading h2 { margin: 0; font-size: 1rem; }
+.gallery-settings-heading button { padding: 0 6px; min-block-size: 24px; font-size: 1rem; }
+#gallery-settings .index-theme { display: grid; gap: 4px; }
+#gallery-settings .index-theme select { inline-size: 100%; }
+#gallery-settings .index-install { order: 2; }
+#gallery-settings .index-install[open] { position: static; }
+#gallery-settings p { margin: 0; font-size: .85rem; line-height: 1.4; }
+
+/* Resize the existing preview; switching modes never replaces the iframe. */
+.gallery-preview{display:grid;grid-template-rows:auto minmax(0,1fr)}
+.gallery-preview-modes{display:flex;gap:4px;border-block-end:1px solid var(--gramlot-border);background:var(--gramlot-surface)}
+.gallery-preview-modes button{font:inherit;font-size:12px;background:transparent;color:var(--gramlot-text-secondary);border:0;border-radius:0;border-block-end:2px solid transparent;padding:5px 12px;min-block-size:28px}
+.gallery-preview-modes button[aria-pressed=true]{color:var(--gramlot-action);border-block-end-color:currentColor}
+.gallery-preview-stage{min-block-size:0;min-inline-size:0;overflow:hidden;background:var(--gramlot-surface-subtle);display:flex;justify-content:center}
+.gallery-preview-stage[data-preview-mode=mobile] iframe{inline-size:390px;max-inline-size:100%;flex:none;border-inline:1px solid var(--gramlot-border)}

package/src/gramlot_examples/index.js

@@ -1,3 +1,4 @@
+import {collections} from './gallery/collections.js';
 /** Gramlot example pages, the gallery page and its catalogue. */
 import {existsSync, readFileSync} from 'node:fs';
 import {basename, extname, join} from 'node:path';
@@ -6,7 +7,7 @@ import {fileURLToPath} from 'node:url';
 const PACKAGE = fileURLToPath(new URL('./', import.meta.url));
 const MEDIA_TYPES = {'.css': 'text/css', '.svg': 'image/svg+xml', '.png': 'image/png', '.json': 'application/json'};
 const SUFFIXES = ['.py', '.js', '.css', '.md', '_aux.js'];
-const DIST = ['gallery.js', 'frame.js', 'notices.json', 'LICENSE', 'NOTICE'];
+const DIST = ['gallery.js', 'frame.js', 'inputs.js', 'layout.js', 'notices.json', 'LICENSE', 'NOTICE'];
 
 /** Media type of a gallery asset; only the built gallery scripts are served as JavaScript. */
 function mediaType(path, script = false) {
@@ -77,5 +78,5 @@ export function buildGallery({catalogs = []} = {}) {
             }
         }
     }
-    return {families, routes, assets};
+    return {families, routes, assets, collections};
 }

package/src/gramlot_examples/pages/README.md

@@ -1,17 +1,20 @@
 # Gramlot examples
 
 The [gallery](https://github.com/gramlot-org/gramlot-examples/blob/main/docs/010-gallery.md) presents the same examples in Python and
-JavaScript, in three families:
+JavaScript, in four families:
 
 - [`html_svg/`](html_svg/): thirteen HTML and SVG pages, without binding.
 - [`binding/`](binding/): eleven pages whose DOM follows the Data through pointers,
   editing, booleans, style, SVG and freeze. The last three take the content of
   `html_svg` examples 06, 08 and 12 and add the binding.
-- [`controllers/`](controllers/): seventeen pages with formulas, controllers, named
+- [`controllers/`](controllers/): twenty-two pages with formulas, controllers, named
   logic in the `Logic` class of the page module, inline expressions, node methods, buttons,
   events, the end-to-end story, `dataRpc` calls to the endpoints of the page, `remote`
   fragments and `dataRemote` values.
 
+- [`components/`](components/): twenty-five lessons for inputs, labelbox, layout,
+  command buttons and validation, with compact desktop/touch presentation.
+
 Each example is a file page: `NN_name.py`, its JavaScript equivalent `NN_name.js`,
 its README `NN_name.md`, and where needed a same-name stylesheet `NN_name.css`.
 `NN_name.js` exports `Page` and `Logic`: the JavaScript page uses both, the Python

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/binding/09_forms.js

@@ -56,7 +56,7 @@ export class Page extends BasePage {
         options.input({type: 'text', id: 'unavailable', value: 'Disabled', disabled: true});
         options.html_label('Attachment', {for: 'attachment'});
         options.input({type: 'file', id: 'attachment', name: 'attachment'});
-        form.button('Submit unavailable', {type: 'submit', disabled: true});
+        form.html_button('Submit unavailable', {type: 'submit', disabled: true});
 
         const record = layout.aside({class: 'card stack'});
         record.h2('The Data record');

package/src/gramlot_examples/pages/components/01_textbox.js

@@ -0,0 +1,32 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static devices = ['desktop', 'tablet', 'phone'];
+    static title = "Textbox and labelbox";
+    static css = ["/themes/gramlot-base/theme.css"];
+
+    main(root) {
+        const pane = root.main({class: "example-page stack"});
+        pane.h1("One value, two textboxes");
+        pane.p("Type in either field. Both share the same Data value.");
+        const controls = pane.formlet({class: "card stack", width: "100%", max_width: "24rem"});
+        controls.html_label("Label position", {for: "position"});
+        const position = controls.select({id: "position", value: "^position", width: "8rem", max_width: "100%"});
+        for (const code of ["TL", "TC", "TR", "L", "R", "BL", "BC", "BR"]) {
+            position.option(code, {value: code});
+        }
+        controls.checkbox({value: "^live", lbl: "Editing", label: "Update while typing"});
+        controls.checkbox({value: "^readonly", lbl: "State", label: "Read only"});
+        const fields = pane.formlet({class: "card stack", width: "100%", max_width: "32rem"});
+        fields.textbox({id: "customer", value: "^customer", lbl: "Customer", lbl_position: "^position", live: "^live", readonly: "^readonly", placeholder: "Enter a name", lbl_color: "#315fa8", box_padding: "8px", box_l_padding: "4px", box_c_width: "240px"});
+        fields.textbox({id: "customer-copy", value: "^customer", lbl: "Same customer", live: "^live", readonly: "^readonly"});
+        pane.h2("The Data");
+        pane.p("^customer", {id: "customer-value"});
+        for (const [path, value] of [["customer", "Ada"], ["position", "TL"], ["live", true], ["readonly", false]]) {
+            pane.dataSetter({destination_path: path, value});
+        }
+    }
+}
+
+/** This page needs no named client methods. */
+export class Logic {}

package/src/gramlot_examples/pages/components/01_textbox.md

@@ -0,0 +1,14 @@
+# 01 · Textbox and labelbox
+
+Two textboxes share a customer name. Type in either one, switch live editing off and on, and move the label without rebuilding the field.
+
+**Uses:** the first 0.3 input components, shared labelbox, Source, Data and bindings. No endpoints or validation engine.
+
+<details>
+<summary>More detail</summary>
+
+`lbl_` styles the label; `box_` styles the whole labelbox. `box_l_` and `box_c_` address its label and control containers. Read only stops editing while Data updates can still reach the field.
+
+**Try it:** choose each of `TL`, `TC`, `TR`, `L`, `R`, `BL`, `BC`, `BR`. The default is `TL`. Open the inspector to see the same values in Data.
+
+</details>

package/src/gramlot_examples/pages/components/02_checkbox.js

@@ -0,0 +1,25 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = "Checkbox and labelbox";
+    static css = ["/themes/gramlot-base/theme.css"];
+
+    main(root) {
+        const pane = root.main({class: "example-page stack"});
+        pane.h1("A boolean value");
+        pane.p("lbl names the field; label is the caption beside its checkbox.");
+        const fields = pane.formlet({class: "card stack", width: "100%", max_width: "32rem"});
+        fields.checkbox({id: "newsletter", value: "^newsletter", lbl: "Contact preferences", label: "Send me the newsletter", lbl_color: "#315fa8", box_padding: "8px", disabled: "^locked"});
+        fields.checkbox({id: "newsletter-copy", value: "^newsletter", lbl: "Same preference", label: "Newsletter", disabled: "^locked"});
+        const controls = pane.formlet({class: "card stack", width: "100%", max_width: "24rem"});
+        controls.checkbox({value: "^locked", lbl: "State", label: "Disable the preference"});
+        pane.p("Subscribed", {hidden: "^newsletter:=!{}", id: "subscribed"});
+        pane.p("Not subscribed", {hidden: "^newsletter", id: "not-subscribed"});
+        for (const [path, value] of [["newsletter", false], ["locked", false], ]) {
+            pane.dataSetter({destination_path: path, value});
+        }
+    }
+}
+
+/** This page needs no named client methods. */
+export class Logic {}

package/src/gramlot_examples/pages/components/02_checkbox.md

@@ -0,0 +1,14 @@
+# 02 · Checkbox and labelbox
+
+Two checkboxes share one boolean preference. Click either caption, then disable both using the State checkbox.
+
+**Uses:** the first 0.3 input components, shared labelbox, Source, Data and bindings. No endpoints or validation engine.
+
+<details>
+<summary>More detail</summary>
+
+`lbl` names the field; `label` is the caption beside the checkbox. The stored value is `True`/`False` in Python and `true`/`false` in JavaScript.
+
+**Try it:** click either checkbox and inspect the shared boolean in Data. For layout variants, use Settings (⚙) in the gallery footer.
+
+</details>

package/src/gramlot_examples/pages/components/03_radio_button_text.js

@@ -0,0 +1,30 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = "RadioButtonText and labelbox";
+    static css = ["/themes/gramlot-base/theme.css"];
+
+    main(root) {
+        const pane = root.main({class: "example-page stack"});
+        pane.h1("One code for each group");
+        pane.p("Choose a delivery option: the Data stores its code, not its caption. The second group has its own value. Arrow keys move between options.");
+        const controls = pane.formlet({class: "card stack", width: "100%", max_width: "24rem"});
+        controls.html_label("Columns (1–3): ", {for: "columns"}).span("^columns", {id: "columns-value"});
+        controls.input({id: "columns", type: "range", min: 1, max: 3, value: "^columns", live: true, width: "16rem", max_width: "100%"});
+        const fields = pane.formlet({class: "card stack", width: "100%", max_width: "36rem"});
+        const choices = "standard:Standard,express:Express,pickup:Pick up";
+        fields.radioButtonText({id: "shipping", value: "^shipping", values: choices, lbl: "Delivery", cols: "^columns", lbl_color: "#315fa8", box_padding: "8px"});
+        fields.radioButtonText({id: "alternative", value: "^alternative", values: choices, lbl: "Alternative delivery", cols: 3, box_padding: "8px"});
+        const facts = pane.dl();
+        facts.dt("Delivery code");
+        facts.dd("^shipping", {id: "shipping-value"});
+        facts.dt("Alternative code");
+        facts.dd("^alternative", {id: "alternative-value"});
+        for (const [path, value] of [["shipping", "standard"], ["alternative", "pickup"], ["columns", 3]]) {
+            pane.dataSetter({destination_path: path, value});
+        }
+    }
+}
+
+/** This page needs no named client methods. */
+export class Logic {}

package/src/gramlot_examples/pages/components/03_radio_button_text.md

@@ -0,0 +1,16 @@
+# 03 · RadioButtonText and labelbox
+
+Choose one delivery option in each group. Change the column count, and try the arrow keys inside a group.
+
+**Uses:** the first 0.3 input components, shared labelbox, Source, Data and bindings. No endpoints or validation engine.
+
+<details>
+<summary>More detail</summary>
+
+`values="standard:Standard,express:Express,pickup:Pick up"` separates stored codes from visible captions. Each group writes only its own Data path; `cols` and `lbl_position` can follow pointers.
+
+The controls stay above the groups so changing the number of rows does not move the slider while you drag it. The number beside **Columns** shows the current Data value, from 1 to 3.
+
+**Try it:** click either checkbox and inspect the shared boolean in Data. For layout variants, use Settings (⚙) in the gallery footer.
+
+</details>

package/src/gramlot_examples/pages/components/04_text_box_area.js

@@ -0,0 +1,23 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = "Multiline text and labelbox";
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const pane = root.main({class: 'example-page stack'});
+        pane.h1("Multiline text and labelbox");
+        pane.p("Two multiline fields share one note. Switch live editing and move the label while keeping the text and selection.");
+        const controls = pane.formlet({class: "card stack", width: "100%", max_width: "24rem"});
+        controls.checkbox({id: "live", value: "^live", lbl: "Editing", label: "Update while editing"});
+        controls.checkbox({id: "locked", value: "^locked", lbl: "State", label: "Disable controls"});
+        const fields = pane.formlet({class: "card stack", width: "100%", max_width: "24rem"});
+        fields.textBoxArea({id: "notes", value: "^notes", lbl: "Notes", rows: 4, cols: 24,
+            placeholder: "Write a few lines", live: "^live", disabled: "^locked", box_padding: "8px"});
+        fields.textBoxArea({id: "notes-copy", value: "^notes", lbl: "Same notes", rows: 3, cols: 24, live: "^live", disabled: "^locked"});
+        for (const [path, value] of [["notes", "First line\nSecond line"], ["locked", false], ["live", true]]) pane.dataSetter({destination_path: path, value});
+    }
+}
+
+/** This page needs no named client methods. */
+export class Logic {}

package/src/gramlot_examples/pages/components/04_text_box_area.md

@@ -0,0 +1,14 @@
+# 04 · Multiline text and labelbox
+
+Two multiline fields share one note. Switch live editing and move the label while keeping the text and selection.
+
+**Uses:** the 0.3 input collection, shared labelbox, Source, Data and bindings. No endpoint calls, stores or validation engine.
+
+<details>
+<summary>More detail</summary>
+
+`textBoxArea` wraps a native textarea; `rows` and `cols` set its visible size. With live editing off, leave the field to commit. With it on, the second field follows each edit. Native `textarea` remains available in the earlier HTML lessons.
+
+All controls use `lbl`, reactive `lbl_position` (TL by default), and the shared `lbl_`/`box_` style prefixes. Disable the controls to compare their common behavior. Label layout variants are in Settings (⚙) in the gallery footer.
+
+</details>

package/src/gramlot_examples/pages/components/05_passwordbox.js

@@ -0,0 +1,23 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = "Password and labelbox";
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const pane = root.main({class: 'example-page stack'});
+        pane.h1("Password and labelbox");
+        pane.p("Two password fields share a sample value. The browser masks the characters; changing either field updates the other.");
+        const controls = pane.formlet({class: "card stack", width: "100%", max_width: "24rem"});
+        controls.checkbox({id: "live", value: "^live", lbl: "Editing", label: "Update while editing"});
+        controls.checkbox({id: "locked", value: "^locked", lbl: "State", label: "Disable controls"});
+        const fields = pane.formlet({class: "card stack", width: "100%", max_width: "24rem"});
+        fields.passwordbox({id: "secret", value: "^secret", lbl: "Sample password", live: "^live",
+            disabled: "^locked", placeholder: "Use a sample value", box_padding: "8px"});
+        fields.passwordbox({id: "secret-copy", value: "^secret", lbl: "Same sample password", live: "^live", disabled: "^locked"});
+        for (const [path, value] of [["secret", "sample-only"], ["locked", false], ["live", true]]) pane.dataSetter({destination_path: path, value});
+    }
+}
+
+/** This page needs no named client methods. */
+export class Logic {}

package/src/gramlot_examples/pages/components/05_passwordbox.md

@@ -0,0 +1,14 @@
+# 05 · Password and labelbox
+
+Two password fields share a sample value. The browser masks the characters; changing either field updates the other.
+
+**Uses:** the 0.3 input collection, shared labelbox, Source, Data and bindings. No endpoint calls, stores or validation engine.
+
+<details>
+<summary>More detail</summary>
+
+`passwordbox` wraps a native password input. Masking changes its display, not the value in Data: this lesson uses a sample, and the inspector can read it. It has the same string, live editing and labelbox behavior as `textbox`.
+
+All controls use `lbl`, reactive `lbl_position` (TL by default), and the shared `lbl_`/`box_` style prefixes. Disable the controls to compare their common behavior. Label layout variants are in Settings (⚙) in the gallery footer.
+
+</details>

package/src/gramlot_examples/pages/components/06_radio_button.js

@@ -0,0 +1,28 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = "Single radio buttons";
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const pane = root.main({class: 'example-page stack'});
+        pane.h1("Single radio buttons");
+        pane.p("Each radio binds its own boolean. A shared group makes the choices exclusive; a separate group stays independent.");
+        const controls = pane.formlet({class: "card stack", width: "100%", max_width: "24rem"});
+        controls.checkbox({id: "locked", value: "^locked", lbl: "State", label: "Disable controls"});
+        const fields = pane.formlet({class: "card stack", width: "100%", max_width: "24rem"});
+        for (const [code, caption] of [["standard", "Standard"], ["express", "Express"], ["pickup", "Pick up"]]) {
+            fields.radioButton({id: code, value: `^${code}`, group: "delivery", label: caption,
+                lbl: caption, disabled: "^locked", box_padding: "4px"});
+        }
+        fields.radioButton({id: "independent", value: "^independent", group: "other", label: "Independent choice", lbl: "Another group", disabled: "^locked"});
+        const facts = pane.dl();
+        for (const code of ["standard", "express", "pickup", "independent"]) {
+            facts.dt(code); facts.dd(`^${code}`, {id: `${code}-value`});
+        }
+        for (const [path, value] of [["standard", true], ["express", false], ["pickup", false], ["independent", false], ["locked", false]]) pane.dataSetter({destination_path: path, value});
+    }
+}
+
+/** This page needs no named client methods. */
+export class Logic {}

package/src/gramlot_examples/pages/components/06_radio_button.md

@@ -0,0 +1,14 @@
+# 06 · Single radio buttons
+
+Each radio binds its own boolean. A shared group makes the choices exclusive; a separate group stays independent.
+
+**Uses:** the 0.3 input collection, shared labelbox, Source, Data and bindings. No endpoint calls, stores or validation engine.
+
+<details>
+<summary>More detail</summary>
+
+`radioButton` uses one boolean per control; `group` names the exclusive group within the current Source form (or page). Selecting Express writes `express=True` and clears the selected peer. Use arrow keys between choices or click the captions. Compare w03: `radioButtonText` stores one selected code instead. These are two different value contracts.
+
+All controls use `lbl`, reactive `lbl_position` (TL by default), and the shared `lbl_`/`box_` style prefixes. Disable the controls to compare their common behavior. Label layout variants are in Settings (⚙) in the gallery footer.
+
+</details>