@gramlot/gramlot-examples 0.3.3 → 0.3.4

package/src/gramlot_examples/pages/layout/07_tabs.js

@@ -0,0 +1,300 @@
+import { Page as BasePage } from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = 'Tabs, selection and closing';
+    static devices = ['desktop', 'tablet', 'phone'];
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const pane = root.main({ class: 'example-page stack', datapath: 'tabsDemo' });
+        for (const [key, value] of [
+            ['page', 'customer'],
+            ['index', 0],
+            ['name', 'Ada'],
+            ['notes', 'These Data survive closing Notes.'],
+            ['variantMessage', 'Please confirm the delivery address.'],
+            ['mode', 'tabs'],
+            ['position', 'top'],
+            ['align', 'start'],
+            ['unread', 3],
+            ['badgeColor', 'crimson'],
+            ['notesIcon', '✉'],
+            ['locked', false],
+            ['events', ''],
+            ['closed', 'None'],
+        ]) {
+            pane.dataSetter({ destination_path: `.${key}`, value: value });
+        }
+        for (const topic of ['hiding', 'showing', 'selected', 'closing', 'closed']) {
+            pane.dataController({
+                script: "this.SET('.events', history + topic + ': ' + JSON.stringify(_subscription_kwargs) + '\\n');",
+                history: '=.events',
+                topic: topic,
+                ...{ [`subscribe_editor_${topic}`]: true },
+            });
+        }
+        pane.dataController({ script: "this.SET('.closed', pageName)", subscribe_editor_closed: true });
+        this.tab_variants(pane);
+        this.tab_alignment(pane);
+        pane.h2('Try the controls, selection and closing');
+        pane.p(
+            'Try a one-letter name, switch away and return: the invalid draft remains. Close Notes: its Source disappears, but the saved notes below remain.',
+        );
+        const controls = pane.formlet({ col_min_width: '14rem', max_width: '36rem' });
+        controls.filteringSelect({
+            id: 'tabs-choice',
+            value: '^.page',
+            lbl: 'Selected page',
+            values: 'customer:Customer,notes:Notes,layout:Nested border',
+        });
+        controls.filteringSelect({
+            id: 'tabs-mode',
+            value: '^.mode',
+            lbl: 'Presentation',
+            values: 'tabs:Tabs,underline:Underline',
+        });
+        controls.filteringSelect({
+            id: 'tabs-position',
+            value: '^.position',
+            lbl: 'Tab position',
+            values: 'top:Top,bottom:Bottom,left:Left,right:Right',
+        });
+        controls.filteringSelect({
+            id: 'tabs-align',
+            value: '^.align',
+            lbl: 'Alignment along the strip',
+            values: 'start:Start,center:Center,end:End',
+        });
+        controls.horizontalSlider({
+            id: 'tabs-unread',
+            value: '^.unread',
+            lbl: 'Unread messages',
+            min: 0,
+            max: 12,
+            step: 1,
+            live: true,
+            width: '14rem',
+            max_width: '100%',
+        });
+        controls.filteringSelect({
+            id: 'tabs-badge-color',
+            value: '^.badgeColor',
+            lbl: 'Badge color',
+            values: 'crimson:Crimson,seagreen:Green,royalblue:Blue',
+        });
+        controls.filteringSelect({
+            id: 'tabs-icon',
+            value: '^.notesIcon',
+            lbl: 'Notes icon',
+            values: '✉:Envelope,●:Dot,★:Star',
+        });
+        controls.checkbox({
+            id: 'tabs-lock',
+            value: '^.locked',
+            label: 'Prevent closing Notes',
+            mode: 'switch',
+        });
+        pane.p(
+            'Change position and presentation while keeping a draft. Move the unread slider while Notes is inactive: its badge updates immediately.',
+        );
+        pane.p('^.index', { id: 'tabs-index', mask: 'Selected index: {}' });
+        const tabs = pane.tabContainer({
+            id: 'tabs-demo',
+            node_id: 'editor',
+            selectedPage: '^.page',
+            selected: '^.index',
+            tabMode: '^.mode',
+            tabPosition: '^.position',
+            tabAlign: '^.align',
+            height: '300px',
+            max_width: '44rem',
+            border: '1px solid var(--gramlot-border-control, #aaa)',
+            rounded: 6,
+        });
+        const customer = tabs.contentPane({
+            id: 'customer-panel',
+            pageName: 'customer',
+            title: 'Customer',
+            icon: '👤',
+            padding: '12px',
+        });
+        customer.textbox({
+            id: 'tabs-name',
+            value: '^.name',
+            lbl: 'Name (2–20)',
+            validate_len: '2:20',
+            live: true,
+            width: '15rem',
+        });
+        customer.p('The accepted Data value:');
+        customer.p('^.name', { id: 'tabs-accepted' });
+        const notes = tabs.contentPane({
+            id: 'notes-panel',
+            pageName: 'notes',
+            title: 'Notes',
+            icon: '^.notesIcon',
+            badge: '^.unread',
+            badge_color: '^.badgeColor',
+            closable: true,
+            onClose: "return !this.GET('.locked')",
+            padding: '12px',
+        });
+        notes.textBoxArea({
+            id: 'tabs-notes',
+            value: '^.notes',
+            lbl: 'Notes',
+            rows: 3,
+            width: '100%',
+            max_width: '24rem',
+        });
+        const nested = tabs.borderContainer({
+            id: 'tabs-border',
+            pageName: 'layout',
+            title: 'Nested border',
+            icon: '▦',
+        });
+        nested
+            .contentPane({
+                region: 'left',
+                width: '100px',
+                splitter: true,
+                drawer: true,
+                drawer_label: 'Tools',
+                padding: '10px',
+                background: 'var(--gramlot-surface-subtle, #eef1f5)',
+            })
+            .p('Resize me');
+        nested
+            .contentPane({ region: 'center', padding: '12px' })
+            .textbox({ value: '^.name', lbl: 'Same accepted name', width: '15rem' });
+        pane.p('^.closed', { id: 'tabs-closed', mask: 'Last closed: {}' });
+        pane.p('^.notes', { id: 'tabs-saved-notes', mask: 'Saved notes: {}' });
+        pane.h2('Container events');
+        pane.pre('^.events', {
+            id: 'tabs-events',
+            max_height: '12rem',
+            overflow: 'auto',
+            white_space: 'pre-wrap',
+            overflow_wrap: 'anywhere',
+        });
+    }
+
+    tab_variants(pane) {
+        pane.h1('See the tab variants side by side');
+        pane.p(
+            'Compare shaped tabs with a light underline, on each of the four sides. Every card is a working editor. Change the name in one: the others show the same Data.',
+        );
+        pane.p(
+            'Top and bottom use a horizontal row. Left and right use a vertical list; the words remain horizontal so they are easy to read.',
+        );
+        const grid = pane.section({
+            id: 'tab-variants',
+            display: 'grid',
+            grid_template_columns: 'repeat(auto-fit, minmax(min(100%, 24rem), 1fr))',
+            gap: '16px',
+            width: '100%',
+            max_width: '72rem',
+        });
+        for (const [position, caption] of [
+            ['top', 'Top'],
+            ['bottom', 'Bottom'],
+            ['left', 'Left'],
+            ['right', 'Right'],
+        ]) {
+            for (const [mode, presentation] of [
+                ['tabs', 'Shaped tabs'],
+                ['underline', 'Underline'],
+            ]) {
+                const key = `${mode}-${position}`;
+                this.variant_card(grid, key, `${presentation} · ${caption}`, mode, position);
+            }
+        }
+    }
+
+    tab_alignment(pane) {
+        pane.h2('Align the labels along the strip');
+        pane.p(
+            'Position chooses the side of the panel. Alignment chooses where the labels sit along that side. Compare the three horizontal rows, then the three vertical lists.',
+        );
+        const grid = pane.section({
+            id: 'tab-alignment',
+            display: 'grid',
+            grid_template_columns: 'repeat(auto-fit, minmax(min(100%, 22rem), 1fr))',
+            gap: '16px',
+            width: '100%',
+            max_width: '72rem',
+        });
+        for (const [position, axis, captions] of [
+            ['top', 'Horizontal', ['Left', 'Center', 'Right']],
+            ['left', 'Vertical', ['Top', 'Center', 'Bottom']],
+        ]) {
+            for (const [align, caption] of ['start', 'center', 'end'].map((value, i) => [
+                value,
+                captions[i],
+            ])) {
+                this.variant_card(
+                    grid,
+                    `align-${position}-${align}`,
+                    `${axis} · ${caption}`,
+                    'underline',
+                    position,
+                    align,
+                );
+            }
+        }
+    }
+
+    variant_card(grid, key, title, mode, position, align = 'start') {
+        const card = grid.section({ min_width: 0 });
+        card.h2(title, { font_size: '1rem', margin: '0 0 6px' });
+        card.p(`tabMode="${mode}", tabPosition="${position}", tabAlign="${align}"`, {
+            font_family: 'var(--gramlot-font-code)',
+            font_size: '.8rem',
+            margin: '0 0 8px',
+        });
+        const tabs = card.tabContainer({
+            id: `tabs-variant-${key}`,
+            tabMode: mode,
+            tabPosition: position,
+            tabAlign: align,
+            height: '240px',
+            width: '100%',
+            border: '1px solid var(--gramlot-border-control)',
+            rounded: 6,
+        });
+        const profile = tabs.contentPane({ pageName: 'profile', title: 'Profile', padding: '12px' });
+        profile.textbox({
+            id: `variant-name-${key}`,
+            value: '^.name',
+            lbl: 'Customer name',
+            width: '100%',
+            max_width: '15rem',
+            live: true,
+        });
+        profile.p('Switch to Messages and back. Your edit stays here.', { font_size: '.9rem' });
+        const messages = tabs.contentPane({
+            pageName: 'messages',
+            title: 'Messages',
+            icon: '✉',
+            badge: '^.unread',
+            badge_color: '^.badgeColor',
+            padding: '12px',
+        });
+        messages.textBoxArea({
+            value: '^.variantMessage',
+            lbl: 'Message',
+            rows: 2,
+            width: '100%',
+            live: true,
+        });
+        messages.p('The badge remains visible when this panel is hidden.', { font_size: '.9rem' });
+        const activity = tabs.contentPane({ pageName: 'activity', title: 'Activity', padding: '12px' });
+        activity.h3('Customer updated', { font_size: '1rem' });
+        activity.p('^.name', { mask: 'Latest name: {}' });
+        activity.p('Each card selects its own panel; only the business values are shared.', {
+            font_size: '.9rem',
+        });
+    }
+}
+
+export class Logic {}

