@gramlot/gramlot-examples 0.2.15 → 0.3.0

package/src/gramlot_examples/pages/components/07_colorpicker.js

@@ -0,0 +1,24 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = "Color and labelbox";
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const pane = root.main({class: 'example-page stack'});
+        pane.h1("Color and labelbox");
+        pane.p("Choose a color in either picker. Both controls and the swatch follow the same Data value.");
+        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.colorpicker({id: "color", value: "^color", lbl: "Accent color", live: "^live", disabled: "^locked", box_padding: "8px"});
+        fields.colorpicker({id: "color-copy", value: "^color", lbl: "Same color", live: "^live", disabled: "^locked"});
+        pane.div({background_color: "^color", width: "6rem", height: "3rem", border: "1px solid #888", aria_label: "Color sample"});
+        pane.p("^color", {id: "color-value"});
+        for (const [path, value] of [["color", "#315fa8"], ["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/07_colorpicker.md

@@ -0,0 +1,14 @@
+# 07 · Color and labelbox
+
+Choose a color in either picker. Both controls and the swatch follow the same Data value.
+
+**Uses:** the 0.3 input collection, shared labelbox, Source, Data and bindings. No endpoint calls, stores or validation engine.
+
+<details>
+<summary>More detail</summary>
+
+`colorpicker` uses the native browser color dialog and a `#rrggbb` string. Live mode uses the input events the browser supplies; otherwise the value commits on change. The swatch uses ordinary Source style binding. The dialog appearance can differ between browsers.
+
+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/08_horizontal_slider.js

@@ -0,0 +1,24 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = "Horizontal slider";
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const pane = root.main({class: 'example-page stack'});
+        pane.h1("Horizontal slider");
+        pane.p("Two horizontal sliders share a numeric level. Drag or use the arrow keys; switch live editing to compare immediate and committed updates.");
+        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.horizontalSlider({id: "level", value: "^level", lbl: "Level", min: 0, max: 100, step: 5,
+            live: "^live", disabled: "^locked", box_padding: "8px"});
+        fields.horizontalSlider({id: "level-copy", value: "^level", lbl: "Same level", min: 0, max: 100, step: 5, live: "^live", disabled: "^locked"});
+        pane.p("^level", {id: "level-value"});
+        for (const [path, value] of [["level", 50], ["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/08_horizontal_slider.md

@@ -0,0 +1,14 @@
+# 08 · Horizontal slider
+
+Two horizontal sliders share a numeric level. Drag or use the arrow keys; switch live editing to compare immediate and committed updates.
+
+**Uses:** the 0.3 input collection, shared labelbox, Source, Data and bindings. No endpoint calls, stores or validation engine.
+
+<details>
+<summary>More detail</summary>
+
+`horizontalSlider` wraps a native range input. `min`, `max` and `step` define its numeric range and can also use Data pointers. The Data value is a number, not text. With live editing off, releasing the slider commits the value. Native clamping affects display and does not rewrite an out-of-range Data value by itself.
+
+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/09_vertical_slider.js

@@ -0,0 +1,24 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = "Vertical slider";
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const pane = root.main({class: 'example-page stack'});
+        pane.h1("Vertical slider");
+        pane.p("Vertical and horizontal sliders share the same level. The vertical minimum is at the bottom and the maximum at the top.");
+        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.verticalSlider({id: "level", value: "^level", lbl: "Vertical level", min: 0, max: 100, step: 5,
+            live: "^live", disabled: "^locked", box_padding: "8px"});
+        fields.horizontalSlider({id: "level-copy", value: "^level", lbl: "Same level horizontally", min: 0, max: 100, step: 5, live: "^live", disabled: "^locked"});
+        pane.p("^level", {id: "level-value"});
+        for (const [path, value] of [["level", 50], ["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/09_vertical_slider.md

@@ -0,0 +1,14 @@
+# 09 · Vertical slider
+
+Vertical and horizontal sliders share the same level. The vertical minimum is at the bottom and the maximum at the top.
+
+**Uses:** the 0.3 input collection, shared labelbox, Source, Data and bindings. No endpoint calls, stores or validation engine.
+
+<details>
+<summary>More detail</summary>
+
+`verticalSlider` shares the numeric and editing contract of `horizontalSlider`. Standard CSS writing mode gives the native range its vertical orientation; the value increases upwards. Try ArrowUp and ArrowDown, then move the label. Home/End follow the browser's native writing-mode behavior: WebKit and Chromium can select opposite endpoints. The horizontal companion shows that orientation does not change the Data value.
+
+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/10_number_textbox.js

@@ -0,0 +1,30 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = "Number editing";
+    static locale = "it-IT";
+    static css = ["/themes/gramlot-base/theme.css"];
+    async main(root) {
+        const {Bag} = await import('@gramlot/gramlot');
+        const pane = root.main({class:"example-page stack"});
+        pane.h1("Number editing");
+        pane.p("Try a comma decimal, an integer and an exact Decimal. Invalid text stays in the field without changing Data.");
+        const controls = pane.formlet({class:"card stack",width:"100%",max_width:"24rem"});
+        controls.checkbox({id:"live",value:"^live",lbl:"Editing",label:"Update while typing"});
+        controls.checkbox({id:"locked",value:"^locked",lbl:"State",label:"Read only"});
+        const fields = pane.formlet({class:"card stack",width:"100%",max_width:"24rem"});
+        fields.numberTextBox({id:"amount", value:"^amount", lbl:"Amount (0–100)", format:"0.00", min:0, max:100, live:"^live", readonly:"^locked", box_c_width:"14rem"});
+        fields.numberTextBox({id:"amount-copy", value:"^amount", lbl:"Same amount", format:"0.00", readonly:"^locked", box_c_width:"14rem"});
+        fields.numberTextBox({id:"quantity", value:"^quantity", lbl:"Integer", dtype:"L", readonly:"^locked", box_c_width:"10rem"});
+        fields.numberTextBox({id:"exact", value:"^exact", lbl:"Exact Decimal", dtype:"N", format:"0.00", readonly:"^locked", box_c_width:"16rem"});
+        pane.p("^amount", {id:"amount-value", format:"0.00", dtype:"R"});
+        pane.p("^exact", {id:"exact-value", format:"0.00", dtype:"N"});
+        pane.dataSetter({destination_path:"amount",value:12.5});
+        pane.dataSetter({destination_path:"quantity",value:3});
+        pane.dataSetter({destination_path:"exact",value:Bag.fromTytx('{"exact":"9007199254740993.25::N"}').getItem('exact')});
+        for (const [path,value] of [["live",false],["locked",false]]) pane.dataSetter({destination_path:path,value});
+    }
+}
+
+
+export class Logic {}

package/src/gramlot_examples/pages/components/10_number_textbox.md

@@ -0,0 +1,16 @@
+# 10 · Number editing
+
+Try a comma decimal, an integer and an exact Decimal. Invalid text stays in the field without changing Data.
+
+**Uses:** the 0.3 input collection, labelbox, typed Data, page locale and Gramlot formatting. No endpoint calls or validation engine.
+
+<details>
+<summary>More detail</summary>
+
+The page locale is `it-IT`: enter `38,25`, without thousands separators. The amount accepts 0–100; the integer field rejects fractions. `dtype="N"` keeps a Decimal, including digits beyond JavaScript's safe integer range. `format="0.00"` controls display, not the stored precision. In Python the initial exact value is a `Decimal`; JavaScript initializes a typed Bag with `Bag.fromTytx` and reads its Decimal.
+
+Try `38x`: it stays visible with an error while the previous Data value remains intact. Clear a field to write null. Enter or leaving the field commits a valid draft; Escape restores the last accepted value. With live editing, each complete valid input updates Data. Partial or invalid input never writes a replacement value.
+
+Make the fields read-only; try label layout variants from Settings (⚙) in the gallery footer. Both controls keep the shared labelbox contract (`lbl_` and `box_`). The cards stay within 24rem.
+
+</details>

package/src/gramlot_examples/pages/components/11_date_textbox.js

@@ -0,0 +1,23 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = "Date editing";
+    static locale = "it-IT";
+    static css = ["/themes/gramlot-base/theme.css"];
+    main(root) {
+        const pane = root.main({class:"example-page stack"});
+        pane.h1("Date editing");
+        pane.p("Enter a calendar date or a word such as oggi or domani. Two fields share one civil date.");
+        const controls = pane.formlet({class:"card stack",width:"100%",max_width:"24rem"});
+        controls.checkbox({id:"live",value:"^live",lbl:"Editing",label:"Update while typing"});
+        controls.checkbox({id:"locked",value:"^locked",lbl:"State",label:"Read only"});
+        const fields = pane.formlet({class:"card stack",width:"100%",max_width:"24rem"});
+        fields.dateTextBox({id:"date", value:"^date", lbl:"Appointment", format:"long",  live:"^live", readonly:"^locked", box_c_width:"16rem"});
+        fields.dateTextBox({id:"date-copy", value:"^date", lbl:"Same date, short display", calendar:false, format:"short",  readonly:"^locked", box_c_width:"14rem"});
+        pane.p("^date", {id:"date-value", format:"long", dtype:"D"});
+        pane.dataSetter({destination_path:"date",value:new Date('2026-10-16T00:00:00Z')});
+        for (const [path,value] of [["live",false],["locked",false]]) pane.dataSetter({destination_path:path,value});
+    }
+}
+
+export class Logic {}

package/src/gramlot_examples/pages/components/11_date_textbox.md

@@ -0,0 +1,18 @@
+# 11 · Date editing
+
+Enter a calendar date or a word such as oggi or domani. Two fields share one civil date.
+
+**Uses:** the 0.3 input collection, labelbox, typed Data, page locale and Gramlot formatting. No endpoint calls or validation engine.
+
+<details>
+<summary>More detail</summary>
+
+The page locale is `it-IT`. Focus a field to edit its short date; leave it to see its chosen `format`. Try `18/10/2026`, `oggi` and `domani`. Words such as `ieri`, `oggi` and `domani` are relative to today in the browser, independently of the date already in the field. An explicit `workdate="YYYY-MM-DD"` can be used when an application deliberately needs a different reference day.
+
+The Data value is a Python `date`, transported as TYTX `D`; JavaScript represents it as a Date at UTC midnight. It remains a civil date, independent of the page timezone. `31/02/2026` is invalid and does not change Data. Period expressions are rejected: this field edits one complete date. Clearing writes null; Escape cancels the draft. This is a text editor, not a calendar popup.
+
+Make the fields read-only; try label layout variants from Settings (⚙) in the gallery footer. Both controls keep the shared labelbox contract (`lbl_` and `box_`). The cards stay within 24rem.
+
+</details>
+
+The first field also opens a calendar (Alt+Down or its button). The second uses `calendar=False` to keep text editing only. See **Date calendar** for the standalone view and shared binding.

package/src/gramlot_examples/pages/components/12_time_textbox.js

@@ -0,0 +1,23 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = "Time editing";
+    static locale = "it-IT";
+    static css = ["/themes/gramlot-base/theme.css"];
+    main(root) {
+        const pane = root.main({class:"example-page stack"});
+        pane.h1("Time editing");
+        pane.p("Edit a civil time with hours, minutes and optional seconds. The two fields keep the same typed value.");
+        const controls = pane.formlet({class:"card stack",width:"100%",max_width:"24rem"});
+        controls.checkbox({id:"live",value:"^live",lbl:"Editing",label:"Update while typing"});
+        controls.checkbox({id:"locked",value:"^locked",lbl:"State",label:"Read only"});
+        const fields = pane.formlet({class:"card stack",width:"100%",max_width:"24rem"});
+        fields.timeTextBox({id:"time", value:"^time", lbl:"Departure", format:"medium", live:"^live", readonly:"^locked", box_c_width:"14rem"});
+        fields.timeTextBox({id:"time-copy", value:"^time", lbl:"Same time, short display", format:"short", readonly:"^locked", box_c_width:"14rem"});
+        pane.p("^time", {id:"time-value", format:"medium", dtype:"H"});
+        pane.dataSetter({destination_path:"time",value:new Date('1970-01-01T09:30:00Z')});
+        for (const [path,value] of [["live",false],["locked",false]]) pane.dataSetter({destination_path:path,value});
+    }
+}
+
+export class Logic {}

package/src/gramlot_examples/pages/components/12_time_textbox.md

@@ -0,0 +1,16 @@
+# 12 · Time editing
+
+Edit a civil time with hours, minutes and optional seconds. The two fields keep the same typed value.
+
+**Uses:** the 0.3 input collection, labelbox, typed Data, page locale and Gramlot formatting. No endpoint calls or validation engine.
+
+<details>
+<summary>More detail</summary>
+
+Type `14:35`, `14:35:20` or `14:35:20.125`. Editing uses the 24-hour clock; display uses the page locale and `format` (`short` or `medium`). A short display can hide seconds, but it does not remove them from Data. Focus the field to see the complete time again.
+
+Python starts with `datetime.time`; TYTX `H` carries a civil time, represented in JavaScript on 1970-01-01 UTC. No timezone shift is applied. Midnight is a valid value; an empty field writes null. `25:00` stays as an invalid draft without overwriting Data. Enter or leaving the field commits; Escape cancels. Millisecond precision is supported; this editor does not provide a time picker popup.
+
+Make the fields read-only; try label layout variants from Settings (⚙) in the gallery footer. Both controls keep the shared labelbox contract (`lbl_` and `box_`). The cards stay within 24rem.
+
+</details>

package/src/gramlot_examples/pages/components/13_filtering_select.js

@@ -0,0 +1,23 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = "Filtering select";
+    static css = ["/themes/gramlot-base/theme.css"];
+    main(root) {
+        const pane = root.main({class:"example-page stack"});
+        pane.h1("Filtering select");
+        pane.p("Search a caption, store its code. Two fields share the same choice and the same list.");
+        const controls = pane.formlet({class:"card stack",width:"100%",max_width:"24rem"});
+        controls.checkbox({id:"locked",value:"^locked",lbl:"State",label:"Read only"});
+        const fields = pane.formlet({class:"card stack",width:"100%",max_width:"24rem"});
+        fields.filteringSelect({id:"choice",value:"^choice",values:"^choices",lbl:"Delivery",readonly:"^locked",box_c_width:"16rem",placeholder:"Type part of a caption"});
+        fields.filteringSelect({id:"choice-copy",value:"^choice",values:"^choices",lbl:"Same choice",readonly:"^locked",box_c_width:"16rem"});
+        pane.dataSetter({destination_path:"choices",value:"standard:Standard,express:Express,pickup:Pick up"});
+        pane.dataSetter({destination_path:"choice",value:"express"});
+        pane.p("Selected code:");
+        pane.p("^choice",{id:"choice-value"});
+        pane.dataSetter({destination_path:"locked",value:false});
+    }
+}
+
+export class Logic {}

package/src/gramlot_examples/pages/components/13_filtering_select.md

@@ -0,0 +1,20 @@
+# 13 · Filtering select
+
+Search a caption, store its code. Two fields share the same choice and the same list.
+
+**Uses:** the 0.3 input collection, shared labelbox, Source and Data bindings. No endpoints or validation engine.
+
+<details>
+<summary>More detail</summary>
+
+Type `Exp`, then press Enter or click **Express**. Data stores `express`, while both fields show **Express**. The arrow button opens all choices; use Up/Down to move and Enter to select. Escape restores the committed caption. Emptying and leaving the field writes null. An unknown caption stays as an invalid draft and does not overwrite Data.
+
+`values="^choices"` reads `code:Caption` pairs separated by commas from Data. Updating that value refreshes the choices. `filteringSelect` is a component; plain `select` remains the native HTML element.
+
+```python
+fields.filteringSelect(value="^choice", values="^choices", lbl="Delivery")
+```
+
+Move the label or enable read-only mode without replacing the input. Both lessons use the same `lbl_` and `box_` contract as the earlier controls, with compact cards and bounded field widths.
+
+</details>

package/src/gramlot_examples/pages/components/14_callback_select.js

@@ -0,0 +1,45 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = "Callback select";
+    static css = ["/themes/gramlot-base/theme.css"];
+    main(root) {
+        const pane = root.main({class:"example-page stack"});
+        pane.h1("Callback select");
+        pane.p("Search 100 random samples generated once in this page. The callback reads a Data Bag, without a server request.");
+        const controls = pane.formlet({class:"card stack",width:"100%",max_width:"24rem"});
+        controls.checkbox({id:"locked",value:"^locked",lbl:"State",label:"Read only"});
+        const fields = pane.formlet({class:"card stack",width:"100%",max_width:"24rem"});
+        fields.callbackSelect({id:"choice",value:"^choice",callback:"searchChoices",lbl:"Sample",readonly:"^locked",box_c_width:"18rem",placeholder:"Try Sample 02 or value 7"});
+        fields.callbackSelect({id:"choice-copy",value:"^choice",callback:"searchChoices",lbl:"Same sample",readonly:"^locked",box_c_width:"18rem"});
+        pane.p("100 stable codes; random values stay unchanged until the page reloads.");
+        pane.dataController({func:"createSamples",_onStart:true});
+        pane.p("Selected code:");
+        pane.p("^choice",{id:"choice-value"});
+        pane.dataSetter({destination_path:"locked",value:false});
+    }
+}
+
+export class Logic {
+    createSamples(node) {
+        for (let i = 1; i <= 100; i++) {
+            const number = String(i).padStart(3, '0');
+            const id = `item_${number}`;
+            const value = Math.floor(Math.random() * 100);
+            node.SET(`samples.${id}.id`, id);
+            node.SET(`samples.${id}.name`, `Sample ${number} — value ${value}`);
+        }
+        node.SET('choice', 'item_001');
+    }
+    searchChoices(node, kw) {
+        const rows = node.GET('samples').getNodes().map(item => ({
+            id: item.getValue().getItem('id'),
+            name: item.getValue().getItem('name')
+        }));
+        return {
+            rows: rows.filter(row => kw._id != null ? row.id === kw._id
+                : row.name.toLocaleLowerCase().includes(kw._querystring.toLocaleLowerCase())),
+            identifier: 'id', caption: 'name'
+        };
+    }
+}

package/src/gramlot_examples/pages/components/14_callback_select.md

@@ -0,0 +1,24 @@
+# 14 · Callback select
+
+Search 100 random samples generated once in this page. The callback reads a Data Bag, without a server request.
+
+**Uses:** the 0.3 input collection, shared labelbox, Source and Data bindings and named browser Logic. No endpoints or validation engine.
+
+<details>
+<summary>More detail</summary>
+
+Search `Sample 02` to see samples 020–029, then choose one. The second field recovers its caption from the selected code. Searching again does not regenerate the random values: inspect `samples` in the Data inspector to see the same 100 records.
+
+Python declares the control and names its browser Logic method:
+
+```python
+fields.callbackSelect(value="^choice", callback="searchChoices", lbl="Sample")
+```
+
+The Logic method receives `(node, kw)`. `_querystring` asks for matches; `_id` asks for the record of a code already in Data. It returns `{rows, identifier: 'id', caption: 'name'}`. Rows are objects with string codes and captions. The example reads them from a Data Bag initialized by an ordinary startup controller. No endpoint, manual DOM code or second application state is needed.
+
+A callback may also return a Promise. The control shows pending state and discards responses from superseded searches or removed controls. Callback failures appear below the input. The same code/caption, keyboard and invalid-draft rules apply as in Filtering select.
+
+Move the label or enable read-only mode without replacing the input. Both lessons use the same `lbl_` and `box_` contract as the earlier controls, with compact cards and bounded field widths.
+
+</details>

package/src/gramlot_examples/pages/components/15_combo_box.js

@@ -0,0 +1,23 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = "Combo box";
+    static css = ["/themes/gramlot-base/theme.css"];
+    main(root) {
+        const pane = root.main({class:"example-page stack"});
+        pane.h1("Combo box");
+        pane.p("Choose a suggested city or enter a different one. Two fields share the same text; suggestions do not restrict what you can write.");
+        const controls = pane.formlet({class:"card stack",width:"100%",max_width:"24rem"});
+        controls.checkbox({id:"locked",value:"^locked",lbl:"State",label:"Read only"});
+        const fields = pane.formlet({class:"card stack",width:"100%",max_width:"24rem"});
+        fields.comboBox({id:"choice",value:"^choice",values:"^choices",lbl:"City",readonly:"^locked",box_c_width:"16rem",placeholder:"Choose or type a city"});
+        fields.comboBox({id:"choice-copy",value:"^choice",values:"^choices",lbl:"Same city",readonly:"^locked",box_c_width:"16rem"});
+        pane.dataSetter({destination_path:"choices",value:"Rome,Paris,Berlin"});
+        pane.dataSetter({destination_path:"choice",value:"Rome"});
+        pane.p("Stored text:");
+        pane.p("^choice",{id:"choice-value"});
+        pane.dataSetter({destination_path:"locked",value:false});
+    }
+}
+
+export class Logic {}

package/src/gramlot_examples/pages/components/15_combo_box.md

@@ -0,0 +1,22 @@
+# 15 · Combo box
+
+Choose a suggested city or enter a different one. Two fields share the same text; suggestions do not restrict what you can write.
+
+**Uses:** the 0.3 input collection, labelbox, Source and Data bindings. No endpoints or validation engine.
+
+<details>
+<summary>More detail</summary>
+
+Type `Pa` and choose **Paris** from the suggestions. Then type a city absent from the list and press Enter or leave the field: the new text is accepted and appears in both controls.
+
+```python
+fields.comboBox(value="^choice", values="Rome,Paris,Berlin", lbl="City")
+```
+
+`comboBox` stores the text, including the caption of a chosen suggestion. Compare **Filtering select**, which accepts only listed choices and stores their codes. If `values` contains `code:Caption` pairs, comboBox still stores the caption, not the code.
+
+The arrow opens all suggestions. Up/Down moves the highlight; Enter or a click chooses it. Escape cancels an uncommitted draft. Empty text writes an empty string; an untouched initial null stays null. `live=True` enables text updates while typing, through the same binding and IME handling as textbox.
+
+`values`, `lbl_position` and readonly can follow Data pointers. Changing the label preserves the input and caret. Cards and fields remain compact, using the shared `lbl_` and `box_` styling contract.
+
+</details>

package/src/gramlot_examples/pages/components/16_checkbox_text.js

@@ -0,0 +1,23 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = "Checkbox group";
+    static css = ["/themes/gramlot-base/theme.css"];
+    main(root) {
+        const pane = root.main({class:"example-page stack"});
+        pane.h1("Several choices, one value");
+        pane.p("Choose several notification channels. Two groups share the same comma-separated codes; clearing all choices writes null.");
+        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%"});
+        controls.checkbox({id:"locked",value:"^locked",lbl:"State",label:"Read only"});
+        const fields = pane.formlet({class:"card stack",width:"100%",max_width:"24rem"});
+        fields.checkBoxText({id:"channels",value:"^channels",values:"^choices",lbl:"Notifications",cols:"^columns",readonly:"^locked",box_padding:"8px"});
+        fields.checkBoxText({id:"channels-copy",value:"^channels",values:"^choices",lbl:"Same channels",cols:1,readonly:"^locked",box_padding:"8px"});
+        pane.p("Selected codes:");
+        pane.p("^channels",{id:"channels-value"});
+        for (const [destination_path,value] of [["choices","email:Email,sms:SMS,push:Push"],["channels","email,push"],["columns",2],["locked",false]]) pane.dataSetter({destination_path,value});
+    }
+}
+
+export class Logic {}

package/src/gramlot_examples/pages/components/16_checkbox_text.md

@@ -0,0 +1,23 @@
+# 16 · Checkbox group
+
+Choose several notification channels. Two groups share the same comma-separated codes; clearing all choices writes null.
+
+**Uses:** the 0.3 input collection, labelbox, Source and Data bindings. No endpoints, stores or validation engine.
+
+<details>
+<summary>More detail</summary>
+
+Check **SMS** in either group: both show the same selection. The Data value is a string such as `email,push,sms`, not the visible captions. Uncheck every option: Data becomes null. Existing selected codes keep their order; new choices are appended.
+
+```python
+fields.checkBoxText(value="^channels", values="email:Email,sms:SMS,push:Push",
+                    lbl="Notifications", cols=2)
+```
+
+Compare **RadioButtonText**: it uses the same option and labelbox structure, but selects only one code. Here every checkbox is independent. Tab or arrow keys move focus and Space changes the focused checkbox. Home/End move to the first/last option.
+
+Change the number of columns; label layout variants are in Settings (⚙) in the gallery footer. The group keeps its controls and selection. `values`, `cols`, `lbl_position` and `readonly` can follow Data pointers; the readonly switch locks both groups. Shared `lbl_` and `box_` attributes style the same labelbox parts as earlier lessons.
+
+This lesson uses an inline group. Popup selection and Bag/store-backed options are separate features. Cards stay within 24rem and the column slider within 16rem.
+
+</details>

package/src/gramlot_examples/pages/components/17_date_calendar.js

@@ -0,0 +1,25 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static devices = ['desktop', 'tablet', 'phone'];
+    static title = "Date calendar";
+    static locale = "it-IT";
+    static css = ["/themes/gramlot-base/theme.css"];
+    main(root) {
+        const pane = root.main({class:"example-page stack"});
+        pane.h1("One date, three editors");
+        pane.p("Pick a day or type a date. The inline calendar, popup and text-only field share the same Data value.");
+        const controls = pane.formlet({class:"card stack",width:"100%",max_width:"24rem"});
+        controls.checkbox({id:"locked",value:"^locked",lbl:"State",label:"Read only"});
+        const fields = pane.formlet({class:"card stack",width:"100%",max_width:"24rem"});
+        fields.dateTextBox({id:"date",value:"^date",lbl:"With popup",
+            readonly:"^locked",box_c_width:"14rem",box_c_max_width:"100%"});
+        fields.dateTextBox({id:"plain",value:"^date",lbl:"Text only",calendar:false,
+            readonly:"^locked",box_c_width:"14rem",box_c_max_width:"100%"});
+        fields.dateCalendar({id:"calendar",value:"^date",lbl:"Choose a day",readonly:"^locked",lbl_color:"#4369c5",box_c_max_width:"100%"});
+        pane.p("^date",{id:"date-value",format:"long",dtype:"D"});
+        pane.dataSetter({destination_path:"date",value:new Date('2026-10-16T00:00:00Z')});
+        pane.dataSetter({destination_path:"locked",value:false});
+    }
+}
+export class Logic {}

package/src/gramlot_examples/pages/components/17_date_calendar.md

@@ -0,0 +1,22 @@
+# 17 · Date calendar
+
+Pick a day or type a date. The inline calendar, popup and text-only field share the same Data value. Learn when to use a calendar beside the page or inside a date field.
+
+**Uses:** the 0.3 input collection, labelbox and typed Data bindings. No endpoints, stores or validation engine.
+
+<details>
+<summary>More detail</summary>
+
+```python
+fields.dateTextBox(value="^date", lbl="With popup")
+fields.dateTextBox(value="^date", lbl="Text only", calendar=False)
+fields.dateCalendar(value="^date", lbl="Choose a day")
+```
+
+`dateTextBox` has a calendar button by default (`calendar=True`). `dateCalendar` displays the same calendar directly in the page. All three declarations use the same pointer: choosing or typing a date updates every view. The Data holds a civil date (`D`), never the formatted caption. **Clear** writes null; **Today** and natural-language input use today's local date in the browser. The initial sample value does not set the reference day. An application may explicitly provide `workdate` when a different working date is intended.
+
+Use the arrows to browse months. In the day grid, arrow keys move by day/week, Home/End move to Monday/Sunday, PageUp/PageDown change month, and Enter or Space selects. Navigation alone leaves Data unchanged. Alt+Down opens the text field's calendar; Escape closes it and returns focus to the field. A popup selection commits the date immediately. Invalid text remains a draft until corrected or cancelled.
+
+The calendar has Monday-first weeks; month/day captions follow the page locale (`it-IT` here). **Read only** locks all three controls. Use Settings (⚙) in the gallery footer to compare label positions. The calendar shares the `lbl_position`, `lbl_` and `box_` contract of the other inputs. Cards stay within 24rem and text fields within 14rem.
+
+</details>

package/src/gramlot_examples/pages/components/18_validation.js

@@ -0,0 +1,31 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static devices = ['desktop', 'tablet', 'phone'];
+    static title = "Required values and length";
+    static css = ["/themes/gramlot-base/theme.css"];
+    main(root) {
+        const pane = root.main({class:"example-page stack"});
+        pane.h1("The draft and the accepted value");
+        pane.p("Try one letter, more than eight, or an empty name. The draft stays in the field; the Data below keeps the last valid value.");
+        const controls = pane.formlet({class:"card stack",width:"100%",max_width:"24rem"});
+        controls.checkbox({id:"live",value:"^live",lbl:"Timing",label:"Validate while typing"});
+        const fields = pane.formlet({class:"card stack",width:"100%",max_width:"24rem"});
+        fields.textbox({id:"name",value:"^name",lbl:"Name (2–8 characters)",live:"^live",
+            validate_notnull:true,validate_len:"2:8",validate_notnull_error:"Please enter a name.",
+            validate_len_error:"Use between 2 and 8 characters.",box_c_width:"16rem",box_c_max_width:"100%"});
+        fields.p("Last accepted name:");fields.p("^name",{id:"accepted-name"});
+        fields.textbox({id:"name-copy",value:"^name",lbl:"Another view of the Data",readonly:true,
+            box_c_width:"16rem",box_c_max_width:"100%"});
+        const notes = pane.formlet({class:"card stack",width:"100%",max_width:"24rem"});
+        notes.textBoxArea({id:"notes",value:"^notes",lbl:"Optional note (up to 20 characters)",rows:2,
+            validate_len:":20",live:"^live",box_c_width:"18rem",box_c_max_width:"100%"});
+        notes.p("^notes",{id:"accepted-notes"});
+        const numbers = pane.formlet({class:"card stack",width:"100%",max_width:"24rem"});
+        numbers.numberTextBox({id:"quantity",value:"^quantity",lbl:"Required quantity — zero is valid",
+            validate_notnull:true,box_c_width:"10rem",box_c_max_width:"100%"});
+        numbers.p("^quantity",{id:"accepted-quantity"});
+        for (const [destination_path,value] of [["name","Ada"],["notes","Hello"],["quantity",0],["live",false]]) pane.dataSetter({destination_path,value});
+    }
+}
+export class Logic {}

