@gramlot/gramlot-examples 0.2.2

package/src/gramlot_examples/pages/html_svg/11_static_report.js

@@ -0,0 +1,68 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+const REGIONS = [['North', 12, 'var(--gramlot-action)'], ['South', 9, 'var(--gramlot-warning)'], ['West', 15, 'var(--gramlot-success)']];
+
+export class Page extends BasePage {
+    static title = 'Static report';
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const page = root.main({class: 'example-page stack'});
+        const header = page.header();
+        header.p('SAMPLE REPORT', {class: 'eyebrow'});
+        header.h1('Orders by region');
+        header.p('A fixed dataset feeds the summary, chart and table.');
+        const total = REGIONS.reduce((sum, region) => sum + region[1], 0);
+        this.summary(page, total);
+        this.chart(page);
+        this.table(page, total);
+    }
+
+    summary(page, total) {
+        const summary = page.section({class: 'grid report-summary', aria_label: 'Summary'});
+        this.stat(summary, 'Total orders', String(total));
+        this.stat(summary, 'Regions', String(REGIONS.length));
+    }
+
+    chart(page) {
+        const chart = page.figure({class: 'card'});
+        const svg = chart.svg({viewBox: '0 0 520 230', role: 'img', aria_labelledby: 'report-chart-title', class: 'example-art'});
+        svg.title('Orders by region: North 12, South 9, West 15', {id: 'report-chart-title'});
+        REGIONS.forEach(([region, value, color], index) => {
+            const y = 28 + index * 68;
+            svg.text(region, {x: 12, y: y + 23, font_size: 17, fill: 'currentColor'});
+            svg.rect({x: 105, y, width: value * 23, height: 32, rx: 7, fill: color});
+            svg.text(String(value), {x: 112 + value * 23, y: y + 23, font_size: 17, fill: 'currentColor'});
+        });
+        chart.figcaption('The bar lengths and table cells use the same values.');
+        const legend = page.ul({class: 'report-legend'});
+        for (const [region, , color] of REGIONS) {
+            const item = legend.li();
+            item.span('■ ', {style: `color: ${color}`});
+            item.span(region);
+        }
+    }
+
+    table(page, total) {
+        const table = page.table();
+        table.caption('Exact figures');
+        const head = table.thead().tr();
+        head.th('Region', {scope: 'col'});
+        head.th('Orders', {scope: 'col'});
+        const body = table.tbody();
+        for (const [region, value] of REGIONS) {
+            const row = body.tr();
+            row.th(region, {scope: 'row'});
+            row.td(String(value));
+        }
+        const foot = table.tfoot().tr();
+        foot.th('Total', {scope: 'row'});
+        foot.td(String(total));
+    }
+
+    stat(parent, label, value) {
+        const card = parent.div({class: 'card'});
+        card.p(label, {class: 'muted'});
+        card.p(value, {class: 'report-number'});
+    }
+}

package/src/gramlot_examples/pages/html_svg/11_static_report.md

@@ -0,0 +1,9 @@
+# 11 · Static report
+
+A summary, SVG bar chart, visible legend and table from one dataset.
+
+Page methods build each section. Chart lengths and exact figures derive from the same local values.
+
+**Try it:** Add a region, then check summary, legend, chart and table.
+
+**Limit:** The report has no data service or live refresh.

package/src/gramlot_examples/pages/html_svg/12_complete_page.css

@@ -0,0 +1,5 @@
+.complete-page { display: grid; gap: 2rem; }
+.complete-header { display: grid; gap: .55rem; }
+.complete-header nav { display: flex; flex-wrap: wrap; gap: 1rem; padding-top: .5rem; }
+.complete-hero { display: grid; gap: 1rem; text-align: center; }
+.complete-grid { grid-template-columns: repeat(auto-fit, minmax(12rem, 1fr)); }

package/src/gramlot_examples/pages/html_svg/12_complete_page.js

