@gramlot/gramlot-examples 0.3.3 → 0.3.4

package/src/gramlot_examples/pages/layout/04_drawer_handles.js

@@ -0,0 +1,140 @@
+import { Page as BasePage } from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = 'Drawers: handles, content and retained Data';
+    static devices = ['desktop', 'tablet', 'phone'];
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const pane = root.main({
+            class: 'example-page stack',
+            height: '100dvh',
+            box_sizing: 'border-box',
+            display: 'flex',
+            flex_direction: 'column',
+            overflow: 'hidden',
+        });
+        pane.h1('Small handles, readable labels');
+        pane.p('Open and resize the regions; the fields share the same Data.');
+        const border = pane.borderContainer({
+            id: 'handles-demo',
+            height: '100%',
+            min_height: 0,
+            flex: '1',
+            max_width: '64rem',
+            border: '1px solid var(--gramlot-border-control, #aaa)',
+            rounded: 12,
+        });
+        const surface = 'var(--gramlot-surface-subtle, #eef1f5)';
+        const search = border.contentPane({
+            region: 'top',
+            node_id: 'drawerSearch',
+            height: '64px',
+            splitter: true,
+            drawer: '^drawerSearch',
+            drawer_icon: '⌕',
+            drawer_label: 'Search',
+            drawer_title: 'Search',
+            drawer_minimize: true,
+            minSize: 36,
+            padding: '10px',
+            background: surface,
+        });
+        search.textbox({
+            value: '^search',
+            lbl: 'Search customers',
+            placeholder: 'Type a name',
+            width: '100%',
+            max_width: '20rem',
+        });
+        const filters = border.contentPane({
+            region: 'left',
+            node_id: 'drawerFilters',
+            width: '^filtersWidth',
+            splitter: true,
+            drawer: '^drawerFilters',
+            drawer_label: 'Filters',
+            drawer_title: 'Filters',
+            minSize: 70,
+            padding: '10px',
+            background: surface,
+        });
+        filters.h3('Filters');
+        filters.checkbox({ value: '^active', label: 'Active only', mode: 'switch' });
+        filters.radioButtonText({
+            value: '^delivery',
+            values: 'standard:Standard,express:Express,pickup:Pick up',
+            cols: 1,
+        });
+        const details = border.contentPane({
+            region: 'right',
+            node_id: 'drawerDetails',
+            width: '180px',
+            splitter: true,
+            drawer: '^drawerDetails',
+            drawer_label: 'Details',
+            drawer_title: 'Details',
+            drawer_minimize: true,
+            minSize: 70,
+            padding: '10px',
+            background: surface,
+        });
+        details.h3('Customer details');
+        details.textbox({ value: '^customer', lbl: 'Customer', width: '100%' });
+        details.p('Pull the closed handle inward to open this panel.');
+        border
+            .contentPane({
+                region: 'bottom',
+                node_id: 'drawerOutput',
+                height: '64px',
+                splitter: true,
+                drawer: '^drawerOutput',
+                drawer_label: 'Output',
+                drawer_title: 'Output',
+                minSize: 36,
+                padding: '10px',
+                background: surface,
+            })
+            .p('^note', { mask: 'Shared note: {}' });
+        const center = border.contentPane({
+            region: 'center',
+            padding: '16px',
+            background: 'var(--gramlot-surface, #fff)',
+        });
+        center.h2('Customer workspace');
+        center.p('^customer', { mask: 'Customer: {}' });
+        center.p('^delivery', { mask: 'Delivery: {}' });
+        center.textbox({
+            id: 'handles-note',
+            value: '^note',
+            lbl: 'Retained value',
+            width: '100%',
+            max_width: '18rem',
+        });
+        center.p(
+            'Move over a handle or focus it with Tab. Its label grows over the panel; the fields do not move.',
+        );
+        center.p(
+            'Click to toggle. Drag to resize, even from closed. On touch devices the captions remain visible and compact at rest.',
+        );
+        for (const title of ['Search', 'Filters', 'Details', 'Output']) {
+            pane.dataSetter({
+                destination_path: `drawer${title}`,
+                value: title === 'Details' ? 'close' : true,
+            });
+            pane.dataController({
+                script: "this.SET(path, open ? true : 'close')",
+                path: `drawer${title}`,
+                ...{ [`subscribe_drawer${title}_closable_change`]: true },
+            });
+        }
+        pane.dataSetter({ destination_path: 'filtersWidth', value: '180px' });
+        pane.dataSetter({ destination_path: 'customer', value: 'Ada Lovelace' });
+        pane.dataSetter({ destination_path: 'search', value: '' });
+        pane.dataSetter({ destination_path: 'active', value: true });
+        pane.dataSetter({ destination_path: 'delivery', value: 'standard' });
+        pane.dataSetter({ destination_path: 'note', value: 'Same Data, every presentation' });
+    }
+}
+
+export class Logic {}