package/src/gramlot_examples/pages/components/18_validation.md

@@ -0,0 +1,29 @@
+# 18 · Required values and length
+
+Try a missing, short or long name. You learn the difference between the draft visible in a field and the last accepted value in Data.
+
+**Uses:** the 0.3 input collection, shared validation, labelbox and Data bindings. No form/save service, callbacks or remote validators.
+
+<details>
+<summary>More detail</summary>
+
+```python
+fields.textbox(value="^name", lbl="Name", validate_notnull=True,
+               validate_len="2:8", validate_len_error="Use 2 to 8 characters.")
+```
+
+Type `A`, then leave the field: the message appears, while the accepted name stays `Ada`. Try more than eight characters: nothing is truncated. Type `Grace` and leave the field: both Data views update and the message disappears. Clear the field: the required message appears and Data stays `Grace`.
+
+Turn **Validate while typing** on to use `live=True`. The same rules now run on each edit, after IME composition has finished. Otherwise text fields validate on their normal change/blur event; typed number/date/time editors also confirm on Enter.
+
+`validate_notnull` rejects null and the empty string. Zero and false are values. `validate_len="2:8"` accepts 2–8 characters, `"2:"` sets only a minimum, `":20"` only a maximum, and `"4"` requires an exact length. Length counts JavaScript string units, as in the existing PoC; it is not a grapheme counter. Optional empty text passes the length rule, as the note demonstrates. No trimming or normalization is added.
+
+The error messages can be customized with `validate_notnull_error` and `validate_len_error`; they are marked as localizable strings for the future localization service. Rules and messages may follow Data pointers. The next edit uses the current rules. Changing a label does not discard an invalid draft; a different external Data value replaces it. Validation does not filter writes performed directly by application logic.
+
+The shared message also drives ARIA and native custom validity. Gramlot remains the rule owner; `maxlength` is not imposed because that would prevent the invalid draft from being entered and inspected. Required quantity demonstrates that clearing a typed editor is rejected while zero is accepted.
+
+</details>
+
+An invalid field keeps a pale red background. Its message floats without moving the other fields,
+then fades out after about two seconds (no animation with reduced motion). Focus or hover the field to read it again;
+Escape dismisses it. The error and last accepted Data value remain until corrected.