@@ -0,0 +1,120 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+const SESSIONS = [
+    ['09:00', 'A first Source tree', 'Mira', 'Describe a page with semantic HTML.'],
+    ['10:30', 'Drawing with SVG', 'Theo', 'Build a small scene from SVG shapes.'],
+    ['13:00', 'Putting it together', 'Mira & Theo', 'Compose cards, a schedule and a summary.'],
+];
+const SPEAKERS = [['Mira', 'Page authoring'], ['Theo', 'SVG composition']];
+const QUESTIONS = [['Do I need a service?', 'This local example has no remote data.'],
+    ['Is the map interactive?', 'No. It is a schematic SVG illustration.']];
+
+export class Page extends BasePage {
+    static title = 'A complete example page';
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const shell = root.div({class: 'example-page complete-page'});
+        this.header(shell);
+        const main = shell.main({class: 'stack'});
+        this.hero(main);
+        this.highlights(main);
+        this.schedule(main);
+        this.speakers(main);
+        this.map(main);
+        this.faq(main);
+        shell.footer().small('Gramlot HTML/SVG examples · Static content');
+    }
+
+    header(shell) {
+        const header = shell.header({class: 'complete-header'});
+        header.p('GRAMLOT FIELD NOTES', {class: 'eyebrow'});
+        header.h1('A day of small interfaces');
+        header.p('A composed page built from HTML and SVG Source.');
+        const nav = header.nav({aria_label: 'Page sections'});
+        for (const [label, target] of [['Highlights', 'highlights'], ['Schedule', 'schedule'],
+            ['Speakers', 'speakers'], ['Map', 'map'], ['FAQ', 'faq']]) nav.a(label, {href: `#${target}`});
+    }
+
+    hero(main) {
+        const hero = main.section({class: 'card complete-hero', aria_label: 'Illustration'});
+        const drawing = hero.svg({viewBox: '0 0 720 180', role: 'img', aria_labelledby: 'complete-art-title', class: 'example-art'});
+        drawing.title('Three connected steps', {id: 'complete-art-title'});
+        drawing.line({x1: 125, y1: 90, x2: 595, y2: 90, stroke: 'var(--gramlot-border)', stroke_width: 8});
+        for (const [x, label, color] of [[125, 'WRITE', 'var(--gramlot-action)'],
+            [360, 'COMPOSE', 'var(--gramlot-warning)'], [595, 'REVIEW', 'var(--gramlot-success)']]) {
+            const group = drawing.g({transform: `translate(${x} 90)`});
+            group.circle({cx: 0, cy: 0, r: 47, fill: color});
+            group.text(label, {x: 0, y: 6, text_anchor: 'middle', font_size: 15,
+                font_weight: 'bold', fill: 'var(--gramlot-background)'});
+        }
+        hero.p('Three lessons. One Source tree. A page you can read without scripts beyond the Gramlot runtime.');
+    }
+
+    highlights(main) {
+        const section = main.section({id: 'highlights', class: 'stack'});
+        section.h2('Highlights');
+        const cards = section.div({class: 'grid complete-grid'});
+        for (const [number, title, description] of [
+            ['01', 'Write', 'Use page methods to describe content.'],
+            ['02', 'Compose', 'Nest HTML elements and SVG.'],
+            ['03', 'Review', 'Inspect the result in either language.'],
+        ]) {
+            const card = cards.article({class: 'card stack'});
+            card.p(number, {class: 'eyebrow'});
+            card.h3(title);
+            card.p(description);
+        }
+    }
+
+    schedule(main) {
+        const section = main.section({id: 'schedule', class: 'stack'});
+        section.h2('Schedule');
+        const table = section.table();
+        table.caption('Three short sessions');
+        const heading = table.thead().tr();
+        for (const title of ['Time', 'Session', 'Speaker', 'Focus']) heading.th(title, {scope: 'col'});
+        const body = table.tbody();
+        for (const [time, title, speaker, focus] of SESSIONS) {
+            const row = body.tr();
+            row.th(time, {scope: 'row'});
+            for (const text of [title, speaker, focus]) row.td(text);
+        }
+    }
+
+    speakers(main) {
+        const section = main.section({id: 'speakers', class: 'stack'});
+        section.h2('Speakers');
+        const cards = section.div({class: 'grid complete-grid'});
+        for (const [name, specialty] of SPEAKERS) {
+            const card = cards.article({class: 'card'});
+            card.h3(name);
+            card.p(specialty);
+        }
+    }
+
+    map(main) {
+        const section = main.section({id: 'map', class: 'stack'});
+        section.h2('A schematic venue map');
+        const figure = section.figure({class: 'card'});
+        const drawing = figure.svg({viewBox: '0 0 600 210', role: 'img', aria_labelledby: 'venue-title', class: 'example-art'});
+        drawing.title('Entrance, studio and hall connected by a path', {id: 'venue-title'});
+        drawing.path({d: 'M80 110 H300 V65 H510', fill: 'none', stroke: 'var(--gramlot-action)', stroke_width: 8});
+        for (const [x, y, label] of [[80, 110, 'Entrance'], [300, 65, 'Studio'], [510, 65, 'Hall']]) {
+            const stop = drawing.g({transform: `translate(${x} ${y})`});
+            stop.circle({cx: 0, cy: 0, r: 15, fill: 'var(--gramlot-warning)'});
+            stop.text(label, {x: 0, y: 37, text_anchor: 'middle', font_size: 17, fill: 'currentColor'});
+        }
+        figure.figcaption('A diagram made of paths, circles and labels; it is not navigation.');
+    }
+
+    faq(main) {
+        const section = main.section({id: 'faq', class: 'stack'});
+        section.h2('Frequently asked questions');
+        for (const [question, answer] of QUESTIONS) {
+            const details = section.details({class: 'card'});
+            details.summary(question);
+            details.p(answer);
+        }
+    }
+}