package/src/gramlot_examples/pages/layout/04_drawer_handles.md

@@ -0,0 +1,33 @@
+# Make room without losing your work
+
+Imagine editing a customer while keeping filters, customer details and a short output summary nearby. You need those tools, but you do not need them all on screen all the time. A **drawer** is a panel you can tuck away and bring back with a small handle.
+
+This example has one on each side. Search is above the workspace, Filters is on the left, Details is on the right, and Output is below. Details starts closed.
+
+## Let the page show you
+
+In the gallery, open the lower **Guide** handle and press **Start / Resume**. We will change a delivery option, hide its panel, and bring it back. Then we will change a customer name and a note, showing where those values appear elsewhere.
+
+You can pause whenever you want to try something. **Next** performs one step at a time. **Back** lets you reread an explanation; it does not undo changes. **Stop** leaves the example as it is. Starting again begins the demonstration again, including its changes to the customer, delivery and note.
+
+If you prefer listening, enable **Voice**. It reads the same English explanation using a voice available in your browser. You can follow the lesson with text alone. The guide is part of the gallery, so you will not see it if you open this example on its own.
+
+## Try it
+
+Choose **Express** in Filters and read the delivery line in the center. Now close Filters with its handle. The delivery line still says Express. Open Filters again: Express is still selected.
+
+That is the key idea. Closing a drawer hides a view; it does not erase the values behind it. Gramlot calls those shared values **Data**. The radio group and the delivery line read the same value, so they stay in agreement.
+
+Open Details and enter a different customer name. Leave the field and look at the center. You did not have to copy the name from one widget to another: their bindings connect them to the same Data.
+
+For one more experiment, close Output, change the note in the center and leave its field, then reopen Output. It shows the new note even though it was hidden when you made the edit.
+
+## Small handles, deliberate choices
+
+A click opens or closes a drawer. When a splitter is enabled, you can also drag the handle to resize its panel, even starting from closed. The icon belongs to the caption. By default both stay hidden in a thin grip until you interact; on touch it remains readable without starting zoomed. An author can explicitly request an always-visible caption with drawer_minimize=False.
+
+## Find the idea in Python
+
+In **Code**, look for the contentPane declarations. The region chooses a side; drawer enables opening and closing; drawer_label gives the handle a name. The values beginning with a caret connect those choices to Data. The small controllers below keep that Data up to date when you operate a handle yourself.
+
+You do not need to understand every line to use a drawer. Start with a panel that opens and closes, then add resizing and bindings when your application needs them.

package/src/gramlot_examples/pages/layout/05_nested_lab.js

