@gjsify/example-gtk-adwaita-storybook 0.54.0 → 0.55.0

package/src/browser/drawing/drag-icon.web.ts

@@ -0,0 +1,112 @@
+// Browser port of the Drag Icon story. Shares metadata with drag-icon.story.ts.
+//
+// THE DRAG SOURCE IS A `draggable` ROW HERE, and that is the whole of the difference: a
+// browser has no drag source object to attach to a widget, but it does have the HTML
+// drag-and-drop events, and `dragstart` is the same moment as `GtkDragSource::drag-begin`.
+
+import { StoryElement, type StoryArgs, type StoryMeta, type WebStoryModule } from '@gjsify/adwaita-storybook';
+// The one place a story needs an element's VALUE: `getForDrag` and `createWidgetForValue`
+// are the static half of `GtkDragIcon`'s API — an icon is not something a page declares and
+// fills in, it is something a drag asks for. Everywhere else the stories create elements by
+// tag, which needs no import at all.
+import { Gtk } from '@gjsify/adwaita-web';
+import { dragIconMeta } from '../../drawing/drag-icon.meta.js';
+
+/** The `rgba()` a `GdkRGBA` value paints, as the colour swatch shows it. */
+interface Rgba {
+    readonly red: number;
+    readonly green: number;
+    readonly blue: number;
+    readonly alpha?: number;
+}
+
+export class DragIconWebStory extends StoryElement {
+    private _row: HTMLElement | null = null;
+    private _hint: HTMLElement | null = null;
+
+    constructor() {
+        super(DragIconWebStory.getMetadata(), 'Default');
+    }
+
+    static getMetadata(): StoryMeta {
+        return dragIconMeta;
+    }
+
+    initialize(): void {
+        const box = document.createElement('div');
+        box.style.display = 'flex';
+        box.style.flexDirection = 'column';
+        box.style.alignItems = 'center';
+        box.style.gap = '12px';
+
+        const hint = document.createElement('p');
+        hint.className = 'dim-label';
+        this._hint = hint;
+        box.append(hint);
+
+        // The DRAGGABLE ROW. What `gtk_widget_add_controller (widget,
+        // GTK_EVENT_CONTROLLER (drag_source))` is in GTK (gtkdragsource.c:44-58) is a
+        // `draggable` element plus a `dragstart` handler in a browser.
+        this._row = document.createElement('div');
+        this._row.className = 'card';
+        this._row.draggable = true;
+        this._row.style.display = 'flex';
+        this._row.style.alignItems = 'center';
+        this._row.style.gap = '12px';
+        this._row.style.padding = '12px';
+        const label = document.createElement('span');
+        label.className = 'heading';
+        label.textContent = 'Report.odt';
+        this._row.append(label);
+        this._row.addEventListener('dragstart', (event) => this._onDragStart(event as DragEvent));
+        box.append(this._row);
+
+        this._apply();
+        this.addContent(box);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    /** The value the drag offers, which is also what decides the icon — the two are one thing. */
+    private _value(): string | Rgba | null {
+        switch (this.args.value) {
+            case 'rgba':
+                return { red: 0.25, green: 0.55, blue: 0.95, alpha: 1 };
+            case 'none':
+                return null;
+            default:
+                return 'Report.odt';
+        }
+    }
+
+    /**
+     * `::drag-begin`: `GtkDragIcon.getForDrag` is the only way to reach an icon, and
+     * `createWidgetForValue` is what decides what a value shows (gtkdragicon.c:529-556).
+     */
+    private _onDragStart(event: DragEvent): void {
+        // `actions` on the source is the effect this drag may have; a browser states it as
+        // `effectAllowed`, and 'copy' / 'move' are the two Gdk.DragAction bits of the story.
+        if (event.dataTransfer !== null) {
+            event.dataTransfer.effectAllowed = this.args.actions === 'move' ? 'move' : 'copy';
+        }
+        const value = this._value();
+        if (value === null) return;
+        const icon = Gtk.DragIcon.getForDrag(event);
+        // `set_child` unparents the old child and shows the icon (:468-489), so this is also
+        // how an icon that had none starts showing.
+        icon.setChild(Gtk.DragIcon.createWidgetForValue(value));
+    }
+
+    private _apply(): void {
+        if (this._hint === null || this._row === null) return;
+        this._hint.textContent =
+            this.args.value === 'none'
+                ? 'Drag the row — no icon, because the value has no widget to show'
+                : 'Drag the row and watch the pointer';
+        this._row.title = 'Draggable — the icon that follows the pointer is a <gtk-drag-icon>';
+    }
+}
+
+export const DragIconWebStories: WebStoryModule = { stories: [DragIconWebStory] };

package/src/browser/drawing/drawing-area.web.ts

@@ -0,0 +1,66 @@
+// Browser port of the Drawing Area story. Shares metadata with drawing-area.story.ts.
+
+import { StoryElement, type StoryArgs, type StoryMeta, type WebStoryModule } from '@gjsify/adwaita-storybook';
+// TYPE-ONLY: the draw function is installed imperatively, exactly as the GTK story
+// installs its callback, so the element type is what the story needs to say — not a
+// hand-written interface that would be a second copy of the API. The import erases.
+import type { Gtk } from '@gjsify/adwaita-web';
+import { drawingAreaMeta } from '../../drawing/drawing-area.meta.js';
+
+export class DrawingAreaWebStory extends StoryElement {
+    private _area: Gtk.DrawingArea | null = null;
+
+    constructor() {
+        super(DrawingAreaWebStory.getMetadata(), 'Default');
+    }
+
+    static getMetadata(): StoryMeta {
+        return drawingAreaMeta;
+    }
+
+    initialize(): void {
+        this._area = document.createElement('gtk-drawing-area') as Gtk.DrawingArea;
+        // The same three shapes the GTK draw function draws, on the same 2D context: the
+        // element scales it by the device pixel ratio, so the numbers here are logical
+        // pixels on both surfaces.
+        const area = this._area;
+        area.setDrawFunc((_area, cr, width, height) => {
+            // The area paints itself in the widget's own colour, which is what
+            // `gtk_widget_get_color` is for (gtkdrawingarea.c:98-101) — `currentColor` is
+            // the browser's spelling of the same question.
+            cr.fillStyle = 'currentColor';
+            cr.globalCompositeOperation = 'source-over';
+            cr.fillRect(0, 0, width, height);
+            cr.globalCompositeOperation = 'difference';
+            switch (this.args.shape) {
+                case 'grid':
+                    for (let x = 0; x < width; x += 16) cr.fillRect(x, 0, 8, height);
+                    break;
+                case 'crosshair':
+                    cr.fillRect(width / 2 - 1, 0, 2, height);
+                    cr.fillRect(0, height / 2 - 1, width, 2);
+                    break;
+                default:
+                    cr.beginPath();
+                    cr.arc(width / 2, height / 2, Math.min(width, height) / 2, 0, 2 * Math.PI);
+                    cr.fill();
+                    break;
+            }
+            cr.globalCompositeOperation = 'source-over';
+        });
+        this._apply();
+        this.addContent(this._area);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._area) return;
+        this._area.setAttribute('content-width', String(this.args.contentWidth as number));
+        this._area.setAttribute('content-height', String(this.args.contentHeight as number));
+    }
+}
+
+export const DrawingAreaWebStories: WebStoryModule = { stories: [DrawingAreaWebStory] };

