@gramlot/gramlot-examples 0.3.3 → 0.3.5

package/src/gramlot_examples/gallery/guided-demo.js

@@ -0,0 +1,151 @@
+const STEPS = [
+    {
+        title: 'Meet your workspace',
+        text: 'Imagine you are editing a customer. Search is above the form, Filters is on the left, and Output is below. Details is tucked away on the right. Each small handle lets you bring a tool into view or put it away. We will try that together.',
+        changes: {
+            drawerSearch: true,
+            drawerFilters: true,
+            drawerDetails: 'close',
+            drawerOutput: true,
+        },
+        seconds: 14,
+    },
+    {
+        title: 'One choice, shown in two places',
+        text: 'Look at Filters: Express is now selected. The delivery line in the center also says express. These are two views of the same stored value. Gramlot calls these shared values Data. You do not need to copy the choice from the radio group into the summary.',
+        changes: {
+            delivery: 'express',
+        },
+        seconds: 14,
+    },
+    {
+        title: 'Put the filters away',
+        text: 'We have closed Filters to give the form more room. Notice that the delivery line still says express. Hiding the panel has not cancelled your choice. A drawer is useful when you need a tool nearby, but do not want it taking up space all the time.',
+        changes: {
+            drawerFilters: 'close',
+        },
+        seconds: 14,
+    },
+    {
+        title: 'Bring your choice back',
+        text: 'Filters is open again, and Express is still selected. We have also made the panel a little wider. Nothing had to be filled in again. You can pause here and try dragging its thin separator or its handle to choose a comfortable width yourself.',
+        changes: {
+            drawerFilters: true,
+            filtersWidth: '220px',
+        },
+        seconds: 14,
+    },
+    {
+        title: 'Edit once, see it wherever you need it',
+        text: 'Details has opened on the right, and the customer is now Grace Hopper. Look at the name in the center too. Both places are connected to the same customer value. This connection is called a binding: when the value changes, the places reading it update.',
+        changes: {
+            drawerDetails: true,
+            customer: 'Grace Hopper',
+        },
+        seconds: 14,
+    },
+    {
+        title: 'The customer stays, even when the editor is hidden',
+        text: 'Details is closed, but the center still shows Grace Hopper. We have hidden the place where you edit the customer, not removed the customer. You can open Details again whenever you need it; its field will still have that name.',
+        changes: {
+            drawerDetails: 'close',
+        },
+        seconds: 14,
+    },
+    {
+        title: 'Change something while its summary is hidden',
+        text: 'We have closed Output and changed the note in the center. Read the field: it now says Written while Output was closed. Can a panel that was hidden keep up with that change? In the next step we will open it and see.',
+        changes: {
+            drawerOutput: 'close',
+            note: 'Written while Output was closed',
+        },
+        seconds: 14,
+    },
+    {
+        title: 'Your work is still here',
+        text: 'Output is back, and it shows the new note. That is the main idea: drawers let you rearrange what you see while your work stays in place. Try it yourself now. Change the note, leave its field, close Output, and open it again. There is no extra save or copy step in this example.',
+        changes: {
+            drawerOutput: true,
+        },
+        seconds: 14,
+    },
+];
+
+export function guidedDemo(parent) {
+    for (const [name, value] of Object.entries({
+        steps: STEPS,
+        status: 'ready',
+        position: -1,
+        executed: -1,
+        count: STEPS.length,
+        progress: `Ready · ${STEPS.length} steps`,
+        title: 'Let’s explore drawers together',
+        text: 'Press Start to watch the workspace change, or Next to take one step at a time. You can pause and try the handles yourself whenever you like.',
+        voice: false,
+        rate: '1',
+        voiceAvailable: false,
+        voiceMessage: '',
+        available: false,
+    })) {
+        parent.dataSetter({ destination_path: `galleryGuide.${name}`, value: value });
+    }
+    const panel = parent.contentPane({
+        region: 'bottom',
+        height: '190px',
+        minSize: 140,
+        maxSize: 300,
+        splitter: true,
+        drawer: true,
+        drawer_label: 'Guide',
+        drawer_icon: '▶',
+        node_id: 'galleryGuidePanel',
+        id: 'gallery-guide',
+        class: 'gallery-guide',
+        padding: '12px 16px',
+        border_top: '1px solid var(--gramlot-border)',
+        background: 'var(--gramlot-surface-subtle)',
+    });
+    const toolbar = panel.div({ class: 'gallery-guide-toolbar' });
+    for (const [name, caption, disabled] of [
+        ['Play', '▶ Start / Resume', "^galleryGuide.status:= {} === 'running' || !{available}"],
+        ['Pause', 'Ⅱ Pause', "^galleryGuide.status:= {} !== 'running'"],
+        ['Stop', '■ Stop', "^galleryGuide.status:= !['running','paused'].includes({})"],
+        ['Previous', '← Back', '^galleryGuide.position:= {} <= 0'],
+        ['Next', 'Next →', '^galleryGuide.position:= {} >= {count} - 1 || !{available}'],
+    ]) {
+        toolbar.button(caption, {
+            node_id: `galleryGuide${name}`,
+            id: `gallery-guide-${name.toLowerCase()}`,
+            action: "this.publish('command')",
+            disabled: disabled,
+            available: '^galleryGuide.available',
+            count: '^galleryGuide.count',
+        });
+    }
+    toolbar.checkbox({
+        value: '^galleryGuide.voice',
+        label: 'Voice',
+        id: 'gallery-guide-voice',
+        disabled: '^galleryGuide.voiceAvailable:=!{}',
+    });
+    const speed = toolbar.select({
+        value: '^galleryGuide.rate',
+        aria_label: 'Narration speed',
+        id: 'gallery-guide-rate',
+        width: '5em',
+    });
+    for (const [value, caption] of [
+        ['0.8', '0.8×'],
+        ['1', '1×'],
+        ['1.2', '1.2×'],
+    ]) {
+        speed.option(caption, { value: value });
+    }
+    toolbar.span('^galleryGuide.progress', { id: 'gallery-guide-progress', role: 'status' });
+    panel.strong('^galleryGuide.title', { id: 'gallery-guide-title' });
+    panel.p('^galleryGuide.text', { id: 'gallery-guide-text', aria_live: 'polite' });
+    panel.p('^galleryGuide.voiceMessage', { id: 'gallery-guide-voice-message', role: 'status' });
+    panel.small(
+        'The tour changes delivery, customer and note. Stop keeps the current values. Back reviews the explanation only.',
+    );
+}