package/src/gramlot_examples/pages/html_svg/12_complete_page.md

@@ -0,0 +1,9 @@
+# 12 · A complete page
+
+An event page with schedule, speakers, schematic map and FAQ.
+
+Page methods divide the sections; nested loops compose rows, speaker cards and map labels from local data.
+
+**Try it:** Add a session, speaker and FAQ, then add a map stop.
+
+**Limit:** The event content is illustrative; there is no booking or routing service.

package/src/gramlot_examples/pages/html_svg/13_live_source.css

@@ -0,0 +1,3 @@
+.live-toolbar { display: flex; flex-wrap: wrap; gap: .5rem; }
+.live-items { display: grid; gap: .5rem; padding-inline-start: 1.5rem; }
+.example-page svg { display: block; width: min(100%, 32rem); height: auto; }

package/src/gramlot_examples/pages/html_svg/13_live_source.js

@@ -0,0 +1,64 @@
+import {Page as BasePage} from '@gramlot/gramlot/page';
+
+// These browser actions change Source, never DOM elements.
+const ACTIONS = {
+    "add": "window.gramlot.builder.wrapSource(window.gramlot.source.getNode('main.page.work.items')).li('A new item', {class: 'card'})",
+    "remove": "const items = window.gramlot.source.getItem('main.page.work.items'); const last = items.getNodes().at(-1); if (last) items.popNode(last.label)",
+    "clear": "window.gramlot.source.getItem('main.page.work.items').clear()",
+    "rename": "window.gramlot.source.getNode('main.page.heading').setValue('Source is alive!')",
+    "color": "window.gramlot.source.getNode('main.page.motion.scene.ball').setAttr({fill: 'var(--gramlot-warning)'})",
+    "stop": "window.gramlot.source.getItem('main.page').popNode('motion')"
+};
+const ANIMATION = `queueMicrotask(() => {
+    const app = window.gramlot;
+    const motion = app.source.getNode('main.page.motion');
+    const ball = app.source.getNode('main.page.motion.scene.ball');
+    const timer = setInterval(() => {
+        ball.setAttr({cx: 160 + 110 * Math.sin(performance.now() / 700)});
+    }, 50);
+    app.renderer.onDispose(motion, () => clearInterval(timer));
+});`;
+
+export class Page extends BasePage {
+    static title = 'Live Source playground';
+    static css = ['/themes/gramlot-base/theme.css'];
+
+    main(root) {
+        const page = root.main({node_label: 'page', class: 'example-page stack'});
+        page.h1('Live Source playground', {node_label: 'heading'});
+        page.p('Create and remove items, change text and watch SVG move. Every change goes through Source.');
+        this.workspace(page);
+        this.motion(page);
+        page.p('Reload to restore the initial page. Changes are local to this browser page.', {class: 'muted'});
+        page.script(ANIMATION);
+    }
+
+    button(root, title, action) {
+        root.button(title, {type: 'button', onclick: ACTIONS[action]});
+    }
+
+    workspace(page) {
+        const work = page.section({node_label: 'work', class: 'card stack'});
+        work.h2('Build a list live');
+        work.p('The first two items are authored by a loop. Add item uses the browser Builder to create another li.');
+        const toolbar = work.div({class: 'live-toolbar'});
+        for (const [title, action] of [['Add item', 'add'], ['Remove last', 'remove'], ['Clear list', 'clear'], ['Change heading', 'rename']]) {
+            this.button(toolbar, title, action);
+        }
+        const items = work.ul({node_label: 'items', class: 'live-items'});
+        for (const title of ['Explore the Source', 'Try a live change']) items.li(title, {class: 'card'});
+    }
+
+    motion(page) {
+        const motion = page.section({node_label: 'motion', class: 'card stack'});
+        motion.h2('An animated Source attribute');
+        motion.p("Every 50 ms, setInterval changes the circle's cx attribute in Source. Gramlot projects it into SVG.");
+        const scene = motion.svg({node_label: 'scene', viewBox: '0 0 320 100', role: 'img', aria_label: 'A circle moving from side to side'});
+        scene.line({x1: 30, y1: 50, x2: 290, y2: 50, stroke: 'var(--gramlot-action)', stroke_width: 2});
+        scene.circle({node_label: 'ball', cx: 160, cy: 50, r: 16, fill: 'var(--gramlot-action)'});
+        const toolbar = motion.div({class: 'live-toolbar'});
+        this.button(toolbar, 'Change ball color', 'color');
+        this.button(toolbar, 'Remove animation', 'stop');
+        motion.p('Removing this section also clears its interval through renderer.onDispose.', {class: 'muted'});
+    }
+}

