@gramlot/gramlot-examples 0.2.16 → 0.3.1

package/src/gramlot_examples/pages/components/22_button.js

@@ -0,0 +1,18 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+export class Page extends BasePage {
+    static title = 'Button commands';
+    static devices = ['desktop', 'tablet', 'phone'];
+    static css = ['/themes/gramlot-base/theme.css'];
+    main(root) {
+        const pane=root.main({class:'example-page stack'});
+        pane.h1('One shared command engine');
+        pane.p('Confirm the action, or click the delayed command several times: only the last burst is delivered.');
+        const actions=pane.div({class:'card stack',max_width:'26rem'});
+        actions.button('Confirm action',{id:'command-confirm',icon:'✓',action:"this.SET('result', 'Confirmed')",ask:'Run this command?'});
+        actions.button('Delayed command',{id:'command-delay',_delay:300,action:"this.SET('result', 'Delayed: ' + _counter)"});
+        actions.html_button('Plain HTML',{type:'button',id:'command-native',connect_onclick:"this.SET('result', 'Explicit HTML event')"});
+        pane.p('^result',{id:'command-result'});
+        pane.dataSetter({destination_path:'result',value:'No command yet'});
+    }
+}
+export class Logic {}

package/src/gramlot_examples/pages/components/22_button.md

@@ -0,0 +1,12 @@
+# 22 · Button commands
+
+Compare the Gramlot command button with plain HTML. Try confirmation and a delayed command.
+
+**Uses:** built-in command components, Source, Data and the shared action engine; the toggle example also uses inputs and layout. No endpoints or database.
+
+<details>
+<summary>More detail</summary>
+
+`button` is a Web Component with an internal native button. It reuses action, ask, fire, nested controllers and _delay. `html_button` stays plain HTML, including native form submission. Here its explicit click connection updates Data. Gramlot command buttons do not implicitly submit forms.
+
+</details>

package/src/gramlot_examples/pages/components/23_toggle_button.js

@@ -0,0 +1,18 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+export class Page extends BasePage {
+    static title = 'Toggle button with LED';
+    static devices = ['desktop', 'tablet', 'phone'];
+    static css = ['/themes/gramlot-base/theme.css'];
+    main(root) {
+        const pane=root.main({class:'example-page stack'});
+        pane.h1('A boolean command with an LED');
+        const fields=pane.formlet({columns:1,max_width:'26rem',lbl_position:'L'});
+        fields.toggleButton('Enabled',{id:'toggle-command',value:'^enabled',readonly:'^readonly',disabled:'^disabled',action:"this.SET('result', this.GET('enabled') ? 'Enabled' : 'Disabled')"});
+        fields.checkbox({value:'^enabled',lbl:'Same Data',id:'toggle-checkbox'});
+        fields.checkbox({value:'^readonly',lbl:'Read only'});
+        fields.checkbox({value:'^disabled',lbl:'Disabled'});
+        pane.p('^result',{id:'toggle-result'});
+        for(const [destination_path,value] of [['enabled',false],['readonly',false],['disabled',false],['result','No command yet']]) pane.dataSetter({destination_path,value});
+    }
+}
+export class Logic {}

package/src/gramlot_examples/pages/components/23_toggle_button.md

@@ -0,0 +1,12 @@
+# 23 · Toggle button with LED
+
+A command button and a checkbox share a boolean. The LED and aria-pressed follow Data.
+
+**Uses:** built-in command components, Source, Data and the shared action engine; the toggle example also uses inputs and layout. No endpoints or database.
+
+<details>
+<summary>More detail</summary>
+
+`toggleButton(value="^enabled")` writes a boolean through the shared Data adapter. The LED and aria-pressed expose the current state; Space and Enter activate the native internal button. The state changes before its optional action; an action confirmation does not undo the state change. Readonly and disabled block user toggling, while external Data can still change the state.
+
+</details>

package/src/gramlot_examples/pages/components/24_dropdown_button.js