@@ -0,0 +1,251 @@
+import { Page as BasePage } from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = 'Nested regions playground';
+    static devices = ['desktop', 'tablet', 'phone'];
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const pane = root.main({ class: 'example-page stack' });
+        pane.h1('Five containers, one live workspace');
+        pane.p(
+            'Move the sliders, drag separators and close drawers. The same widgets and their values stay in place.',
+        );
+        const settings = pane.section({
+            display: 'flex',
+            flex_wrap: 'wrap',
+            gap: '12px',
+            align_items: 'end',
+        });
+        settings.filteringSelect({
+            id: 'lab-design',
+            value: '^design',
+            lbl: 'Outer design',
+            width: '10rem',
+            values: 'headline:Headline,sidebar:Sidebar',
+        });
+        settings.checkbox({
+            id: 'lab-minimize',
+            value: '^minimize',
+            lbl: 'Drawer captions',
+            label: 'Minimize',
+        });
+        settings.horizontalSlider({
+            id: 'lab-radius',
+            value: '^radius',
+            lbl: 'Corner radius',
+            min: 0,
+            max: 28,
+            live: true,
+            width: '12rem',
+        });
+        const sliders = pane.section({ display: 'flex', flex_wrap: 'wrap', gap: '12px' });
+        const sizes = [
+            ['outer.top', 'Header height', 40, 110, 58],
+            ['outer.bottom', 'Footer height', 35, 130, 46],
+            ['outer.left', 'Navigation width', 90, 240, 150],
+            ['outer.right', 'Details width', 90, 240, 170],
+            ['workspace.left', 'Tools width', 70, 200, 105],
+            ['workspace.bottom', 'Preview height', 50, 180, 90],
+            ['editor.bottom', 'Notes height', 60, 180, 100],
+        ];
+        for (const [path, caption, minimum, maximum, initial] of sizes) {
+            sliders.horizontalSlider({
+                id: 'size-' + path.replace('.', '-'),
+                value: '^regions.' + path,
+                lbl: `^regions.${path}:${caption} · {} px`,
+                min: minimum,
+                max: maximum,
+                step: 1,
+                live: true,
+                width: '12rem',
+            });
+            pane.dataSetter({ destination_path: 'regions.' + path, value: initial });
+        }
+        const surface = 'var(--gramlot-surface, #fff)';
+        const edge = '1px solid var(--gramlot-border-control, #8192aa)';
+        const fills = {
+            nav: 'color-mix(in srgb, var(--gramlot-surface, #fff) 90%, #4488cc)',
+            tools: 'color-mix(in srgb, var(--gramlot-surface, #fff) 90%, #32a880)',
+            details: 'color-mix(in srgb, var(--gramlot-surface, #fff) 90%, #bb8844)',
+            preview: 'color-mix(in srgb, var(--gramlot-surface, #fff) 90%, #9977bb)',
+        };
+        const drawer = { splitter: true, drawer: true, drawer_minimize: '^minimize' };
+        const outer = pane.borderContainer({
+            id: 'lab-outer',
+            height: '700px',
+            max_width: '78rem',
+            design: '^design',
+            rounded: '^radius',
+            border: edge,
+            background: surface,
+        });
+        const header = outer.contentPane({
+            region: 'top',
+            height: '^regions.outer.top:{}px',
+            minSize: 40,
+            maxSize: 110,
+            drawer_label: 'Header',
+            padding: '10px',
+            background: fills['nav'],
+            ...drawer,
+        });
+        header.strong('Customer workspace · ');
+        header.span('^customer');
+        const footer = outer.contentPane({
+            region: 'bottom',
+            height: '^regions.outer.bottom:{}px',
+            minSize: 35,
+            maxSize: 130,
+            drawer_label: 'Status',
+            padding: '10px',
+            background: fills['preview'],
+            ...drawer,
+        });
+        footer.span('^customer', { mask: 'Customer: {}' });
+        footer.span('^delivery', { mask: ' · Delivery: {}' });
+        const nav = outer.borderContainer({
+            id: 'lab-navigation',
+            region: 'left',
+            width: '^regions.outer.left:{}px',
+            minSize: 90,
+            maxSize: 240,
+            drawer_label: 'Navigation',
+            background: fills['nav'],
+            ...drawer,
+        });
+        nav.contentPane({ region: 'top', height: '40px', padding: '10px' }).strong('Navigation');
+        const navbody = nav.contentPane({ region: 'center', padding: '12px' });
+        navbody.textbox({ id: 'lab-search', value: '^search', lbl: 'Search', width: '100%' });
+        navbody.radioButtonText({
+            value: '^section',
+            lbl: 'Section',
+            values: 'profile:Profile,orders:Orders,history:History',
+            cols: 1,
+        });
+        nav.contentPane({ region: 'bottom', height: '54px', padding: '10px' }).span('^section', {
+            mask: 'Section: {}',
+        });
+        const details = outer.borderContainer({
+            id: 'lab-details',
+            region: 'right',
+            width: '^regions.outer.right:{}px',
+            minSize: 90,
+            maxSize: 240,
+            drawer_label: 'Details',
+            background: fills['details'],
+            ...drawer,
+        });
+        details.contentPane({ region: 'top', height: '40px', padding: '10px' }).strong('Details');
+        const detailfields = details
+            .contentPane({ region: 'center', padding: '12px' })
+            .formlet({ columns: 1 });
+        detailfields.checkbox({ value: '^active', lbl: 'Active', mode: 'switch' });
+        detailfields.textbox({ value: '^customer', lbl: 'Same customer', width: '100%' });
+        detailfields.dateTextBox({
+            id: 'lab-date',
+            value: '^appointment',
+            lbl: 'Appointment',
+            width: '100%',
+        });
+        details
+            .contentPane({ region: 'bottom', height: '60px', padding: '10px' })
+            .p('An independent nested container.');
+        const work = outer.borderContainer({
+            id: 'lab-workspace',
+            region: 'center',
+            rounded: '^radius',
+            border: edge,
+        });
+        const tools = work.contentPane({
+            region: 'left',
+            width: '^regions.workspace.left:{}px',
+            minSize: 70,
+            maxSize: 200,
+            drawer_label: 'Tools',
+            padding: '10px',
+            background: fills['tools'],
+            ...drawer,
+        });
+        tools.strong('Tools');
+        tools.checkbox({ value: '^active', lbl: 'Enabled', mode: 'switch' });
+        tools.checkbox({ value: '^readonly', lbl: 'Editor', label: 'Read only' });
+        const preview = work.contentPane({
+            region: 'bottom',
+            height: '^regions.workspace.bottom:{}px',
+            minSize: 50,
+            maxSize: 180,
+            drawer_label: 'Preview',
+            padding: '12px',
+            background: fills['preview'],
+            ...drawer,
+        });
+        preview.strong('Shared note');
+        preview.p('^note');
+        const editor = work.borderContainer({
+            id: 'lab-editor',
+            region: 'center',
+            rounded: '^radius',
+            border: edge,
+            background: surface,
+        });
+        editor
+            .contentPane({ region: 'top', height: '40px', padding: '10px' })
+            .strong('Editor · third nesting level');
+        const fields = editor
+            .contentPane({ region: 'center', padding: '16px 24px' })
+            .formlet({ columns: 1, max_width: '22rem' });
+        fields.textbox({
+            id: 'lab-customer',
+            value: '^customer',
+            lbl: 'Customer (2–24 characters)',
+            validate_len: '2:24',
+            readonly: '^readonly',
+            width: '100%',
+        });
+        fields.filteringSelect({
+            id: 'lab-delivery',
+            value: '^delivery',
+            lbl: 'Delivery',
+            width: '100%',
+            values: 'standard:Standard,express:Express,pickup:Pick up',
+        });
+        fields.numberTextBox({ id: 'lab-quantity', value: '^quantity', lbl: 'Quantity', width: '100%' });
+        const notes = editor.contentPane({
+            region: 'bottom',
+            height: '^regions.editor.bottom:{}px',
+            minSize: 60,
+            maxSize: 180,
+            drawer_label: 'Notes',
+            padding: '10px 24px',
+            background: fills['tools'],
+            ...drawer,
+        });
+        notes.textBoxArea({
+            id: 'lab-note',
+            value: '^note',
+            lbl: 'Retained draft',
+            rows: 2,
+            live: true,
+            width: '100%',
+        });
+        for (const [key, value] of [
+            ['design', 'headline'],
+            ['minimize', true],
+            ['radius', 12],
+            ['customer', 'Ada Lovelace'],
+            ['search', ''],
+            ['section', 'profile'],
+            ['active', true],
+            ['readonly', false],
+            ['delivery', 'standard'],
+            ['quantity', 3],
+            ['appointment', new Date(Date.UTC(2026, 9, 18))],
+            ['note', 'Resize any region: this note stays here.'],
+        ]) {
+            pane.dataSetter({ destination_path: key, value: value });
+        }
+    }
+}
+
+export class Logic {}