package/src/gramlot_examples/pages/html_svg/13_live_source.md

@@ -0,0 +1,18 @@
+# 13 · Live Source playground
+
+Try the buttons: add list items, remove the last one, clear the list and change
+the heading. Builder.wrapSource creates new elements; Source node and Bag methods
+update or remove them. The renderer updates only the affected DOM branches.
+
+The SVG circle moves because a short script calls setInterval every 50 ms and
+changes its Source cx attribute. Change its color while it moves. Remove animation
+deletes the entire section and runs the renderer.onDispose callback, clearing the
+timer. Disposing the page also clears it. Reload restores the initial content.
+
+Python and JavaScript pages declare the same structure and browser actions.
+Named Source paths make the target of each operation explicit. Methods divide
+the page into sections and loops construct the initial items and buttons.
+
+This example demonstrates live Source, not Data binding, persistence or server
+synchronization. Its scripts/actions run in the hosted profiles and in the regenerated standalone
+directory opened directly from disk, offline.

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

@@ -0,0 +1,10 @@
+# HTML / SVG
+
+Learn to build a page with Gramlot: each instruction adds an element, and nested instructions describe its structure.
+
+Start with **Hello World**, then explore text, lists, tables and form controls. Continue with SVG shapes and combine them with HTML. The final examples use methods and loops to compose larger pages from simple parts.
+
+Compare each preview with its code, then try the small change suggested in the example's notes. Python and JavaScript express the same ideas.
+
+Finish with **Live Source playground**: change the page while it is running and
+watch a small SVG animation driven by Source attributes. The live examples also run in the regenerated standalone directory, offline.