@@ -0,0 +1,21 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+export class Page extends BasePage {
+    static title = 'Dropdown commands and persistence';
+    static devices = ['desktop', 'tablet', 'phone'];
+    static css = ['/themes/gramlot-base/theme.css'];
+    main(root) {
+        const pane=root.main({class:'example-page stack'});
+        pane.h1('Execute, or execute and remember');
+        pane.p('Click a menu entry to execute it. Hold Shift while selecting it to also change the main action and caption. Reload to verify persistence.');
+        const actions=pane.div({class:'card stack',max_width:'26rem'});
+        const dropdown=actions.dropDownButton('Export',{id:'export-command',icon:'↓',persist:true,action:"this.SET('result', 'Default export')"});
+        const menu=dropdown.menu();
+        menu.menuline('Export CSV',{code:'csv',id:'export-csv',action:"this.SET('result', 'CSV export')"});
+        menu.menuline('Export PDF',{code:'pdf',id:'export-pdf',action:"this.SET('result', 'PDF export')"});
+        menu.menuline('-');
+        menu.menuline('Unavailable',{code:'unavailable',disabled:true,action:"this.SET('result', 'Unavailable')"});
+        pane.p('^result',{id:'dropdown-result'});
+        pane.dataSetter({destination_path:'result',value:'No command yet'});
+    }
+}
+export class Logic {}

package/src/gramlot_examples/pages/components/24_dropdown_button.md

@@ -0,0 +1,12 @@
+# 24 · Dropdown commands and persistence
+
+The main surface executes; the arrow opens the menu. Shift-select a command to run it and make it the default.
+
+**Uses:** built-in command components, Source, Data and the shared action engine; the toggle example also uses inputs and layout. No endpoints or database.
+
+<details>
+<summary>More detail</summary>
+
+`dropDownButton` is one split command: the main surface never opens its menu. The arrow opens it; arrow keys, Home/End and Escape navigate or close it. Normal selection only executes; Shift+selection executes and changes the default action/caption. `persist=True` requires a stable id and saves the item code for this page URL in browser storage. Nothing executable is stored. On touch, ordinary selection executes; setting a default currently requires Shift. This is a local flat menu, without nested menus or button bars.
+
+</details>

package/src/gramlot_examples/pages/components/25_validation_engine.js