package/src/browser/drawing/gl-area.web.ts

@@ -0,0 +1,162 @@
+// Browser port of the GL Area story. Shares metadata with gl-area.story.ts.
+
+import { StoryElement, type StoryArgs, type StoryMeta, type WebStoryModule } from '@gjsify/adwaita-storybook';
+import type { Gtk } from '@gjsify/adwaita-web';
+import { glAreaMeta } from '../../drawing/gl-area.meta.js';
+
+const VERTEX_SHADER = `
+attribute vec2 position;
+uniform float angle;
+void main () {
+    float c = cos (angle);
+    float s = sin (angle);
+    gl_Position = vec4 ((position.x * c - position.y * s) * 0.7,
+                        (position.x * s + position.y * c) * 0.7,
+                        0.0, 1.0);
+}`;
+
+const FRAGMENT_SHADER = `
+precision mediump float;
+void main () { gl_FragColor = vec4 (0.25, 0.55, 0.9, 1.0); }`;
+
+export class GLAreaWebStory extends StoryElement {
+    private _area: Gtk.GLArea | null = null;
+    private _readout: HTMLElement | null = null;
+    private _frame = 0;
+    private _program: WebGLProgram | null = null;
+    private _buffer: WebGLBuffer | null = null;
+    private _angle = 0;
+    private _renders = 0;
+    private _viewport = '—';
+
+    constructor() {
+        super(GLAreaWebStory.getMetadata(), 'Default');
+    }
+
+    static getMetadata(): StoryMeta {
+        return glAreaMeta;
+    }
+
+    initialize(): void {
+        this._area = document.createElement('gtk-gl-area') as Gtk.GLArea;
+        this._area.style.width = '240px';
+        this._area.style.height = '160px';
+        this._readout = document.createElement('div');
+        this._readout.className = 'adw-gl-area-story-readout';
+
+        // The SAME two signals the GTK story connects, in the SAME order: `resize` arrives
+        // before the first `render` and on every later allocation, and its numbers are
+        // device pixels (gtkglarea.c:761-763, :797-807).
+        this._area.addEventListener('resize', (event: Event) => {
+            const { width, height } = (event as CustomEvent).detail as { width: number; height: number };
+            this._viewport = `${width} × ${height}`;
+            this._refresh();
+        });
+        this._area.addEventListener('render', (event: Event) => {
+            const { context } = (event as CustomEvent).detail as {
+                context: WebGLRenderingContext | WebGL2RenderingContext | null;
+            };
+            if (context) this._draw(context);
+            this._renders += 1;
+            this._refresh();
+        });
+
+        this._apply();
+        this._start();
+        const box = document.createElement('div');
+        box.style.display = 'flex';
+        box.style.flexDirection = 'column';
+        box.style.gap = '6px';
+        box.style.alignItems = 'center';
+        box.append(this._area, this._readout);
+        this.addContent(box);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._stop();
+        this._apply();
+        this._start();
+    }
+
+    private _apply(): void {
+        if (!this._area) return;
+        this._area.setAttribute('auto-render', String(this.args.autoRender as boolean));
+        this._area.setAttribute('has-depth-buffer', String(this.args.hasDepthBuffer as boolean));
+        // `allowed-apis` is refused once the area is realized (gtkglarea.c:1242), so it is
+        // set before the first render — which is also what the GTK story does.
+        this._area.setAttribute('allowed-apis', this.args.allowedApis as string);
+    }
+
+    /**
+     * `queue_render()` is how a GL application asks for the next frame (gtkglarea.c:1465).
+     * The browser's frame clock is `requestAnimationFrame`, and the element coalesces
+     * through it, so this is a scheduler rather than a synchronous draw.
+     */
+    private _start(): void {
+        if (!this.args.spinning) return;
+        const step = () => {
+            this._angle += 0.05;
+            this._area?.queueRender();
+            this._frame = requestAnimationFrame(step);
+        };
+        this._frame = requestAnimationFrame(step);
+    }
+
+    private _stop(): void {
+        if (this._frame !== 0) cancelAnimationFrame(this._frame);
+        this._frame = 0;
+    }
+
+    /** The triangle the GTK story cannot draw here: a program, a buffer and a draw call. */
+    private _draw(context: WebGLRenderingContext | WebGL2RenderingContext): void {
+        // WebGL2 extends WebGL, so one `instanceof` covers both.
+        if (!(context instanceof WebGLRenderingContext)) return;
+        if (!this._program) this._build(context);
+        const program = this._program;
+        // `_build` compiles and links; a driver that refuses either leaves nothing to draw,
+        // which is the end of this frame rather than an error thrown out of the handler.
+        if (program === null) return;
+        context.clearColor(0.15, 0.16, 0.18, 1);
+        context.clear(context.COLOR_BUFFER_BIT);
+        context.useProgram(program);
+        context.uniform1f(context.getUniformLocation(program, 'angle'), this._angle);
+        context.bindBuffer(context.ARRAY_BUFFER, this._buffer);
+        context.enableVertexAttribArray(0);
+        context.vertexAttribPointer(0, 2, context.FLOAT, false, 0, 0);
+        context.drawArrays(context.TRIANGLES, 0, 3);
+    }
+
+    /** Compiled once, with the context current — the C's own advice. */
+    private _build(context: WebGLRenderingContext | WebGL2RenderingContext): void {
+        const compile = (type: number, source: string): WebGLShader | null => {
+            const shader = context.createShader(type);
+            if (!shader) return null;
+            context.shaderSource(shader, source);
+            context.compileShader(shader);
+            return shader;
+        };
+        const program = context.createProgram();
+        const vertex = compile(context.VERTEX_SHADER, VERTEX_SHADER);
+        const fragment = compile(context.FRAGMENT_SHADER, FRAGMENT_SHADER);
+        if (!program || !vertex || !fragment) return;
+        context.attachShader(program, vertex);
+        context.attachShader(program, fragment);
+        context.linkProgram(program);
+        this._program = program;
+        const buffer = context.createBuffer();
+        context.bindBuffer(context.ARRAY_BUFFER, buffer);
+        context.bufferData(
+            context.ARRAY_BUFFER,
+            new Float32Array([-0.6, -0.6, 0.6, -0.6, 0.0, 0.6]),
+            context.STATIC_DRAW,
+        );
+        this._buffer = buffer;
+    }
+
+    private _refresh(): void {
+        if (!this._readout) return;
+        this._readout.textContent = `viewport ${this._viewport} device px · ${this._renders} renders`;
+    }
+}
+
+export const GLAreaWebStories: WebStoryModule = { stories: [GLAreaWebStory] };