package/src/gramlot_examples/gallery/page.js

@@ -14,14 +14,14 @@ export class Page extends GalleryPage {
         return families.map(({key, title, path, examples}) => {
             const read = name => readFileSync(join(path, name), 'utf8');
             return {
-                key, title, readme: read('README.md'),
+                key, title, get readme() { return read('README.md'); },
                 examples: examples.map(example => ({
-                    key: example.key, title: example.title, folder: example.folder, frameUrl: example.key,
-                    readme: read(`${example.folder}.md`),
-                    source: read(`${example.folder}.js`),
+                    key: example.key, title: example.title, description: example.description, folder: example.folder, frameUrl: example.key,
+                    get readme() { return read(`${example.folder}.md`); },
+                    get source() { return read(`${example.folder}.js`); },
                     // The page module shows its own Logic; only a companion NN_name_aux.js is shown apart.
-                    logic: routes[example.key].logic === routes[example.key].page
-                        ? null : readFileSync(routes[example.key].logic, 'utf8'),
+                    get logic() { return routes[example.key].logic === routes[example.key].page
+                        ? null : readFileSync(routes[example.key].logic, 'utf8'); },
                 })),
             };
         });

package/src/gramlot_examples/index.js

@@ -52,6 +52,7 @@ export function buildGallery({catalogs = []} = {}) {
     const resolve = specifier => fileURLToPath(import.meta.resolve(specifier));
     const routes = {index: {page: join(gallery, 'page.js'), stylesheet: null, logic: null}};
     const filesByUrl = [
+        ['/catalog.json', join(PACKAGE, 'catalog.json')],
         ['/themes/gramlot-base/theme.css', resolve('@gramlot/gramlot/themes/gramlot-base/theme.css')],
         ['/assets/branding/gramlot-logo-dark.svg', resolve('@gramlot/gramlot/assets/branding/gramlot-logo-dark.svg')],
         ['/assets/branding/app-icon.png', resolve('@gramlot/gramlot/assets/branding/app-icon.png')],

package/src/gramlot_examples/pages/layout/01_border.js

@@ -0,0 +1,80 @@
+import { Page as BasePage } from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = 'Border regions and splitters';
+    static devices = ['desktop', 'tablet', 'phone'];
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const pane = root.main({ class: 'example-page stack' });
+        pane.h1('Space for content');
+        pane.p(
+            'Drag a separator or use its arrow keys. Resize Filters and Details while editing the customer.',
+        );
+        const bc = pane.borderContainer({
+            id: 'border-demo',
+            height: '440px',
+            max_width: '64rem',
+            border: '1px solid var(--gramlot-border-control, #aaa)',
+        });
+        bc.contentPane({
+            region: 'top',
+            border_bottom: '1px solid var(--gramlot-border-control, #aaa)',
+            height: '40px',
+            background: 'var(--gramlot-surface-subtle, #eef1f5)',
+            padding: '8px',
+        }).strong('Customer workspace');
+        const left = bc.contentPane({
+            region: 'left',
+            border_right: '1px solid var(--gramlot-border-control, #aaa)',
+            width: '160px',
+            splitter: true,
+            minSize: 100,
+            maxSize: 300,
+            padding: '12px',
+            background: 'var(--gramlot-surface-subtle, #eef1f5)',
+        });
+        left.textbox({ value: '^filter', lbl: 'Filter', width: '100%' });
+        const right = bc.contentPane({
+            region: 'right',
+            border_left: '1px solid var(--gramlot-border-control, #aaa)',
+            width: '220px',
+            splitter: true,
+            minSize: 120,
+            maxSize: 400,
+            padding: '12px',
+            background: 'var(--gramlot-surface-subtle, #eef1f5)',
+        });
+        right.h3('Customer summary');
+        right.p('^customer.name', { mask: 'Customer: {}' });
+        right.checkbox({ value: '^customer.active', label: 'Active customer', mode: 'switch' });
+        right.p('^customer.notes');
+        const center = bc.contentPane({
+            region: 'center',
+            background: 'var(--gramlot-surface, #fff)',
+            padding: '16px 48px',
+        });
+        const fields = center.formlet({ columns: 1, max_width: '22rem', gap: '12px' });
+        fields.textbox({
+            id: 'customer-name',
+            value: '^customer.name',
+            lbl: 'Name (2–8 characters)',
+            validate_len: '2:8',
+            width: '100%',
+        });
+        fields.textBoxArea({ value: '^customer.notes', lbl: 'Notes', rows: 3, width: '100%' });
+        center.p('Accepted name:');
+        center.p('^customer.name', { id: 'accepted-name' });
+        center.p('Try an invalid one-character name, then resize the panes. The draft stays in the field.');
+        for (const [path, value] of [
+            ['customer.active', true],
+            ['filter', ''],
+            ['customer.name', 'Ada'],
+            ['customer.notes', 'Same fields, same Data'],
+        ]) {
+            pane.dataSetter({ destination_path: path, value: value });
+        }
+    }
+}
+
+export class Logic {}

package/src/gramlot_examples/pages/layout/01_border.md

@@ -0,0 +1,23 @@
+# Give each part of your page its own space
+
+Imagine a customer screen: filters on the left, a form in the middle, and a summary on the right. You want people to give the form more room without having to close their work. This is what a **borderContainer** helps you build.
+
+A *region* is simply one of its areas: top, bottom, left, right or center. The center takes the space that remains. You do not have to calculate its width yourself.
+
+## Try it
+
+Start by dragging the thin line beside the filters. This line is a **splitter**. As the filters get wider, the form gets narrower. Release it where you are comfortable: you have changed the layout, not the form.
+
+Now enter a customer name of at least two characters and leave the field. Look at the summary. It shows your new name because both places use the same stored value. In Gramlot, those shared values are called **Data**.
+
+For a useful contrast, enter just one letter. The field reports that the name is too short, while the summary keeps the last accepted name. Resize the pane again: even the unfinished, invalid edit stays in the field. Moving a separator does not rebuild the editor.
+
+## How you would build this
+
+First create a borderContainer. Add a contentPane for each region you need. For a left-hand pane, set region to left, choose a starting width and enable splitter. Add another pane with region set to center for the main form. That is the layout: no resize formula for the center is needed.
+
+Minimum and maximum sizes keep a pane useful when someone drags too far. A keyboard user can focus a splitter and use its arrow keys.
+
+## Take one idea with you
+
+A container organizes space; the fields continue to own their editing state. Use **Code** when you want to find the region declarations, then return to the example and try a different width. Next, **Nested borders** shows how one area can contain a layout of its own.

package/src/gramlot_examples/pages/layout/02_nested.js

@@ -0,0 +1,99 @@
+import { Page as BasePage } from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = 'Nested borders and layout designs';
+    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 layout inside another');
+        const controls = pane.formlet({ max_width: '24rem', columns: 1 });
+        controls.filteringSelect({
+            id: 'design',
+            value: '^design',
+            lbl: 'Outer design',
+            values: 'headline:Headline,sidebar:Sidebar',
+            width: '10rem',
+        });
+        const bc = pane.borderContainer({
+            id: 'nested-demo',
+            height: '440px',
+            design: '^design',
+            max_width: '64rem',
+            border: '1px solid var(--gramlot-border-control, #aaa)',
+        });
+        bc.contentPane({
+            region: 'top',
+            border_bottom: '1px solid var(--gramlot-border-control, #aaa)',
+            height: '48px',
+            splitter: true,
+            minSize: 30,
+            maxSize: 100,
+            padding: '10px',
+            background: 'var(--gramlot-surface-subtle, #eef1f5)',
+        }).p('Outer header');
+        const left = bc.contentPane({
+            region: 'left',
+            border_right: '1px solid var(--gramlot-border-control, #aaa)',
+            width: '130px',
+            drawer: true,
+            splitter: false,
+            drawer_title: 'Side',
+            padding: '10px',
+            background: 'var(--gramlot-surface-subtle, #eef1f5)',
+        });
+        left.h3('Workspace');
+        left.radioButtonText({ value: '^section', values: 'profile:Profile,history:History', cols: 1 });
+        left.p('A fixed-width drawer: open and close without dragging.');
+        const nested = bc.borderContainer({ region: 'center' });
+        nested
+            .contentPane({
+                region: 'top',
+                border_bottom: '1px solid var(--gramlot-border-control, #aaa)',
+                height: '40px',
+                padding: '10px',
+                background: 'var(--gramlot-surface-subtle, #eef1f5)',
+            })
+            .p('Inner header');
+        const editor = nested.contentPane({
+            region: 'center',
+            padding: '12px 40px',
+            background: 'var(--gramlot-surface, #fff)',
+        });
+        editor.textbox({ value: '^name', lbl: 'Customer', width: '100%', max_width: '24rem' });
+        editor.checkbox({ value: '^active', label: 'Active', mode: 'switch' });
+        editor.textBoxArea({
+            id: 'nested-note',
+            value: '^note',
+            lbl: 'Retained draft',
+            rows: 3,
+            width: '100%',
+            max_width: '24rem',
+        });
+        nested
+            .contentPane({
+                region: 'bottom',
+                border_top: '1px solid var(--gramlot-border-control, #aaa)',
+                height: '80px',
+                splitter: true,
+                minSize: 36,
+                maxSize: 180,
+                drawer: true,
+                drawer_title: 'Output',
+                padding: '10px',
+                background: 'var(--gramlot-surface-subtle, #eef1f5)',
+            })
+            .p('^note');
+        pane.dataSetter({ destination_path: 'name', value: 'Ada Lovelace' });
+        pane.dataSetter({ destination_path: 'active', value: true });
+        pane.dataSetter({ destination_path: 'section', value: 'profile' });
+        pane.dataSetter({ destination_path: 'design', value: 'headline' });
+        pane.dataSetter({
+            destination_path: 'note',
+            value: 'Resize the inner bottom region, then change the outer design.',
+        });
+    }
+}
+
+export class Logic {}