@@ -0,0 +1,51 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = 'Validation rules and callbacks';
+    static devices = ['desktop', 'tablet', 'phone'];
+    static css = ['/themes/gramlot-base/theme.css'];
+    main(root) {
+        const pane = root.main({class:'example-page stack'});
+        pane.h1('Validation playground');
+        pane.p('Leave a field to validate it. Invalid drafts stay visible; the accepted values below change only after success.');
+        const group = pane.groupBox({id:'validation-group',datapath:'profile',copy:true,lbl:'Profile · field validations',max_width:'36rem'});
+        const fields = group.formlet({id:'validation-fields',lbl_position:'L',box_c_width:'100%'});
+        fields.textbox({id:'full-name',value:'^.full_name',lbl:'Name (2–30)',validate_notnull:true,validate_len:'2:30',validate_notnull_error:'Please enter a name.',validate_len_error:'Use 2–30 characters.'});
+        fields.textbox({id:'code',value:'^.code',lbl:'Code (2–6 letters)',validate_case:'upper',validate_regex:'(?:^[A-Z]{2,6}$)',validate_regex_error:'Use 2–6 letters.'});
+        fields.textbox({id:'fallback',value:'^.fallback',lbl:'Empty becomes Guest',validate_empty:'Guest'});
+        fields.numberTextBox({id:'quantity',value:'^.quantity',lbl:'Quantity: 0–10',validate_min:0,validate_max:10});
+        fields.checkbox({id:'strict',value:'^.strict',lbl:'Email',label:'Make the warning blocking'});
+        fields.textbox({id:'email',value:'^.email',lbl:'Email format',validate_email:true,validate_email_iswarning:'^.strict:=!{}'});
+        fields.checkbox({value:'^.check_length',lbl:'Length',label:'Require at least four characters'});
+        fields.textbox({id:'conditional',value:'^.conditional',lbl:'Conditional length',validate_len:'4:',validate_len_if:'enabled',validate_enabled:'^.check_length'});
+        fields.textbox({id:'nickname',value:'^.nickname',lbl:'Nickname',validate_call:'checkNickname',validate_onAccept:'accepted',validate_onReject:'rejected'});
+        fields.textbox({id:'remote-name',value:'^.remote_name',lbl:'Remote name',validate_remote:'check_name',validate_timeout:5000});
+        fields.textBoxArea({id:'notes',value:'^.notes',lbl:'Notes (max 40)',rows:2,validate_len:':40',validate_len_error:'Use at most 40 characters.'});
+        fields.dateTextBox({id:'appointment',value:'^.appointment',lbl:'Appointment',format:'short',validate_notnull:true,validate_notnull_error:'Choose a date or type a date expression.'});
+        fields.filteringSelect({id:'delivery',value:'^.delivery',lbl:'Delivery',values:'standard:Standard,express:Express,pickup:Pick up',validate_notnull:true,validate_notnull_error:'Choose a delivery option.'});
+        group.p('Try an empty name, quantity 11, a malformed email, or a long note. The local callback rejects admin; the asynchronous endpoint rejects taken.');
+        const accepted = pane.details({max_width:'36rem',open:true});
+        accepted.summary('Accepted Data · invalid drafts do not overwrite these values');
+        const values = accepted.dl();
+        for (const [label,path] of [['Name','full_name'],['Code','code'],['Quantity','quantity'],['Email','email'],['Notes','notes'],['Delivery code','delivery'],['Remote name','remote_name']]) {
+            values.dt(label);
+            values.dd('^profile.'+path, {id: {code:'code-result',email:'email-result',remote_name:'remote-result'}[path]});
+        }
+        values.dt('Appointment');
+        values.dd('^profile.appointment',{format:'short'});
+        accepted.p('^profile.validation_status',{id:'validation-status'});
+        for (const [destination_path,value] of [['full_name','Ada Lovelace'],['notes','Please ring the bell.'],['appointment',new Date('2026-10-17T00:00:00Z')],['delivery','standard'],['code','AB'],['fallback','Guest'],['quantity',2],['email',''],['strict',false],['check_length',false],['conditional','Ada'],['nickname','Ada'],['remote_name','AVAILABLE'],['validation_status','Edit a nickname.']]) pane.dataSetter({destination_path:'profile.'+destination_path,value});
+    }
+    check_name({value}) {
+        return value.toLowerCase() === 'taken' ? {errorcode:'reserved',message:'That name is reserved.'} : {value:value.toUpperCase()};
+    }
+}
+Page.registerEndpoint('check_name');
+
+export class Logic {
+    checkNickname(node, {value}) {
+        return value.toLowerCase() === 'admin' ? {errorcode:'reserved',message:'Choose a nickname other than admin.'} : true;
+    }
+    accepted(node, {value}) { node.SET('.validation_status', 'Accepted: ' + value); }
+    rejected(node, {result}) { node.SET('.validation_status', 'Rejected: ' + result.error); }
+}

package/src/gramlot_examples/pages/components/25_validation_engine.md

@@ -0,0 +1,26 @@
+# 25 · Validation rules and callbacks
+
+A labelled groupBox contains a compact formlet with text, multiline text, number, date, selection and boolean controls. Try required values, length, normalization, conditional rules, warnings and asynchronous validation. The group copy icon copies the accepted `profile` Bag as TYTX; its menu also offers JSON. Invalid drafts are not copied. The expandable accepted-Data panel shows what actually changed.
+
+**Uses:** shared input validation, Source conditions, named Logic and typed RPC. The endpoint also runs in the serverless Worker. No database or form-save service.
+
+<details><summary>More detail</summary>
+
+```python
+group = pane.groupBox(datapath="profile", copy=True, lbl="Profile")
+pane = group.formlet(lbl_position="L")
+pane.textbox(value="^.code", validate_case="upper", validate_regex="(?:^[A-Z]{2,6}$)")
+pane.textbox(value="^.email", validate_email=True, validate_email_iswarning="^.strict:=!{}")
+pane.textbox(value="^.nickname", validate_call="checkNickname")
+pane.textbox(value="^.remote_name", validate_remote="check_name")
+```
+
+Clear Name or Appointment to test required values. Write more than 40 characters in Notes. Delivery accepts a listed choice and cannot be empty. The groupBox declares `datapath="profile"` once; its formlet inherits it and fields use relative `^.field` pointers. The formlet automatically aligns left labels without fixed label widths.
+
+Try `abc` in Code: the accepted value becomes `ABC`. Clear the fallback: it becomes Guest. Quantity rejects values outside 0–10. A malformed email is accepted with a warning unless the blocking switch is on. The length condition reads the resolved `validate_enabled` parameter as `enabled`.
+
+The local callback reserves `admin`. The endpoint reserves `taken` and normalizes accepted names to uppercase. It returns a validation result; it does not write Data. While a request is pending, Data retains its last value. Editing again, changing the rules or removing the field makes the old response obsolete. Timeout and transport errors reject the candidate.
+
+`validate_onAccept` runs after the Data write. `validate_onReject` sees the rejected candidate while Data still contains its previous value. Named Logic receives `(node, {value, result, validations, userChange, ...parameters})`; small inline conditions/bodies must originate in activated Source. Full syntax is documented in the core component guide.
+
+</details>