package/src/browser/drawing/graphics-offload.web.ts

@@ -0,0 +1,74 @@
+// Browser port of the Graphics Offload story. Shares metadata with
+// graphics-offload.story.ts.
+
+import { StoryElement, type StoryArgs, type StoryMeta, type WebStoryModule } from '@gjsify/adwaita-storybook';
+import { graphicsOffloadMeta } from '../../drawing/graphics-offload.meta.js';
+
+export class GraphicsOffloadWebStory extends StoryElement {
+    private _offload: HTMLElement | null = null;
+
+    constructor() {
+        super(GraphicsOffloadWebStory.getMetadata(), 'Default');
+    }
+
+    static getMetadata(): StoryMeta {
+        return graphicsOffloadMeta;
+    }
+
+    initialize(): void {
+        this._offload = document.createElement('gtk-graphics-offload');
+        this._offload.style.width = '280px';
+        this._offload.style.height = '96px';
+        this._apply();
+        const box = document.createElement('div');
+        box.style.display = 'flex';
+        box.style.justifyContent = 'center';
+        box.append(this._offload);
+        this.addContent(box);
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        this._apply();
+    }
+
+    private _apply(): void {
+        if (!this._offload) return;
+        // `enabled` before `black-background`, the C's property order
+        // (gtkgraphicsoffload.c:366-380, :423-437).
+        this._offload.setAttribute('enabled', this.args.enabled as string);
+        this._offload.setAttribute('black-background', String(this.args.blackBackground as boolean));
+        // The wrapper holds ONE child, so changing it means replacing it — which is what
+        // `set_child` does, unparenting the old one (gtkgraphicsoffload.c:317-336).
+        let child: HTMLElement;
+        switch (this.args.child) {
+            case 'label': {
+                const label = document.createElement('gtk-label');
+                label.setAttribute('label', 'The child of an offloaded layer');
+                child = label;
+                break;
+            }
+            case 'box': {
+                const row = document.createElement('gtk-box');
+                row.setAttribute('orientation', 'horizontal');
+                row.setAttribute('spacing', '12');
+                for (const text of ['One', 'Two', 'Three']) {
+                    const label = document.createElement('gtk-label');
+                    label.setAttribute('label', text);
+                    row.appendChild(label);
+                }
+                child = row;
+                break;
+            }
+            default: {
+                const image = document.createElement('gtk-image');
+                image.setAttribute('icon-name', 'camera-photo');
+                image.setAttribute('pixel-size', '48');
+                child = image;
+                break;
+            }
+        }
+        this._offload.replaceChildren(child);
+    }
+}
+
+export const GraphicsOffloadWebStories: WebStoryModule = { stories: [GraphicsOffloadWebStory] };