package/src/gramlot_examples/pages/layout/07_tabs.md

@@ -0,0 +1,37 @@
+# Choose the presentation by looking at it
+
+The first eight cards compare two presentations on all four sides. **Shaped tabs** give each label a visible outline; **Underline** leaves a lighter row or list of text, with a line marking the selected panel. You can click every card: these are real containers, not pictures.
+
+**Top** and **Bottom** place the labels in a horizontal row. **Left** and **Right** place them in a vertical list. The text itself stays horizontal: a vertical tab list does not require rotated words. Each card prints the mode, position and alignment options that create it.
+
+Type a name in one **Profile** panel. The other cards update because their editors share the same Data path. Open **Messages**, edit its text, and return to Profile. Changing panels keeps the controls and their values. Each card has independent selection, so you can compare different panels at the same time.
+
+The next six cards separate **position** from **alignment**. Position chooses a side; `tabAlign` chooses where the labels sit along that side. With a horizontal bar, `start`, `center`, `end` mean left, middle, right. With a vertical bar they mean top, middle, bottom. The default is `start`. If the labels no longer fit, the strip keeps its beginning reachable and lets you scroll through the entries.
+
+The controls below the comparison let you change the presentation of one larger editor, adjust icons and unread badges, and explore closing. The unread-message slider also updates the badges in the cards above.
+
+## Keep several tasks within reach
+
+Tabs let someone move between parts of a task without opening a new page. Here you can edit a customer, write notes, and visit a nested layout. Only one panel is visible at a time, but changing tabs keeps the others ready for your return.
+
+There is an important distinction to learn: **switching away from a panel is not the same as closing it**.
+
+## Try it
+
+Write a note in **Notes**, select **Customer**, then return. Your note is still there. In Customer, try a one-letter name: it is too short, so it stays as an unfinished edit while the accepted name below remains unchanged. Switch away and return again. Even that unfinished edit survives.
+
+Now use **Presentation** and **Tab position**. Underline gives you a lighter row of labels; Tabs gives you shaped tabs. Move the row to the bottom or to either side. These are different presentations of the same panels.
+
+While Notes is hidden, move **Unread messages**. The number beside Notes changes without opening the panel. That little number is a **badge**: a way to show that something deserves attention elsewhere. Try its color and icon controls as well.
+
+## Closing deserves a separate experiment
+
+Turn on **Prevent closing Notes** and try its close button. The panel stays. Turn the lock off and try again: this time the tab and its panel are removed. The **Saved notes** line still contains the note, because removing an editor does not automatically erase the Data it was editing.
+
+After closing Notes, it is no longer a selectable tab. Reload this example when you want to repeat that part of the lesson.
+
+## How selection connects to your page
+
+Each panel has a pageName, a stable name such as customer or notes. The container's selectedPage can bind to Data, which is why **Selected page** and clicking a tab can control the same selection. The numeric selected value is its position in the list, starting at zero.
+
+The event report lets you see which panel is being hidden, shown or closed. It is useful when another part of your application needs to react, but you do not need a controller just to switch ordinary tabs: the container already does that.