package/src/gramlot_examples/pages/components/README.md

@@ -0,0 +1,40 @@
+# Input components
+
+This section uses only the first input components, their shared labelbox, Source,
+Data and bindings. It revisits native forms and binding with `textbox`, `checkbox`,
+`radioButtonText`, multiline/password fields, single radios, colors and sliders;
+endpoint calls and stores are outside this section; the final lesson introduces basic validation.
+
+The gallery activates the `inputs` collection once in its application configuration.
+Python uses its generated JSON grammar; the browser loads its JavaScript implementation.
+The widget names are the same in Python and JavaScript.
+
+Start with Textbox, then compare the boolean checkbox and the single-choice radio
+group. All controls use `lbl`, the same reactive `lbl_position` and the `lbl_`/`box_`
+style prefixes. The controls belong to the shared inputs collection.
+
+
+Continue with **Filtering select** for searchable local code/caption pairs, then
+**Callback select** for the same interaction backed by 100 stable random records
+in a Data Bag. These lessons add named browser Logic, with no endpoint calls.
+
+
+**Combo box** allows free text as well as suggestions; **Checkbox group** stores
+several selected codes together. Compare them with Filtering select and
+RadioButtonText to understand the different value contracts.
+
+
+**Date calendar (w17):** one civil date shared by an inline calendar, a popup field and a text-only field. Compare `dateCalendar`, the default `dateTextBox(calendar=True)` and `calendar=False`. The same labelbox and compact sizes apply.
+
+
+**Required values and length (w18):** compare a rejected draft with the last accepted Data value. Shared validation covers required text, text length and a required number, with compact labelbox fields and a live-edit switch.
+
+Use **Settings (⚙)** in the gallery footer to compare themes, light/dark and label positions across components. **As in the example** restores the lesson's own layout. The first lesson keeps a local position selector to explain its Data binding; later lessons focus on their particular input behavior.
+
+**Formlet and shared labels (w19):** Arrange fields in columns and share label settings. Changing the layout preserves each field and its draft.
+
+**GroupBox and typed copy (w20):** Group customer data under a heading. Copy TYTX with its types or choose plain JSON from the copy menu.
+
+**Checkbox as a switch (w21):** A switch and a checkbox share one boolean. Compare their appearance, captions and read-only state.
+
+- `w25`: complete local validation engine, conditional rules, warnings, Logic callbacks and RPC validation. DB/grid rules remain in their own integration scope.

package/src/gramlot_examples/pages/controllers/16_attribute_projection.js