package/src/gramlot_examples/pages/layout/05_nested_lab.md

@@ -0,0 +1,25 @@
+# Explore a layout by moving one thing at a time
+
+This is a small customer workspace with several layouts inside it. It is deliberately busier than the first examples: navigation, details, an editor and output all need space. The sliders let you see which container owns which area.
+
+If the page looks complicated at first, start with just one slider. You do not need to understand the whole arrangement at once.
+
+## Try it
+
+Move one region-size slider a little, then back again. Follow the boundary that moves. Does it belong to the outer workspace, or to a layout inside it? Repeat with a slider for a different level.
+
+Now enter a customer name and a note. Change a date or delivery option too. Look for the places where those values are repeated. They are views of shared Data, not separate copies of the customer.
+
+Move the sliders again. The regions become wider, narrower, taller or shorter while your edits remain. Close one drawer, rearrange another area, and reopen it. Hiding a panel has not discarded its contents.
+
+Finally, try the design and corner-radius controls. These change presentation while the same customer workspace stays alive.
+
+## How a number becomes a size
+
+A slider produces a number. A region width needs a size such as 180px. The example connects them with a pointer template: it reads the slider's Data value and adds the unit. You can find these declarations by looking for the region-size paths in **Code**.
+
+The nested containers still have a simple responsibility: each lays out its own immediate children. The outer container does not calculate the positions of every field inside the editor.
+
+## What to take into your own page
+
+Build the outer layout first, then give a region its own container only when it needs independent areas. Connect sizes to Data if users or application logic need to control them. Ordinary splitters are enough when you only want people to resize by dragging.