package/src/browser/feedback/dialog.web.ts

@@ -0,0 +1,76 @@
+// Browser port of the Dialog story. Shares metadata with dialog.story.ts.
+
+import { StoryElement, type StoryArgs, type StoryMeta, type WebStoryModule } from '@gjsify/adwaita-storybook';
+import { dialogMeta } from '../../feedback/dialog.meta.js';
+
+/**
+ * Story: adw-dialog presented from a button, holding a preferences page as its
+ * child — a 1:1 port of the GTK DialogStory.
+ */
+export class DialogWebStory extends StoryElement {
+    constructor() {
+        super(DialogWebStory.getMetadata(), 'Default');
+    }
+
+    static getMetadata(): StoryMeta {
+        return dialogMeta;
+    }
+
+    initialize(): void {
+        const button = document.createElement('gtk-button');
+        button.textContent = 'Show dialog';
+        button.setAttribute('pill', '');
+        button.setAttribute('suggested', '');
+        button.addEventListener('click', () => this._present());
+
+        // Centre the trigger button so the preview matches the GTK story's
+        // centred halign/valign placement.
+        const center = document.createElement('div');
+        center.style.display = 'flex';
+        center.style.alignItems = 'center';
+        center.style.justifyContent = 'center';
+        center.style.minHeight = '160px';
+        center.append(button);
+
+        this.addContent(center);
+    }
+
+    /** Build + present a fresh dialog, reading the latest args (as the GTK story does). */
+    private _present(): void {
+        const dialog = document.createElement('adw-dialog');
+        dialog.setAttribute('title', this.args.title as string);
+        // The NICK, not the enum member: `presentation-mode` is the string the GIR
+        // enum resolves to on the other two renderers (ADR 0034 § 4).
+        dialog.setAttribute('presentation-mode', this.args.presentation as string);
+
+        // ONE child, and it is the `Adw.Dialog:child` property — the element moves
+        // every child into its content area, so this is a declaration, not a pack.
+        const group = document.createElement('adw-preferences-group');
+        group.setAttribute('title', 'Appearance');
+        const row = document.createElement('adw-switch-row');
+        row.setAttribute('title', 'Dark style');
+        row.setAttribute('subtitle', 'Use a dark colour scheme');
+        row.setAttribute('active', '');
+        group.appendChild(row);
+
+        const page = document.createElement('adw-preferences-page');
+        page.setAttribute('title', 'General');
+        page.appendChild(group);
+
+        dialog.appendChild(page);
+
+        // A DISCONNECTED element is attached to `document.body` on present, the
+        // `Adw.Dialog.present(parent)` idiom; one already in the DOM is revealed in
+        // place and stays reusable.
+        (dialog as HTMLElement & { present(): void }).present();
+
+        // Close it from the story, the way the GTK story's dialog is destroyed on close.
+        dialog.addEventListener('closed', () => dialog.remove(), { once: true });
+    }
+
+    updateArgs(_args: StoryArgs): void {
+        // The dialog reads the latest args each time it is presented; nothing to mutate live.
+    }
+}
+
+export const DialogWebStories: WebStoryModule = { stories: [DialogWebStory] };