@@ -10,8 +10,8 @@ export class Page extends BasePage {
         pane.html_label('Name', {for: 'name'});
         pane.input({value: '^.name', live: true, id: 'name'});
         pane.p('^.name', {mask: 'Hello, {}', id: 'greeting'});
-        pane.div('Hover to read the title', {customer: '^.name', title: 'Customer: ${customer}', id: 'card'});
-        pane.p('The template consumes customer; it is not a DOM attribute.');
+        pane.div('Hover to read the title', {customer: '^.name', title: '^.name:Customer: {customer}', id: 'card'});
+        pane.p('The pointer template reads customer from Source; the customer attribute remains projected.');
         pane.h2('0.2.3: a separate HTML preview');
         pane.html_label('Preview HTML', {for: 'html'});
         pane.textarea({value: '^.html', live: true, id: 'html'});

package/src/gramlot_examples/pages/controllers/16_attribute_projection.md

@@ -2,13 +2,13 @@
 
 One name appears in a greeting and a tooltip with different formatting. You learn how templates and masks reuse a bound value without copying text. The later **0.2.3** section previews HTML in a separate sandboxed frame.
 
-**Uses:** Data binding, attribute templates and text masks (0.2.0); sandboxed Data `srcdoc` only in the later part (0.2.3).
+**Uses:** Data binding, explicit pointer templates and text masks; sandboxed Data `srcdoc` only in the later part (0.2.3).
 
 <details>
 <summary>More detail</summary>
 
 
-**Release stage:** core 0.2.0 templates/masks, followed by the separate 0.2.3 Data-srcdoc sandbox step.
+**Release stage:** maintained explicit pointer syntax; Data-srcdoc sandboxing was introduced in 0.2.3.
 
 **Goal:** Reuse one Data value in text and attributes, then distinguish text from a sandboxed HTML document.
 
@@ -22,28 +22,28 @@ A template reads another attribute of its own Source node **after pointer resolu
 
 ```python
 pane.div("Hover to read the title", customer="^.name",
-         title="Customer: ${customer}")
+         title="^.name:Customer: {customer}")
 pane.p("^.name", mask="Hello, {}")
 ```
 
-`${customer}` is Gramlot syntax, not Python interpolation. `customer` supplies the template and is consumed instead of becoming a DOM attribute. `mask` formats the projected text; it does not enable HTML. The maintained syntax uses `{}`; older releases used `%s`.
+`:` opens the pointer template. `{customer}` reads the current Source attribute; `customer` remains a normal projected DOM attribute. Ordinary `${customer}` is literal text. `mask` formats the projected text; it does not enable HTML. The maintained syntax uses `{}`; older releases used `%s`.
 
 The later section uses `pane.iframe(srcdoc="^.html", ...)`. Data-provided HTML gets `sandbox=""`: it is an isolated document, with scripts/forms/popups blocked by default. Ordinary `pane.p("^.html")` would show literal markup instead.
 
 ## Try it and predict the result
 
 1. Initially the greeting is “Hello, Ada”; hover the card and expect title “Customer: Ada”.
-2. Type Grace: both follow the same Data value. Inspect the card: it has `title`, but no `customer` attribute.
+2. Type Grace: both follow the same Data value. Inspect the card: it has both the formatted `title` and the resolved `customer` attribute.
 3. Clear Name: the greeting becomes empty; the title retains its authored prefix.
 4. Replace Preview HTML with `<h2>Preview two</h2><p>Only this frame changes.</p>`. The heading appears inside the frame; the outer page stays intact. Inspect the iframe's `sandbox` attribute: it is present with an empty value.
 
 ## Change it and check yourself
 
-Change the mask to `Welcome, {}` and the title to `Guest: ${customer}`. Leave the Data pointer alone.
+Change the mask to `Welcome, {}` and the title to `^.name:Guest: {customer}`. Leave the Data pointer alone.
 
 **Answer:** one Name edit still updates both destinations with different formatting; no extra provider or shared formatted Data value is needed.
 
-Separate invalid-edit exercise: rename only the template reference to `${missing}`, then reload. Expect an unknown-template-parameter error, not a blank substitute. Restore it. A preceding backslash escapes `${`; an `==` attribute cannot supply a template parameter, and `==` expressions cannot contain a template. See the reference for the permitted expression/template dependency order.
+Separate invalid-edit exercise: rename only the template slot to `{missing}`, then reload. Expect a missing Source-attribute error. Restore it. Use `:=` for an expression with typed slots; ordinary `${...}` text is not interpolated or consumed.
 
 ## The same example across stages
 

package/src/gramlot_examples/pages/html_svg/06_forms.js

@@ -51,9 +51,9 @@ export class Page extends BasePage {
         options.html_label('Attachment', {for: 'attachment'});
         options.input({type: 'file', id: 'attachment', name: 'attachment'});
         const actions = form.div({class: 'form-actions'});
-        actions.button('Button without an action', {type: 'button'});
-        actions.button('Reset values', {type: 'reset'});
-        actions.button('Submit unavailable', {type: 'submit', disabled: true});
+        actions.html_button('Button without an action', {type: 'button'});
+        actions.html_button('Reset values', {type: 'reset'});
+        actions.html_button('Submit unavailable', {type: 'submit', disabled: true});
     }
 
     field(parent, label, key, kind, attrs = {}) {