@gjsify/adwaita-web 0.54.0 → 0.55.0

package/scss/adwaita-skin.scss

@@ -27,6 +27,15 @@
 @use 'labels';
 // <gtk-box>. Before every widget, which may place its own children in one.
 @use 'box';
+// The five Gtk layout containers after it, and they are here for ONE reason each: nothing
+// downstream of `box` needs to place children in one, and the frame's 1px border is the
+// only rule libadwaita writes for any of the five (`_misc.scss:4-15`) — so they belong with
+// the primitive they build on rather than in the widget run below.
+@use 'frame';
+@use 'aspect_frame';
+@use 'center_box';
+@use 'grid';
+@use 'fixed';
 // The REST of libadwaita's documented style-class surface — the widget-
 // independent half: the surfaces (`.background`, `.view`, `.frame`), `.card` and
 // the two boxed lists, `.toolbar`, `.spacer`, `.osd`, `.linked`, the app-icon
@@ -37,14 +46,32 @@
 // documented surface and fails on a class with no rule behind it.
 @use 'style_classes';
 @use 'window';
+@use 'application_window';
+// <adw-header-bar>, <gtk-header-bar> AND <gtk-window-controls>, in ONE partial because
+// upstream's `_header-bar.scss` styles `headerbar`, `windowcontrols` and `windowtitle`
+// together — and because a bar's frame buttons ARE its window controls.
 @use 'headerbar';
 @use 'action_bar';
 @use 'window_title';
 @use 'button';
+// The four button-derived nodes below, in the order of `src/elements/`: each one
+// renders a `.adw-button` of its own, so each rule comes AFTER `button` rather than
+// before it — `button.link`'s transparent background is the whole point of a link and
+// `.adw-button`'s resting fill must not win it on source order.
+@use 'link';
+@use 'scale_button';
+@use 'color_button';
+@use 'font_button';
 @use 'button_content';
 // The ONE popover surface. Emitted BEFORE the widgets that host one, so a
 // consumer's (or a widget's) own higher-specificity rule still wins over it.
 @use 'popover';
+// <gtk-popover-menu>, <gtk-popover-menu-bar> and <gtk-popover-bin>. All three AFTER
+// `popover`, because every surface they own is `<gtk-popover>`'s and none of them restates
+// it — they add the menubar's item rules and the bin's `.has-open-popup`, and libadwaita
+// puts both in the same file as `popover.menu` for the same reason.
+@use 'popover_menu_bar';
+@use 'popover_bin';
 @use 'split_button';
 @use 'menu_button';
 @use 'drop_down';
@@ -54,14 +81,73 @@
 // own copy of it until it was lifted out of `adw-switch-row {}`.
 @use 'switch';
 @use 'entry';
+@use 'search_entry';
+@use 'password_entry';
+@use 'separator';
+// `<gtk-text>`, `<gtk-text-view>` and `<gtk-editable-label>` — the widgets whose content is
+// text, and the two libadwaita blocks that paint a `text` node.
+@use 'text';
+// `<gtk-search-bar>`, which reads the header-bar tokens rather than the header bar's rules.
+@use 'search_bar';
+// <gtk-drawing-area>, the one widget of the gtk/drawing page that carries a rule of its
+// own. No dependency on anything above it — it styles one canvas — so the order here is
+// placement, not precedence.
+@use 'drawing';
+// The `dnd` node, which libadwaita styles once for the whole widget
+// (`_common.scss:30-32`) and which is otherwise geometry: a drag icon has no parent to lay
+// out in, because it is a GtkRoot with its own surface. No dependency on anything above it.
+@use 'drag_icon';
+// The layout CONTAINERS GTK owns and libadwaita only styles. `_paned` draws the divider as
+// an inset box-shadow on the `separator` node a `GtkPanedHandle` carries, which is a
+// different rule from `<gtk-separator>`'s own fill — so it needs its own partial rather
+// than a class the separator's rule would fight over.
+@use 'overlay';
+@use 'revealer';
+@use 'paned';
+@use 'expander';
 // The two form-control primitives, in ONE partial because upstream merges them
 // (there is no `_radio.scss` in libadwaita) — see _checks.scss.
 @use 'checks';
