@gjsify/adwaita-web 0.33.0 → 0.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-web",
-    "version": "0.33.0",
+    "version": "0.35.0",
     "description": "Adwaita/Libadwaita web components for browser targets",
     "type": "module",
     "main": "./src/index.ts",
@@ -41,14 +41,14 @@
         "@codemirror/language": "^6.12.4",
         "@codemirror/state": "^6.7.0",
         "@codemirror/view": "^6.43.4",
-        "@gjsify/adwaita-core": "^0.33.0",
-        "@gjsify/adwaita-fonts": "^0.33.0",
-        "@gjsify/adwaita-icons": "^0.33.0",
+        "@gjsify/adwaita-core": "^0.35.0",
+        "@gjsify/adwaita-fonts": "^0.35.0",
+        "@gjsify/adwaita-icons": "^0.35.0",
         "@lezer/highlight": "^1.2.3"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.33.0",
-        "@gjsify/unit": "^0.33.0",
+        "@gjsify/cli": "^0.35.0",
+        "@gjsify/unit": "^0.35.0",
         "sass": "^1.101.0",
         "typescript": "^6.0.3"
     },

package/scss/_navigation_split_view.scss

@@ -22,12 +22,16 @@ adw-navigation-split-view {
   min-width: 0;
   flex: 1 1 auto;
 
+  // NO background here — it comes from the `.sidebar-pane` class the element
+  // applies while DOCKED (see _panes.scss). Collapsed, libadwaita builds no
+  // pane bins at all and the sidebar is an ordinary full-window navigation
+  // page; a background nailed to this private class made it sidebar-coloured
+  // at every width.
   .adw-nsv-sidebar {
     display: flex;
     flex-direction: column;
     min-height: 0;
     flex-shrink: 0;
-    background-color: var(--sidebar-bg-color);
   }
 
   // The container MINIMUM, as CSS spells it: `measure_uncollapsed`

package/scss/_navigation_view.scss

@@ -16,9 +16,13 @@ adw-navigation-view {
   background-color: var(--window-bg-color);
   color: var(--window-fg-color);
 
-  // The page stack — fills the view; positioned so pages can stack.
+  // The page stack — fills the view when it is given a height, and MEASURES the
+  // visible page when it is not. A flex column rather than a positioning
+  // context: the page is an in-flow item, so its content reaches the view.
   .adw-navigation-view-pages {
     flex: 1 1 auto;
+    display: flex;
+    flex-direction: column;
     position: relative;
     box-sizing: border-box;
     min-height: 0;
@@ -26,11 +30,31 @@ adw-navigation-view {
   }
 
   // A single navigation page — the visible one fills the view, the rest are
-  // hidden. Positioned absolutely so a transition can overlap two pages.
+  // `display: none`.
+  //
+  // IN FLOW, not absolute. It was `position: absolute; inset: 0` under a comment
+  // saying it had to be "so a transition can overlap two pages" — but two pages
+  // never overlap here: `adw-navigation-view.ts` marks every page but the
+  // visible one `[hidden]`, which is `display: none` below, and the push
+  // animation runs on `.visible-page` alone. So the absolute positioning bought
+  // an overlap that does not happen, and what it cost was the HEIGHT: an
+  // absolutely-positioned child contributes nothing to its parent, so the page
+  // stack measured 0, the view above it measured 0, and the page — `inset: 0` of
+  // a zero-height parent — measured 0 in turn. A closed circle.
+  //
+  // Inside a window that never showed, because a definite height arrived from
+  // outside. `<adw-about-dialog>` is the case where none does: its sheet is
+  // `position: fixed` with a width and no height, exactly as
+  // `adw-about-dialog.ui` declares it (`content-width` 360, no content-height —
+  // libadwaita takes the height from the content). The whole dialog rendered
+  // invisible, with a header bar inside it genuinely measuring 47px.
+  //
+  // `flex: 1 1 auto` keeps the fill: given a height the page still grows into
+  // it; without one it reports its content.
   .adw-navigation-page {
     box-sizing: border-box;
-    position: absolute;
-    inset: 0;
+    position: relative;
+    flex: 1 1 auto;
     display: flex;
     flex-direction: column;
     overflow: auto;

package/scss/_overlay_split_view.scss

@@ -27,8 +27,12 @@ adw-overlay-split-view {
   position: relative;
   overflow: hidden;
 
+  // NO background here. The pane colour comes from the `.sidebar-pane` /
+  // `.overlay-pane` class the element toggles (see _panes.scss), because which
+  // of the two a pane is in is exactly what decides its colour — hard-coding
+  // `--sidebar-bg-color` on this private class painted a collapsed overlay,
+  // which libadwaita puts on the window background, as though it were docked.
   .adw-osv-sidebar {
-    background-color: var(--sidebar-bg-color);
     overflow-y: auto;
     flex-shrink: 0;
     z-index: 10;

package/scss/_panes.scss

@@ -0,0 +1,57 @@
+// _panes.scss — `.sidebar-pane` / `.content-pane` / `.overlay-pane`.
+//
+// These are libadwaita STYLE CLASSES, not private markup of one widget. Both
+// split views document them as their CSS node tree
+// (adw-navigation-split-view.c:157-165, adw-overlay-split-view.c:136-152) and
+// both apply them to their pane bins, which makes them the supported hook an
+// app themes a pane through. They lived nowhere in this stylesheet, so each
+// split view hard-coded `--sidebar-bg-color` onto its own private pane div
+// instead — with two consequences.
+//
+// The first is that an app writing the documented selector styles nothing, and
+// gets no error saying so. Our own docs site is the evidence: every split-view
+// example carried `class="sidebar"` on the sidebar toolbar view, hand-written
+// by someone reaching for exactly this, matching no rule in the build.
+//
+// The second is a rendering defect, because the class is not constant — it is
+// how the widget says which of its states a pane is in. A collapsed overlay
+// sidebar is an `.overlay-pane`, on the WINDOW background, not the sidebar one
+// (adw-overlay-split-view.c:718-741); a collapsed navigation split view has no
+// pane bins at all, its pages being ordinary navigation pages. Painting the
+// sidebar colour at every width, as the private rules did, got both wrong.
+//
+// Reference: refs/libadwaita/src/stylesheet/widgets/_sidebars.scss (.sidebar-pane, .overlay-pane)
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Modifications: Adapted for @gjsify/adwaita-web Web Components.
+
+.sidebar-pane {
+  background-color: var(--sidebar-bg-color);
+  color: var(--sidebar-fg-color);
+}
+
+// A pane nested inside another sidebar pane defers to it rather than stacking a
+// second tint (`.sidebar-pane .sidebar-pane`, _sidebars.scss). libadwaita also
+// recolours the MIDDLE pane of a three-pane setup through
+// `--secondary-sidebar-*`; that needs a split view nested in a split view to
+// mean anything, and no such composition is rendered yet, so the tokens are
+// defined (they are public API an app may already reference) and the selector
+// is left for whoever builds the composition that can test it.
+.sidebar-pane .sidebar-pane {
+  background-color: transparent;
+  color: inherit;
+}
+
+// `.content-pane` deliberately has NO rule here. libadwaita gives it no colour
+// of its own — the window shows through — and writing `transparent` would be a
+// claim, not a copy: it would override the `--window-bg-color` the navigation
+// split view sets on its own content pane for the case where the view is not a
+// window's direct child. The class is still applied, because being able to
+// select it is the point.
+
+// Collapsed: the sidebar floats ABOVE the content as a temporary panel, and
+// libadwaita gives it the window colours rather than the sidebar ones — a panel
+// over the content is not the same surface as a pane beside it.
+.overlay-pane {
+  background-color: var(--window-bg-color);
+  color: var(--window-fg-color);
+}

package/scss/_sidebar.scss

@@ -62,12 +62,19 @@ adw-sidebar {
   }
 
   // --- A single item row ---
+  //
+  // NO `width: 100%`. The list is a column flex container, so a row already
+  // stretches to it — and stretching SUBTRACTS the row's own margins, which is
+  // what puts the same 6px of air on both sides. `width: 100%` resolves against
+  // the containing block INSTEAD, which does not know about the margins, so
+  // every row came out 12px too wide: inset 6px on the left, hanging 6px past
+  // the right edge with its rounded corners cut off by the pane. Visible on any
+  // selected or hovered row, because only a filled row shows where it ends.
   .adw-sidebar-item {
     box-sizing: border-box;
     display: flex;
     align-items: center;
     gap: var(--spacing-m);
-    width: 100%;
     min-height: 36px;
     // The native row has a context menu, so padding lives on the inner box and
     // the row itself carries the menu margin + radius.

package/scss/_theme.scss

@@ -14,6 +14,15 @@
   --headerbar-shade-color: rgba(0, 0, 6, 0.36);
   --separator-color: rgba(255, 255, 255, 0.08);
   --sidebar-bg-color: #2e2e32;
+  --sidebar-fg-color: #ffffff;
+  --sidebar-backdrop-color: #28282c;
+  --sidebar-shade-color: rgba(0, 0, 6, 0.25);
+  --sidebar-border-color: rgba(0, 0, 6, 0.36);
+  --secondary-sidebar-bg-color: #28282c;
+  --secondary-sidebar-fg-color: #ffffff;
+  --secondary-sidebar-backdrop-color: #252529;
+  --secondary-sidebar-shade-color: rgba(0, 0, 6, 0.25);
+  --secondary-sidebar-border-color: rgba(0, 0, 6, 0.36);
   --card-bg-color: rgba(255, 255, 255, 0.08);
   --card-fg-color: #ffffff;
   --card-shade-color: rgba(0, 0, 6, 0.36);

package/scss/_variables.scss

@@ -24,8 +24,25 @@
   // draws separators, instead of a harsh near-black line on a dark surface.
   --separator-color: rgba(0, 0, 6, 0.1);
 
-  // Sidebar
+  // Sidebar / split panes. libadwaita defines the whole family, not just the
+  // background (_colors.scss:47-58), and only the background was here — so
+  // `.sidebar-pane` had no foreground to name, and an app overriding
+  // `--sidebar-fg-color` was overriding nothing.
   --sidebar-bg-color: #ebebed;
+  --sidebar-fg-color: rgba(0, 0, 6, 0.8);
+  --sidebar-backdrop-color: #f2f2f4;
+  --sidebar-shade-color: rgba(0, 0, 6, 0.07);
+  --sidebar-border-color: rgba(0, 0, 6, 0.07);
+
+  // The MIDDLE pane of a three-pane setup. Nothing renders one yet; the tokens
+  // are defined because they are public API an app may already reference, and a
+  // half-present family reads as "this one is unsupported" rather than "this
+  // composition is not built yet".
+  --secondary-sidebar-bg-color: #f3f3f5;
+  --secondary-sidebar-fg-color: rgba(0, 0, 6, 0.8);
+  --secondary-sidebar-backdrop-color: #f6f6fa;
+  --secondary-sidebar-shade-color: rgba(0, 0, 6, 0.07);
+  --secondary-sidebar-border-color: rgba(0, 0, 6, 0.07);
 
   // Cards / boxed lists
   --card-bg-color: #ffffff;

package/scss/adwaita-skin.scss

@@ -66,6 +66,7 @@
 @use 'toast';
 @use 'toolbar_view';
 @use 'wrap_box';
+@use 'panes';
 @use 'overlay_split_view';
 @use 'navigation_split_view';
 @use 'carousel';

package/src/adw-about-dialog.spec.ts

@@ -347,4 +347,40 @@ export const AdwAboutDialogTest = async () => {
             mounted.dispose();
         });
     });
+
+    // AN OPENED DIALOG HAS TO OCCUPY SPACE.
+    //
+    // Every other test in this file reads the built DOM, and all of them passed
+    // while the dialog rendered INVISIBLE — its sheet measured 360×0. The suite
+    // could not see that, because none of it looks at geometry.
+    //
+    // The sheet is `position: fixed` with a width and no height, which is what
+    // `adw-about-dialog.ui:7` declares: `content-width` 360 and no
+    // content-height, libadwaita taking the height from the content. The content
+    // could not supply one — the navigation pages were absolutely positioned, so
+    // they contributed nothing to the page stack, which contributed nothing to
+    // the view, which left the sheet at zero; and the pages, being `inset: 0` of
+    // a zero-height parent, were zero in turn.
+    await describe('adw-about-dialog — an opened dialog is actually on screen', async () => {
+        await it('gives its sheet a height derived from its content', () => {
+            const mounted = mount({ 'application-name': 'Adwaita Storybook', version: '0.11.0' });
+            mounted.dialog.setAttribute('open', '');
+
+            const sheet = mounted.dialog.querySelector('.adw-about-dialog-sheet') as HTMLElement;
+            const rect = sheet.getBoundingClientRect();
+            // HEIGHT only. The width was never the defect, and pinning it here
+            // needs `calc(100vw - 48px)` restated in JS — where `100vw` and
+            // `innerWidth` disagree by the scrollbar (360 against a measured
+            // 342), so the assertion would report the harness rather than the
+            // widget. A test should assert the rule the bug broke.
+            expect(rect.height > 0).toBe(true);
+            // And not merely the header: the sheet has to be taller than the one
+            // child that had a size of its own all along, which is what made the
+            // collapse invisible to every other test in this file.
+            const header = sheet.querySelector('adw-header-bar') as HTMLElement;
+            expect(rect.height > header.getBoundingClientRect().height).toBe(true);
+
+            mounted.dispose();
+        });
+    });
 };

package/src/adw-sidebar.spec.ts

@@ -329,4 +329,36 @@ export const AdwSidebarTest = async () => {
             host.remove();
         });
     });