package/src/gramlot_examples/pages/layout/08_stack.js

@@ -0,0 +1,142 @@
+import { Page as BasePage } from '@gramlot/gramlot/page';
+import catalog from '../../catalog.json' with { type: 'json' };
+
+export class Page extends BasePage {
+    // The static exporter supplies its file routes; the hosted gallery uses route keys.
+    static galleryUrls = Object.fromEntries(
+        catalog.families.flatMap((family) => family.examples).map((demo) => [demo.key, demo.key]),
+    );
+    static title = 'Demo carousel and live preview';
+    static devices = ['desktop', 'tablet', 'phone'];
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const demos = catalog.families
+            .flatMap((family) => family.examples)
+            .filter((demo) => demo.key !== 'l08');
+        const pane = root.main({ class: 'example-page stack', datapath: 'stackDemo' });
+        for (const [key, value] of [
+            ['panel', 0],
+            ['page', demos[0]['key']],
+            ['caption', demos[0]['title']],
+            ['active', demos[0]['key']],
+            ['activeCaption', demos[0]['title']],
+            ['event', ''],
+        ]) {
+            pane.dataSetter({ destination_path: `.${key}`, value: value });
+        }
+        for (const demo of demos) {
+            pane.dataSetter({
+                destination_path: `.urls.${demo.key}`,
+                value: this.constructor.galleryUrls[demo.key],
+            });
+            pane.dataSetter({ destination_path: `.titles.${demo['key']}`, value: demo['title'] });
+            pane.dataSetter({ destination_path: `.opened.${demo['key']}`, value: null });
+        }
+        pane.dataController({
+            script: "if (selected) { this.SET('.caption', this.GET('.titles.' + page)); } this.SET('.event', JSON.stringify(_subscription_kwargs));",
+            subscribe_demoStack_selected: true,
+        });
+        pane.dataController({
+            script: "this.SET('.opened.' + demo, this.GET('.urls.' + demo)); this.SET('.active', demo); this.SET('.activeCaption', this.GET('.titles.' + demo));",
+            demo: '^.page',
+            _delay: 350,
+            _onStart: true,
+        });
+        pane.h1('Browse, pause and try the demo');
+        pane.p(
+            `Slide through ${demos.length} thumbnails in the drawer. Pause to open the full-size demo in the center. Close the drawer for more space.`,
+        );
+        const border = pane.borderContainer({
+            id: 'carousel-layout',
+            height: 'min(76vh, 680px)',
+            min_height: '420px',
+            rounded: 6,
+            border: '1px solid var(--gramlot-border-control, #aaa)',
+        });
+        border
+            .contentPane({
+                region: 'top',
+                height: '36px',
+                padding: '8px 12px',
+                border_bottom: '1px solid var(--gramlot-border, #ccc)',
+                background: 'var(--gramlot-surface-subtle, #eef1f5)',
+            })
+            .strong('^.activeCaption', { id: 'stack-active-title', mask: 'Live demo: {}' });
+        const drawer = border.contentPane({
+            id: 'carousel-drawer',
+            region: 'left',
+            width: '260px',
+            splitter: true,
+            minSize: 180,
+            maxSize: 400,
+            drawer: true,
+            drawer_label: 'Demos',
+            drawer_icon: '▦',
+            padding: '12px',
+            background: 'var(--gramlot-surface-subtle, #eef1f5)',
+            border_right: '1px solid var(--gramlot-border, #ccc)',
+            overflow: 'auto',
+        });
+        drawer.horizontalSlider({
+            id: 'stack-panel',
+            value: '^.panel',
+            lbl: `Demo index (0–${demos.length - 1})`,
+            min: 0,
+            max: demos.length - 1,
+            step: 1,
+            live: true,
+            width: '100%',
+            min_width: 0,
+        });
+        drawer.h2('^.caption', { id: 'stack-caption', margin_top: '12px' });
+        drawer.p('^.page', { id: 'stack-page', mask: 'Demo: {}' });
+        const thumbnails = drawer.stackContainer({
+            id: 'stack-demo',
+            node_id: 'demoStack',
+            selectedPage: '^.page',
+            selected: '^.panel',
+            height: '300px',
+            rounded: 4,
+            border: '1px solid var(--gramlot-border-control, #aaa)',
+        });
+        const center = border.contentPane({ region: 'center', background: 'var(--gramlot-surface, #fff)' });
+        const full = center.stackContainer({ id: 'stack-full', selectedPage: '^.active', height: '100%' });
+        for (const demo of demos) {
+            const panel = thumbnails.contentPane({
+                pageName: demo['key'],
+                position: 'relative',
+                overflow: 'hidden',
+            });
+            panel.iframe({
+                id: `mini-${demo['key']}`,
+                src: this.constructor.galleryUrls[demo.key],
+                title: demo['title'],
+                loading: 'lazy',
+                position: 'absolute',
+                top: 0,
+                left: 0,
+                width: '200%',
+                height: '200%',
+                border: 0,
+                transform: 'scale(0.5)',
+                max_width: 'none',
+                style: 'transform-origin:top left',
+            });
+            full.contentPane({ pageName: demo['key'] }).iframe({
+                id: `live-${demo['key']}`,
+                src: `^.opened.${demo['key']}`,
+                title: `Live: ${demo['title']}`,
+                width: '100%',
+                height: '100%',
+                border: 0,
+                display: 'block',
+            });
+        }
+        pane.p(
+            'The center loads a demo only after a pause and keeps visited pages mounted. Thumbnail and full-size views have independent Data. This overview excludes itself.',
+        );
+    }
+}
+
+export class Logic {}