+@use 'spin_button';
+@use 'scale';
 @use 'progress_bar';
+// <gtk-level-bar>, next to the progress bar it is easy to confuse with. It has no
+// dependency on anything above it, so the order here is readability, not precedence.
+@use 'level_bar';
+// The three views, in dependency order: `list_view` declares the selectable-row mixin
+// and the rubber band that the other two include.
+@use 'list_view';
+@use 'grid_view';
+@use 'column_view';
+@use 'tree_expander';
+// The media group, in dependency order and nothing else: `picture` fits a replaced
+// element, `inscription` is text measured in characters and lines, `video` lays an
+// overlay out and hosts a `media_controls` inside its revealer, so `media_controls`
+// comes after `video` only in the sense that `video` NAMES it — neither partial reads
+// the other, and the order here is readability, not precedence.
+@use 'picture';
+@use 'inscription';
+@use 'video';
+@use 'media_controls';
+// The two child-holding containers. `list_box` comes first only because it reads like
+// `list_view`; nothing here is a `@use` of the other, and `flow_box` includes the selectable
+// mixin from `list_view` above for the cell's four state colours.
+@use 'list_box';
+@use 'flow_box';
+@use 'calendar';
 @use 'preferences';
+@use 'preferences_row';
 @use 'card';
 @use 'data_grid';
+@use 'bin';
 @use 'clamp';
+// <gtk-stack> AND <gtk-stack-switcher> AND <gtk-stack-sidebar>, in ONE partial: upstream
+// styles the switcher's buttons out of `_buttons.scss` and the sidebar's rows out of
+// `_sidebars.scss`, so a stack and the two things that switch over it share styles.
+@use 'stack';
+@use 'clamp_scrollable';
+// <adw-spinner> AND <gtk-spinner>, in ONE partial because upstream's
+// `_spinner.scss` styles `spinner` and `image.spinner` in the same file.
 @use 'spinner';
 // <adw-shortcut-label>'s keycaps. After `labels`, because a separator inside it
 // is an ordinary `.dimmed`.
@@ -80,24 +166,47 @@
 @use 'password_entry_row';
 @use 'toast';
 @use 'toolbar_view';
+// The scrolling trio, beside `_scrolling.scss`'s edge indicators: the scrollbar first,
+// because the scrolled window's grid places it, and the viewport before the window, because
+// the window's grid has a cell for it.
+@use 'scrollbar';
+@use 'viewport';
+@use 'scrolled_window';
+@use 'window_handle';
 @use 'scrolling';
 @use 'wrap_box';
 @use 'panes';
 @use 'overlay_split_view';
 @use 'navigation_split_view';
 @use 'carousel';
+// <adw-tab-bar> BEFORE <adw-tab-view>, and only because upstream writes both in ONE file:
+// `tabbar`, `tabbox` and `tab` (_tab-view.scss:1-95). The chip rules here and the merged
+// bar's are the same declarations against the same class names, so whichever partial is
+// emitted second would win on source order for a document that nests one bar in the other.
+@use 'tab_bar';
 @use 'tab_view';
 @use 'view_switcher';
 @use 'inline_view_switcher';
 @use 'view_stack';
 @use 'view_switcher_bar';
+@use 'tab_button';
+@use 'tab_overview';
+@use 'view_switcher_sidebar';
 @use 'navigation_view';
 @use 'bottom_sheet';
 @use 'sidebar';
+// GTK's own dialogs: the about window's layout, the emoji chooser's nodes, and the two
+// Unix print dialogs. After `popover` and `entry`, which the emoji chooser hosts.
+@use 'gtk_about_dialog';
+@use 'emoji_chooser';
+@use 'print_dialogs';
 @use 'about_dialog';
 @use 'alert_dialog';
 @use 'preferences_dialog';
 @use 'dialog';