+
+    // A row's own box, which nothing had ever measured.
+    //
+    // `.adw-sidebar-item` carried `width: 100%` ON TOP of `margin: 0 6px 2px`.
+    // The list is a column flex container, so a row already stretches to it and
+    // stretching subtracts margins; `width: 100%` resolves against the
+    // containing block instead, which does not, so every row came out 12px too
+    // wide — inset on the left, hanging past the right edge with its rounded
+    // corners clipped away. Every earlier test asked what a row CONTAINED, so
+    // all of them passed.
+    await describe('a sidebar row sits inside its list, not over its edge', async () => {
+        await it('leaves the same margin on both sides', async () => {
+            const { sidebar, host } = mountSidebar([{ items: [{ title: 'Inbox' }, { title: 'Starred' }] }], {
+                selected: '0',
+            });
+            host.setAttribute('style', 'width:220px');
+
+            const list = sidebar.querySelector('.adw-sidebar-list') as HTMLElement;
+            const listBox = list.getBoundingClientRect();
+
+            for (const row of rowsOf(sidebar)) {
+                const box = row.getBoundingClientRect();
+                const left = box.left - listBox.left;
+                const right = listBox.right - box.right;
+                // Symmetric, and INSIDE — a negative right gap is the overhang.
+                expect(Math.round(left)).toBe(Math.round(right));
+                expect(right >= 0).toBe(true);
+            }
+
+            host.remove();
+        });
+    });
 };