package/src/gramlot_examples/pages/layout/02_nested.md

@@ -0,0 +1,23 @@
+# Put a workspace inside a workspace
+
+A whole application and one of its editors rarely need the same layout. The application may need navigation and a header; the editor may need its own tools and output. You can give each its own **borderContainer**, placing the editor's container in the center of the application's container.
+
+Think of it as rooms inside a house: changing the arrangement of one room does not require rebuilding the house.
+
+## Try it
+
+Find the customer and note fields and enter something you will recognize. Now change **Outer design** from Headline to Sidebar. Look at the corners: Headline gives the header the full width, while Sidebar lets the side region run along the height. Your text remains in the editor.
+
+Next, drag the separator above the inner output area. Only that inner layout changes. The outer header and navigation still belong to the outer container.
+
+Close **Side** using its little handle, then open it again. This particular drawer has a fixed width: you can open and close it, but it is not a resizable splitter. A drawer and a splitter are two independent choices.
+
+## How the pieces fit
+
+Each container arranges its direct children. A child can be an ordinary contentPane holding fields, or another borderContainer holding more regions. The inner container only needs to know about its own children.
+
+The design selector writes a shared Data value. The outer container reads that value through a **binding**, a connection that updates an attribute when its Data changes. Changing the design rearranges the existing screen; it does not create a new customer form.
+
+## When this is useful
+
+Use nesting when a section needs its own layout rules. Avoid adding another container just to add spacing: padding is enough for that. The next lesson combines nested layouts with rounded edges and popups.