package/src/gramlot_examples/pages/layout/06_border_events.js

@@ -0,0 +1,118 @@
+import { Page as BasePage } from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = 'Border events and controllers';
+    static devices = ['desktop', 'tablet', 'phone'];
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const pane = root.main({ class: 'example-page stack', datapath: 'events' });
+        for (const [name, value] of [
+            ['drawerCount', 0],
+            ['resizeCount', 0],
+            ['drawerMessage', 'No visibility change yet'],
+            ['resizeMessage', 'No completed resize yet'],
+            ['drawerPayload', '{}'],
+            ['resizePayload', '{}'],
+            ['hideFilters', false],
+            ['name', 'Ada'],
+            ['note', 'Keep this draft'],
+        ]) {
+            pane.dataSetter({ destination_path: `.${name}`, value: value });
+        }
+        pane.dataController({
+            script: "this.SET('.drawerCount', count + 1); this.SET('.drawerMessage', region + ': ' + (open ? 'open' : 'closed')); this.SET('.drawerPayload', JSON.stringify(_subscription_kwargs));",
+            count: '=.drawerCount',
+            subscribe_eventFilters_closable_change: true,
+        });
+        pane.dataController({
+            script: "this.SET('.resizeCount', count + 1); this.SET('.resizeMessage', region + ': ' + previousSize + ' → ' + size); this.SET('.resizePayload', JSON.stringify(_subscription_kwargs));",
+            count: '=.resizeCount',
+            subscribe_eventWorkspace_splitter_resize: true,
+        });
+        pane.h1('Observe a drawer and a splitter');
+        pane.p(
+            'Toggle Filters, drag a separator, or focus a separator and use its arrow keys. The controllers below receive the published payloads.',
+        );
+        pane.checkbox({ id: 'events-hide', value: '^.hideFilters', label: 'Hide Filters from Data' });
+        const border = pane.borderContainer({
+            id: 'events-border',
+            node_id: 'eventWorkspace',
+            height: '360px',
+            max_width: '48rem',
+            rounded: 10,
+            border: '1px solid var(--gramlot-border-control, #aaa)',
+        });
+        const filters = border.contentPane({
+            node_id: 'eventFilters',
+            region: 'left',
+            width: '130px',
+            minSize: 90,
+            maxSize: 230,
+            splitter: true,
+            drawer: true,
+            drawer_label: 'Filters',
+            hidden: '^.hideFilters',
+            padding: '12px',
+            background: 'var(--gramlot-surface-subtle, #eef1f5)',
+            border_right: '1px solid var(--gramlot-border-control, #aaa)',
+        });
+        filters.p('This pane publishes closable_change.');
+        filters.textbox({
+            id: 'events-name',
+            value: '^.name',
+            lbl: 'Name (2–20)',
+            validate_len: '2:20',
+            width: '100%',
+        });
+        const center = border.contentPane({
+            region: 'center',
+            padding: '16px',
+            background: 'var(--gramlot-surface, #fff)',
+        });
+        center.textBoxArea({
+            id: 'events-note',
+            value: '^.note',
+            lbl: 'Retained draft',
+            rows: 3,
+            width: '100%',
+            max_width: '18rem',
+        });
+        center.p(
+            'Live resizing keeps these widgets mounted. The resize counter changes only when the gesture finishes.',
+        );
+        border
+            .contentPane({
+                region: 'bottom',
+                height: '52px',
+                minSize: 36,
+                maxSize: 120,
+                splitter: true,
+                padding: '12px',
+                border_top: '1px solid var(--gramlot-border-control, #aaa)',
+                background: 'var(--gramlot-surface-subtle, #eef1f5)',
+            })
+            .p('Resize this bottom region too.');
+        const report = pane.section({ class: 'card stack', max_width: '48rem' });
+        report.h2('Received by dataController');
+        report.p('^.drawerCount', { id: 'events-drawer-count', mask: 'Visibility events: {}' });
+        report.p('^.drawerMessage');
+        report.pre('^.drawerPayload', {
+            id: 'events-drawer-payload',
+            white_space: 'pre-wrap',
+            overflow_wrap: 'anywhere',
+        });
+        report.p('^.resizeCount', { id: 'events-resize-count', mask: 'Completed resizes: {}' });
+        report.p('^.resizeMessage');
+        report.pre('^.resizePayload', {
+            id: 'events-resize-payload',
+            white_space: 'pre-wrap',
+            overflow_wrap: 'anywhere',
+        });
+        pane.p(
+            "No events are emitted at startup. The Data checkbox changes visibility too; it does not change the drawer's own open/closed preference.",
+        );
+    }
+}
+
+export class Logic {}