package/src/elements/adw-navigation-split-view.ts

@@ -273,6 +273,16 @@ export class AdwNavigationSplitView extends HTMLElement {
             isSidebarAtVisualStart(state.sidebarPosition, this._direction),
         );
 
+        // THE PANE STYLE CLASSES, and only while docked. libadwaita builds the
+        // two `.sidebar-pane` / `.content-pane` bins in the UNCOLLAPSED branch
+        // alone (:583-608); collapsed, both pages move into one AdwNavigationView
+        // and neither bin exists (:552-568) — so a collapsed sidebar is a full
+        // window page on the WINDOW background, not a sidebar-coloured one.
+        // Painting it `--sidebar-bg-color` at every width, as this did, is the
+        // same defect the overlay view has with `.overlay-pane`.
+        this._sidebarEl?.classList.toggle('sidebar-pane', !state.collapsed);
+        this._contentEl?.classList.toggle('content-pane', !state.collapsed);
+
         // The STACK, not the two flags: `update_navigation_stack` (:342-405)
         // keeps a LONE child visible whatever `show-content` says, and with
         // `sidebar-position: end` the CONTENT is the root page — so the sidebar

package/src/elements/adw-overlay-split-view.ts

@@ -442,6 +442,23 @@ export class AdwOverlaySplitView extends HTMLElement {
         // alone cannot get right: the divider follows where the pane is DRAWN.
         this.classList.toggle('sidebar-at-visual-start', atStart);
 
+        // THE PANE STYLE CLASSES, which libadwaita documents as part of this
+        // widget's CSS node tree (adw-overlay-split-view.c:138-152) and switches
+        // in `update_collapsed` (:718-741): docked, the panes are `.sidebar-pane`
+        // and `.content-pane`; collapsed, the sidebar becomes an `.overlay-pane`
+        // floating above a content pane that carries no class at all.
+        //
+        // They are not decoration. `.overlay-pane` is what makes a collapsed
+        // sidebar drop the sidebar background for the window one, and they are
+        // the documented hook an app themes its own panes through — so leaving
+        // them off does not merely look wrong, it makes correct app CSS a no-op.
+        // The docs site is the proof: its split-view examples carried a
+        // hand-written `class="sidebar"` that styled nothing, written by someone
+        // reaching for exactly this and finding nothing there.
+        this._sidebarEl?.classList.toggle('sidebar-pane', !state.collapsed);
+        this._sidebarEl?.classList.toggle('overlay-pane', state.collapsed);
+        this._contentEl?.classList.toggle('content-pane', !state.collapsed);
+
         // Derived, not re-decided here: the shield only exists while collapsed
         // AND revealed, and each pane is reachable by keyboard only when it is
         // the one on screen.

package/src/split-views.spec.ts

@@ -890,4 +890,95 @@ export const AdwSplitViewsTest = async () => {
             host.remove();
         });
     });