package/src/gramlot_examples/pages/layout/03_rounded.js

@@ -0,0 +1,111 @@
+import { Page as BasePage } from '@gramlot/gramlot/page';
+
+export class Page extends BasePage {
+    static title = 'Rounded borders and popups';
+    static devices = ['desktop', 'tablet', 'phone'];
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const pane = root.main({ class: 'example-page stack' });
+        pane.h1('Rounded outside, continuous inside');
+        pane.p(
+            'Drag all four separators and toggle their drawers. Open the calendar and choices inside the rounded inner panel.',
+        );
+        const controls = pane.formlet({ max_width: '24rem', columns: 1 });
+        controls.filteringSelect({
+            id: 'rounded-design',
+            value: '^design',
+            lbl: 'Outer design',
+            values: 'headline:Headline,sidebar:Sidebar',
+            width: '10rem',
+        });
+        controls.horizontalSlider({
+            id: 'rounded-slider',
+            value: '^rounded',
+            lbl: 'Corner radius (px)',
+            min: 0,
+            max: 48,
+            step: 1,
+            live: true,
+            width: '14rem',
+        });
+        const border = pane.borderContainer({
+            id: 'rounded-border',
+            height: '560px',
+            max_width: '64rem',
+            design: '^design',
+            rounded: '^rounded',
+            border: '2px solid var(--gramlot-border-control, #8192aa)',
+            background: 'var(--gramlot-surface, #fff)',
+        });
+        for (const [side, size, label] of [
+            ['top', '64px', 'Header'],
+            ['bottom', '64px', 'Footer'],
+            ['left', '140px', 'Filters'],
+            ['right', '140px', 'Details'],
+        ]) {
+            const dimensions = {
+                [`border_${{ top: 'bottom', bottom: 'top', left: 'right', right: 'left' }[side]}`]:
+                    '1px solid var(--gramlot-border-control, #aaa)',
+                [['top', 'bottom'].includes(side) ? 'height' : 'width']: size,
+            };
+            const region = border.contentPane({
+                id: `rounded-${side}`,
+                region: side,
+                splitter: true,
+                drawer: true,
+                minSize: 40,
+                maxSize: 240,
+                drawer_title: label,
+                padding: '16px',
+                background: 'var(--gramlot-surface-subtle, #e5ebf3)',
+                ...dimensions,
+            });
+            region.strong(label);
+        }
+        const center = border.contentPane({ region: 'center', padding: '24px 32px' });
+        const inner = center.borderContainer({
+            id: 'rounded-inner',
+            height: '100%',
+            rounded: '^rounded',
+            background: 'var(--gramlot-surface, #fff)',
+            border: '2px solid var(--gramlot-border-control, #8192aa)',
+        });
+        inner
+            .contentPane({
+                region: 'top',
+                border_bottom: '1px solid var(--gramlot-border-control, #aaa)',
+                height: '40px',
+                padding: '8px 12px',
+                background: 'var(--gramlot-surface-subtle, #e5ebf3)',
+            })
+            .strong('Shared reactive radius');
+        const fields = inner.contentPane({ region: 'center', padding: '12px' });
+        const form = fields.formlet({ columns: 1, gap: '10px', max_width: '20rem' });
+        form.textbox({
+            id: 'rounded-name',
+            value: '^name',
+            lbl: 'Name (2–8 characters)',
+            validate_len: '2:8',
+            width: '100%',
+        });
+        form.dateTextBox({ id: 'rounded-date', value: '^date', lbl: 'Appointment', width: '100%' });
+        form.filteringSelect({
+            id: 'rounded-choice',
+            value: '^choice',
+            lbl: 'Delivery',
+            values: 'standard:Standard,express:Express,pickup:Pick up,scheduled:Scheduled,evening:Evening,weekend:Weekend',
+            width: '100%',
+        });
+        pane.p(
+            "The rounded outline clips pane backgrounds. Calendar, choices and validation messages use the browser's top layer.",
+        );
+        pane.dataSetter({ destination_path: 'design', value: 'headline' });
+        pane.dataSetter({ destination_path: 'rounded', value: 24 });
+        pane.dataSetter({ destination_path: 'name', value: 'Ada' });
+        pane.dataSetter({ destination_path: 'date', value: new Date(Date.UTC(2026, 9, 18)) });
+        pane.dataSetter({ destination_path: 'choice', value: 'standard' });
+    }
+}
+
+export class Logic {}