package/src/gramlot_examples/pages/layout/08_stack.md

@@ -0,0 +1,27 @@
+# Browse a gallery without losing your place
+
+A **stackContainer** holds several panels but shows just one at a time. Unlike a tabContainer, it does not add a row of tabs. You choose how people move between panels. This example uses a slider, so you can quickly browse many demos.
+
+There are two viewing areas. The left drawer is a small preview browser. The center is a full-size demo you can actually use.
+
+## Try it
+
+Move the slider slowly. Watch the title and miniature change as you move. Stop on a demo that interests you. After a short pause, the center opens that demo at its normal size.
+
+Now sweep quickly past several entries. The center waits until you settle instead of opening every demo you pass. This small delay makes browsing calmer and avoids loading pages you never intended to try.
+
+Choose a demo with a text field. Enter something in the full-size view, visit another demo, then return. The first page is still there with your edit. Choosing a different stack panel hid it; it did not reload it.
+
+Close the carousel drawer when you want more room for the center. Open it again when you want to browse further.
+
+## Why the miniature and the large view differ
+
+Each is a separate embedded page, called an **iframe**. They show the same example, but they do not share its Data. Typing in the large view will not type into the miniature. Each view keeps its own edits when you leave and return.
+
+Full-size demos are loaded on their first settled visit. A demo you skip quickly is not loaded in the center. Miniatures use the browser's lazy loading, so the browser decides when to fetch them. This carousel excludes itself to avoid opening another carousel inside every preview.
+
+## How the pause works
+
+The slider changes the preview selection immediately. A dataController waits 350 milliseconds after the latest selection change before updating the center. This is called **debouncing**: wait until the user pauses, then act on their final choice.
+
+In **Code**, look for the two stackContainers and the controller with _delay=350. Read them as three jobs: browse now, wait briefly, then show the chosen page. You can use the same idea for a search field that waits for someone to stop typing before searching.

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

@@ -0,0 +1,15 @@
+# Learn to arrange a workspace
+
+A useful screen needs room for the task in front of you, while keeping other tools within reach. In these lessons you will build that idea one step at a time: divide the space, put one layout inside another, tuck panels away, and move between tasks without losing your edits.
+
+You can start by playing with a page. Its **Explanation** tab tells you what to try and what the result means. Open **Code** when you want to connect that behavior to Python or JavaScript. There is no need to understand every declaration before your first experiment.
+
+## A route through the lessons
+
+Start with **Border regions and splitters**. Learn what a region is and how the center makes room when you resize a side panel. Continue with **Nested borders** to give part of a page its own layout, then **Rounded borders** to combine that layout with calendars and other popups.
+
+**Drawers** shows how to put tools away without losing their values. Its **Guide** handle opens a step-by-step demonstration, with optional voice. Once you are comfortable, **Nested regions playground** gives you a larger workspace to explore.
+
+**Border events** explains how your page can hear about a change and react. **Tabs** introduces switching between panels and the different meaning of closing one. Finally, **Demo carousel** uses a slider to browse a stack of pages, with a short pause before opening the chosen page at full size.
+
+The same lessons run in the Python, JavaScript and offline galleries. Code shows the language of the gallery you are using.