+
+    // The pane STYLE CLASSES, which libadwaita documents as each split view's
+    // CSS node tree and which an app is meant to be able to select.
+    //
+    // They were absent entirely, and both views hard-coded `--sidebar-bg-color`
+    // onto their own private pane class instead. That is not the same thing
+    // twice: the class is not constant. It says which STATE a pane is in, and
+    // the colour follows from that — so a collapsed overlay sidebar, which
+    // libadwaita puts on the window background, was painted as though it were
+    // still docked beside the content.
+    //
+    // Asserting the class names and not only the colours is deliberate. The
+    // names are the app-facing contract; a rendering that happened to look right
+    // through some other selector would still have broken every app stylesheet
+    // written against the documented one.
+    await describe('split-view panes carry libadwaita pane style classes', async () => {
+        const bg = (el: Element) => getComputedStyle(el).backgroundColor;
+        const token = (name: string) => {
+            const probe = document.createElement('div');
+            probe.style.backgroundColor = `var(${name})`;
+            document.body.appendChild(probe);
+            const value = getComputedStyle(probe).backgroundColor;
+            probe.remove();
+            return value;
+        };
+
+        await it('overlay: docked panes are .sidebar-pane / .content-pane', async () => {
+            const { view, host } = mount('show-sidebar');
+            host.setAttribute('style', 'width:900px;height:300px;display:flex');
+            await settle();
+            const sidebar = view.querySelector('.adw-osv-sidebar') as HTMLElement;
+            const content = view.querySelector('.adw-osv-content') as HTMLElement;
+
+            expect(sidebar.classList.contains('sidebar-pane')).toBe(true);
+            expect(sidebar.classList.contains('overlay-pane')).toBe(false);
+            expect(content.classList.contains('content-pane')).toBe(true);
+            expect(bg(sidebar)).toBe(token('--sidebar-bg-color'));
+            host.remove();
+        });
+
+        await it('overlay: collapsing turns the sidebar into an .overlay-pane on the window background', async () => {
+            const { view, host } = mount('show-sidebar');
+            host.setAttribute('style', 'width:900px;height:300px;display:flex');
+            await settle();
+            const sidebar = view.querySelector('.adw-osv-sidebar') as HTMLElement;
+            const content = view.querySelector('.adw-osv-content') as HTMLElement;
+
+            view.setAttribute('collapsed', '');
+            await settle();
+            expect(sidebar.classList.contains('overlay-pane')).toBe(true);
+            expect(sidebar.classList.contains('sidebar-pane')).toBe(false);
+            // Collapsed, libadwaita removes `.content-pane` outright — the
+            // content is no longer one pane of two, it is the whole view.
+            expect(content.classList.contains('content-pane')).toBe(false);
+            expect(bg(sidebar)).toBe(token('--window-bg-color'));
+
+            // And back: the class follows the state in BOTH directions. A
+            // one-way toggle would leave a re-expanded sidebar window-coloured.
+            view.removeAttribute('collapsed');
+            await settle();
+            expect(sidebar.classList.contains('sidebar-pane')).toBe(true);
+            expect(bg(sidebar)).toBe(token('--sidebar-bg-color'));
+            host.remove();
+        });
+
+        await it('navigation: the pane classes exist while docked and are dropped when collapsed', async () => {
+            const host = document.createElement('div');
+            host.setAttribute('style', 'width:900px;height:300px;display:flex');
+            document.body.appendChild(host);
+            host.innerHTML =
+                '<adw-navigation-split-view><div slot="sidebar">s</div><div slot="content">c</div></adw-navigation-split-view>';
+            const view = host.querySelector('adw-navigation-split-view') as AdwNavigationSplitView;
+            await settle();
+            const sidebar = view.querySelector('.adw-nsv-sidebar') as HTMLElement;
+            const content = view.querySelector('.adw-nsv-content') as HTMLElement;
+
+            expect(sidebar.classList.contains('sidebar-pane')).toBe(true);
+            expect(content.classList.contains('content-pane')).toBe(true);
+            expect(bg(sidebar)).toBe(token('--sidebar-bg-color'));
+
+            // Collapsed, libadwaita builds no pane bins at all: both pages move
+            // into one navigation view, so the sidebar is an ordinary full-width
+            // page and must stop being sidebar-coloured.
+            view.setAttribute('collapsed', '');
+            await settle();
+            expect(sidebar.classList.contains('sidebar-pane')).toBe(false);
+            expect(content.classList.contains('content-pane')).toBe(false);
+            expect(bg(sidebar)).not.toBe(token('--sidebar-bg-color'));
+            host.remove();
+        });
+    });
 };