package/src/gramlot_examples/pages/layout/03_rounded.md

@@ -0,0 +1,25 @@
+# Rounded panels that still let you work
+
+Rounded corners can make a workspace feel softer, but they should never get in the way of a calendar, a choice list or a helpful error message. This example lets you try those things together.
+
+The outer layout and the layout inside it share a corner-radius setting. You will see both respond to one control.
+
+## Try it
+
+Move **Corner radius** slowly from zero toward 48. At zero the corners are square. As the value increases, watch the inner boundaries as well as the outside outline. The page is changing an existing layout, not loading another version of it.
+
+Open the appointment calendar, then open the Delivery list. Try this with a generous corner radius and with a narrow editor. A popup needs to remain usable even when the field sits near a rounded edge.
+
+Enter a one-letter name. The error message floats beside the invalid field rather than pushing the following fields down. You can keep reading the form without losing your place.
+
+Finally, resize a region or close a drawer and reopen it. Your edits should still be there.
+
+## Why one slider changes both layouts
+
+Both containers read the same Data value for their rounded attribute. This is a binding: instead of assigning a radius once, you tell the container where to read it. When the slider changes that value, both containers update.
+
+The rounded background and the popup have different jobs. The background stays within the panel's shape. The calendar and choice popup can appear above it, so the rounded edge does not cut off the choices.
+
+## Your next experiment
+
+Try mimi and joanna from Settings. The appearance changes, but the layout and the values you entered remain the same. Then visit **Drawers** to explore how a panel can get out of your way without throwing away your work.