+// After 'dialog': the shortcuts dialog IS an <adw-dialog> and adds sections and rows
+// inside its content area, so its own rules have to come after the chrome they sit in.
+@use 'shortcuts_dialog';
 // Last among the widgets: an authored `halign` / `valign` is placement the author asked
 // for, and an element rule that sets a margin must not win it back on source order.
 @use 'widget';

package/src/adw-action-rows.spec.ts

@@ -246,6 +246,82 @@ export const AdwActionRowsTest = async () => {
         }
     });
 
+    await describe('<adw-switch-row> prefix slot (inherited add_prefix)', async () => {
+        // Routing a live child and then deriving the box's emptiness are TWO observers in
+        // a chain: `slotted-children` moves the node into the box, and only that move is
+        // what `bindEmptySections` observes. One checkpoint sees the routing, two see the
+        // derivation.
+        const settleSlot = async () => {
+            await Promise.resolve();
+            await Promise.resolve();
+        };
+        await it('routes a DECLARED slot="prefix" child into the prefix box', () => {
+            // Adw.SwitchRow IS an AdwActionRow (adw-switch-row.c:50), so `add_prefix`
+            // and the box that carries it are inherited, not a web-only addition.
+            // The child is authored BEFORE the row reaches the document, which is the
+            // install pass rather than the observer.
+            const host = document.createElement('div');
+            document.body.appendChild(host);
+            const row = document.createElement('adw-switch-row') as AdwSwitchRow;
+            const icon = document.createElement('span');
+            icon.id = 'lead';
+            icon.setAttribute('slot', 'prefix');
+            row.appendChild(icon);
+            host.appendChild(row);
+
+            expect(icon.parentElement?.className).toBe('adw-switch-row-prefix');
+            host.remove();
+        });
+
+        await it('hides the box while it is empty', () => {
+            const { el: row, host } = mount<AdwSwitchRow>('adw-switch-row');
+            const box = row.querySelector('.adw-switch-row-prefix') as HTMLElement;
+            expect(box.hidden).toBe(true);
+            host.remove();
+        });
+
+        await it('routes a prefix appended AFTER connect, and un-hides the box', async () => {
+            // The live half: a renderer mounts the row and then appends the icon, which
+            // is a MutationObserver callback rather than the install pass — the incident
+            // `src/slotted-children.ts` records for 42 elements that snapshotted instead.
+            const { el: row, host } = mount<AdwSwitchRow>('adw-switch-row');
+            const box = row.querySelector('.adw-switch-row-prefix') as HTMLElement;
+
+            const icon = document.createElement('span');
+            icon.setAttribute('slot', 'prefix');
+            row.appendChild(icon);
+            await settleSlot();
+
+            expect(icon.parentElement).toBe(box);
+            expect(box.hidden).toBe(false);
+            host.remove();
+        });
+
+        await it('shows it again when the last prefix child leaves', async () => {
+            const { el: row, host } = mount<AdwSwitchRow>('adw-switch-row');
+            const icon = document.createElement('span');
+            icon.setAttribute('slot', 'prefix');
+            row.appendChild(icon);
+            await settleSlot();
+            const box = row.querySelector('.adw-switch-row-prefix') as HTMLElement;
+
+            expect(box.hidden).toBe(false);
+            icon.remove();
+            await Promise.resolve();
+            expect(box.hidden).toBe(true);
+            host.remove();
+        });
+
+        await it('exposes the box as prefixSection for the imperative spelling', () => {
+            const { el: row, host } = mount<AdwSwitchRow>('adw-switch-row');
+            const icon = document.createElement('span');
+            row.prefixSection.appendChild(icon);
+
+            expect(icon.parentElement).toBe(row.prefixSection);
+            host.remove();
+        });
+    });
+
     await describe('<adw-button-row> (libadwaita conformance vectors)', async () => {
         for (const vector of BUTTON_ROW_ICON_VECTORS) {
             await it(`${JSON.stringify([vector.startIconName, vector.endIconName])} — ${vector.rule}`, () => {

package/src/adw-application-window.spec.ts

@@ -0,0 +1,118 @@
+// DOM-level behaviour tests for <adw-application-window>. Runs in a real browser via the
+// @gjsify/adwaita-web browser test axis (tests/browser Playwright harness). The custom
+// elements are registered by importing the package root in test.browser.mts; these specs
+// create elements via document.createElement and assert their DOM behaviour.
+//
+// The subject is the MENUBAR and the inheritance: `Adw.ApplicationWindow` is
+// `Adw.Window` plus `Gtk.ApplicationWindow:show-menubar`, so the window half is
+// <adw-window>'s spec and only the delta is asserted here.
+import { describe, it, expect } from '@gjsify/unit';
+
+import type { AdwApplicationWindow } from './elements/adw-application-window.js';
+
+const MENU_MODEL = [
+    {
+        label: 'File',
+        submenu: [
+            { label: 'New Window', action: 'app.new-window' },
+            { label: 'Quit', action: 'app.quit' },
+        ],
+    },
+    { label: 'Help', action: 'app.help' },
+];
+
+function makeWindow(model: unknown = MENU_MODEL): AdwApplicationWindow {
+    const el = document.createElement('adw-application-window') as AdwApplicationWindow;
+    el.setAttribute('menu-model', JSON.stringify(model));
+    el.innerHTML = '<p>Content</p>';
+    document.body.appendChild(el);
+    return el;
+}
+
+export const AdwApplicationWindowTest = async () => {
+    await describe('adw-application-window is an adw-window', async () => {
+        await it('places children in the inherited content area', async () => {
+            const win = makeWindow();
+            expect(win.querySelector('.adw-window-content')?.querySelector('p')?.textContent).toBe('Content');
+            win.remove();
+        });
+
+        await it('keeps the inherited size request', async () => {
+            const win = makeWindow();
+            expect(win.style.width).toBe('360px');
+            win.setAttribute('width', '520');
+            expect(win.style.width).toBe('520px');
+            win.remove();
+        });
+    });
+
+    await describe('adw-application-window menubar', async () => {
+        await it('draws no bar without show-menubar', async () => {
+            const win = makeWindow();
+            expect(win.showMenubar).toBe(false);
+            expect(win.menubar?.hidden).toBe(true);
+            win.remove();
+        });
+
+        await it('draws no bar for an application that installed no menu', async () => {
+            // The GTK half of the same rule: a window with no model has no menubar,
+            // however the flag reads.
+            const win = makeWindow([]);
+            win.setAttribute('show-menubar', '');
+            expect(win.menubar?.hidden).toBe(true);
+            win.remove();
+        });
+
+        await it('a submenu becomes a menu button and a bare item a flat button', async () => {
+            const win = makeWindow();
+            win.setAttribute('show-menubar', '');
+
+            expect(win.menubar?.hidden).toBe(false);
+            const menuButton = win.menubar?.querySelector('gtk-menu-button');
+            expect(menuButton?.getAttribute('menu-title')).toBe('File');
+            const help = win.menubar?.querySelector('gtk-button');
+            expect(help?.getAttribute('label')).toBe('Help');
+            win.remove();
+        });
+
+        await it('the menubar sits above the content, inside the content area', async () => {
+            // It is a child of `.adw-window-content` rather than a sibling: the window's
+            // own slot binding would re-home a sibling into the content on the next tick.
+            const win = makeWindow();
+            win.setAttribute('show-menubar', '');
+            expect(win.contentArea.firstElementChild).toBe(win.menubar);
+            win.remove();
+        });
+
+        await it('the flag alone shows and hides the bar without a rebuild', async () => {
+            const win = makeWindow();
+            win.setAttribute('show-menubar', '');
+            expect(win.menubar?.hidden).toBe(false);
+            win.removeAttribute('show-menubar');
+            expect(win.menubar?.hidden).toBe(true);
+            win.remove();
+        });
+
+        await it('a bare item reports its activation the way every menu surface does', async () => {
+            const win = makeWindow();
+            win.setAttribute('show-menubar', '');
+            const seen: unknown[] = [];
+            win.addEventListener('menu-item-activated', (e) => seen.push((e as CustomEvent).detail));
+            (win.menubar?.querySelector('gtk-button') as HTMLButtonElement | null)?.click();
+            expect(seen).toStrictEqual([{ id: 'Help', label: 'Help', path: [1] }]);
+            win.remove();
+        });
+
+        await it('a broken model is dropped rather than thrown', async () => {
+            // `parseMenuModel` is total by construction: a typo in markup must not take
+            // the window down with it.
+            const win = document.createElement('adw-application-window') as AdwApplicationWindow;
+            win.setAttribute('menu-model', '{not json');
+            win.setAttribute('show-menubar', '');
+            document.body.appendChild(win);
+            expect(win.menuModel).toStrictEqual([]);
+            expect(win.menubar?.hidden).toBe(true);
+            win.remove();
+        });
+    });
+};

package/src/adw-bin.spec.ts

@@ -0,0 +1,75 @@
+// DOM-level tests for <adw-bin>: the ONE child a bin holds, that `setChild` REPLACES
+// rather than stacks (adw-bin.c:193-219), and that a child which already has a parent
+// is refused the way C's `g_return_if_fail (gtk_widget_get_parent (child) == NULL)`
+// refuses it.
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { AdwBin } from './elements/adw-bin.js';
+
+function mount(children: Node[] = []): { el: AdwBin; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const el = document.createElement('adw-bin') as AdwBin;
+    host.appendChild(el);
+    for (const child of children) el.appendChild(child);
+    return { el, host };
+}
+
+export const AdwBinTest = async () => {
+    await describe('<adw-bin> one child', async () => {
+        await it('holds whatever it was given, and reports it as `child`', () => {
+            const label = document.createElement('div');
+            const { el, host } = mount([label]);
+            expect(el.child).toBe(label);
+            expect(el.childElementCount).toBe(1);
+            host.remove();
+        });
+
+        await it('a second child REPLACES the first, which is what adw_bin_set_child does', async () => {
+            const first = document.createElement('div');
+            const second = document.createElement('div');
+            const { el, host } = mount([first]);
+            el.appendChild(second);
+            await new Promise<void>((resolve) => setTimeout(resolve, 0));
+            expect(el.child).toBe(second);
+            expect(el.childElementCount).toBe(1);
+            expect(first.parentNode).toBeNull();
+            host.remove();
+        });
+
+        await it('setChild notifies once, and not for the child it already holds', async () => {
+            const { el, host } = mount();
+            const details: unknown[] = [];
+            el.addEventListener('notify::child', (event) => details.push((event as CustomEvent).detail));
+            const child = document.createElement('div');
+            el.child = child;
+            expect(el.child).toBe(child);
+            el.setChild(child);
+            expect(details).toStrictEqual([{ child }]);
+            host.remove();
+        });
+
+        await it('refuses a child that already has a parent, as C does', () => {
+            const other = document.createElement('div');
+            document.body.appendChild(other);
+            const stray = document.createElement('span');
+            other.appendChild(stray);
+            const { el, host } = mount();
+            expect(() => el.setChild(stray)).toThrow();
+            expect(el.child).toBeNull();
+            host.remove();
+            other.remove();
+        });
+
+        await it('an empty bin is a block box, and its only child fills it', () => {
+            const { el, host } = mount([document.createElement('div')]);
+            // A bin takes the size it is GIVEN and hands all of it to the child, which
+            // `GtkBinLayout` does on both axes (gtkbinlayout.c:81).
+            el.style.height = '120px';
+            expect(getComputedStyle(el).display).toBe('block');
+            const child = el.firstElementChild as HTMLElement;
+            expect(child.getBoundingClientRect().height).toBe(120);
+            host.remove();
+        });
+    });
+};