package/src/gramlot_examples/pages/layout/06_border_events.md

@@ -0,0 +1,25 @@
+# Let another part of your page know what happened
+
+Suppose you want a small status message whenever someone closes a panel. You should not have to watch the browser's HTML or write a second click handler for the drawer. The container can announce the change, and your page can listen.
+
+Those announcements are **events**. A **dataController** is a small piece of page logic that runs when an event it subscribes to arrives. Here, controllers turn drawer and splitter events into counters and readable messages.
+
+## Try it
+
+Close Filters and look at **Visibility events**. The count increases and the message says that the left region is closed. Open it again: you receive another change.
+
+Now drag a separator slowly. The panel follows your hand immediately, but **Completed resizes** changes when you finish dragging. This is useful if your application wants to react to the final size rather than every small movement.
+
+Use **Hide Filters from Data**. The region disappears and the visibility report updates too. An event describes a change in the interface, not just a particular mouse click. Untick it to restore visibility; the drawer's own open or closed preference is a separate setting.
+
+## Reading the extra details
+
+The structured text below each message is the event's **payload**: the details sent with the announcement. For visibility, look for the region and whether it is open. For resizing, compare the previous size with the new size. You do not need to memorize the whole object.
+
+## Connecting your own controller
+
+The Filters pane has a node_id of eventFilters. The controller's subscribe_eventFilters_closable_change parameter listens to its visibility announcement. The other subscription names eventWorkspace, the container, and splitter_resize, its completed-resize event.
+
+Read the name in three parts: subscribe, the component's identity, and the event. The controller receives the details and writes its result into Data. The counters on screen then update through normal bindings.
+
+No event is counted just because the page starts. Try an action and watch the result: this is a conversation between existing components, not a replacement for their normal behavior.