package/src/browser/feedback/emoji-chooser.web.ts

@@ -0,0 +1,93 @@
+// Browser port of the Emoji Chooser story. Shares metadata with emoji-chooser.story.ts.
+
+import { StoryElement, type StoryArgs, type StoryMeta, type WebStoryModule } from '@gjsify/adwaita-storybook';
+import { emojiChooserMeta } from '../../feedback/emoji-chooser.meta.js';
+
+/** The half of `<gtk-emoji-chooser>` the markup cannot spell. */
+interface EmojiChooserElement extends HTMLElement {
+    popup(): void;
+    popdown(): void;
+}
+
+/** The search entry the chooser builds inside itself. */
+function searchEntryOf(chooser: HTMLElement): HTMLInputElement | null {
+    return chooser.querySelector<HTMLInputElement>('.emoji-search-entry');
+}
+
+export class EmojiChooserWebStory extends StoryElement {
+    private _entry: HTMLInputElement | null = null;
+    private _button: HTMLElement | null = null;
+    private _chooser: EmojiChooserElement | null = null;
+
+    constructor() {
+        super(EmojiChooserWebStory.getMetadata(), 'Default');
+    }
+
+    static getMetadata(): StoryMeta {
+        return emojiChooserMeta;
+    }
+
+    initialize(): void {
+        const row = document.createElement('div');
+        row.className = 'sb-emoji-row';
+
+        this._entry = document.createElement('input');
+        this._entry.className = 'sb-emoji-entry';
+        this._entry.type = 'text';
+        this._entry.placeholder = 'Type a message…';
+        row.appendChild(this._entry);
+
+        // The chooser is a POPOVER, so it needs something to pop up from — the same shape
+        // the GTK story builds: a button in the entry, the chooser as its child.
+        const anchor = document.createElement('div');
+        anchor.className = 'sb-emoji-anchor';
+        this._button = document.createElement('button');
+        this._button.className = 'adw-button flat circular';
+        this._button.setAttribute('aria-label', 'Insert an emoji');
+        const icon = document.createElement('gtk-image');
+        icon.setAttribute('icon-name', 'face-smile');
+        this._button.appendChild(icon);
+        this._button.addEventListener('click', () => {
+            this._chooser?.popup();
+            searchEntryOf(this._chooser as HTMLElement)?.focus();
+        });
+        anchor.appendChild(this._button);
+        row.appendChild(anchor);
+
+        this._chooser = document.createElement('gtk-emoji-chooser') as EmojiChooserElement;
+        this._chooser.setAttribute('position', 'bottom');
+        this._chooser.setAttribute('align', 'end');
+        // `GtkPopover` positions against the widget it is a child of; here that is the
+        // button, which is NOT its DOM parent (the wrapper is), so the anchor is set.
+        (this._chooser as unknown as HTMLElement & { anchor: HTMLElement | null }).anchor = this._button;
+        this._chooser.addEventListener('emoji-picked', (event) => {
+            const { text } = (event as CustomEvent).detail as { text: string };
+            if (this._entry !== null) this._entry.value += text;
+        });
+        anchor.appendChild(this._chooser);
+
+        this.addContent(row);
+        this._applySearch(this.args.search as string);
+        this._chooser.popup();
+    }
+
+    private _applySearch(text: string): void {
+        const entry = this._chooser === null ? null : searchEntryOf(this._chooser);
+        if (entry === null) return;
+        entry.value = text;
+        entry.dispatchEvent(new Event('input', { bubbles: true }));
+    }
+
+    updateArgs(args: StoryArgs): void {
+        if (typeof args.search === 'string') this._applySearch(args.search);
+    }
+
+    teardown(): void {
+        this._chooser?.popdown();
+        this._chooser = null;
+        this._entry = null;
+        this._button = null;
+    }
+}
+
+export const EmojiChooserWebStories: WebStoryModule = { stories: [EmojiChooserWebStory] };