@gjsify/adwaita-web 0.37.0 → 0.38.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-web",
-    "version": "0.37.0",
+    "version": "0.38.1",
     "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.37.0",
-        "@gjsify/adwaita-fonts": "^0.37.0",
-        "@gjsify/adwaita-icons": "^0.37.0",
+        "@gjsify/adwaita-core": "^0.38.1",
+        "@gjsify/adwaita-fonts": "^0.38.1",
+        "@gjsify/adwaita-icons": "^0.38.1",
         "@lezer/highlight": "^1.2.3"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.37.0",
-        "@gjsify/unit": "^0.37.0",
+        "@gjsify/cli": "^0.38.1",
+        "@gjsify/unit": "^0.38.1",
         "sass": "^1.101.0",
         "typescript": "^6.0.3"
     },
@@ -60,7 +60,18 @@
             "browser": "polyfill",
             "nativescript": "none"
         },
-        "tier": 2
+        "tier": 2,
+        "nodeScript": {
+            "excludeGlobals": [
+                "document",
+                "HTMLElement",
+                "HTMLCanvasElement",
+                "Path2D",
+                "MutationObserver",
+                "navigator",
+                "process"
+            ]
+        }
     },
     "license": "MIT",
     "repository": {

package/scss/_theme.scss

@@ -4,6 +4,10 @@
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Adapted for @gjsify/adwaita-web Web Components.
 
+// `light-theme` lives in _variables.scss; @use makes it reachable (the skin uses
+// the module system, so a mixin there is namespaced rather than global).
+@use 'variables';
+
 @mixin dark-theme {
   --window-bg-color: #222226;
   --window-fg-color: #ffffff;
@@ -64,7 +68,21 @@
   }
 }
 
-// Manual override
-:root.theme-dark {
+// Manual override, on ANY element rather than only on `:root`.
+//
+// It was `:root.theme-dark`, which silently does nothing unless the class lands on
+// `<html>` — so an EMBEDDED consumer could not give its own subtree a scheme without
+// re-theming the host page around it. The storybook is exactly that case: it scopes
+// to its own container, the class was present, the tokens never changed, and nothing
+// reported a problem. Custom properties resolve per element, so an element-level
+// selector overrides the inherited values for its subtree and for nothing else.
+.theme-dark {
   @include dark-theme;
 }
+
+// The light counterpart, for the same reason: on a dark system a subtree has to be
+// able to ask for light, which `:root:not(.theme-light)` on the media query above
+// cannot give it once the class sits anywhere but the root.
+.theme-light {
+  @include variables.light-theme;
+}

package/scss/_variables.scss

@@ -5,7 +5,7 @@
 // Copyright (c) 2025 csm (adwaita-web). MIT License.
 // Modifications: Subset adapted for @gjsify/adwaita-web Web Components.
 
-:root {
+@mixin light-theme {
   // Window
   --window-bg-color: #fafafb;
   --window-fg-color: rgba(0, 0, 6, 0.8);
@@ -150,6 +150,14 @@
   --monospace-font-size: var(--font-size-base);
 }
 
+// The tokens above are a MIXIN rather than a bare `:root` block so `.theme-light`
+// can include them too (see `_theme.scss`). A light opt-out that exists only as
+// `:not(.theme-light)` on the media query cannot serve a SUBTREE: on a dark system
+// the root stays dark, and a container asking for light matches no rule at all.
+:root {
+  @include light-theme;
+}
+
 // High contrast moves the three opacity tokens, and only those — every colour
 // that reads them follows without its own query (_colors.scss:325-329).
 @media (prefers-contrast: more) {

package/src/accent.ts

@@ -0,0 +1,74 @@
+// Applying an Adwaita accent in the browser — the renderer half.
+//
+// The palette and the OkLab standalone derivation are `@gjsify/adwaita-core`'s
+// (ADR 0004). This sets the two custom properties every accent-coloured rule in
+// the stylesheet already reads:
+//
+//   --accent-bg-color   the fill, with white on top
+//   --accent-color      the standalone colour, for text on the window
+//
+// BOTH ARE SET EXPLICITLY, from core's arithmetic, rather than setting only the
+// background and letting CSS derive the other with
+// `oklab(from var(--accent-bg-color) min(l, 0.5) a b)` — which is what
+// libadwaita's own stylesheet does (`_colors.scss:166-170`). Two reasons: core is
+// then the single source of truth for a value three renderers have to agree on,
+// and the relative-colour form needs channel keywords inside `min()`, which is
+// newer than this package's baseline. The CSS route stays available to a consumer
+// who wants it; nothing here depends on it.
+//
+// NOTE, and it is a pre-existing inconsistency rather than something introduced
+// here: `_variables.scss:55` hardcodes `--accent-color: #1c71d8` for the default
+// blue, while libadwaita derives `#0461be`. The semantic colours in the same file
+// DO use the relative-colour expression. Applying an accent through this module
+// therefore also corrects the standalone colour; leaving it unset keeps the
+// legacy value.
+//
+// Reference: refs/libadwaita/src/stylesheet/_colors.scss:146-170
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+
+import { adwaitaAccentBgColor, adwaitaAccentColor, type AdwAccentColorName } from '@gjsify/adwaita-core';
+
+/** The custom property carrying the accent fill. */
+export const ACCENT_BG_PROPERTY = '--accent-bg-color';
+/** The custom property carrying the standalone accent, for text on the window. */
+export const ACCENT_PROPERTY = '--accent-color';
+
+/** Where and how to apply the accent. */
+export interface ApplyAccentOptions {
+    /** The element to set the properties on. Defaults to `document.documentElement`. */
+    readonly target?: HTMLElement;
+    /**
+     * Which standalone variant to use. Defaults to the target's RESOLVED scheme,
+     * because the standalone colour is the one thing about an accent that differs
+     * between light and dark — reading it beats assuming light.
+     */
+    readonly dark?: boolean;
+}
+
+/**
+ * Whether `element` is currently rendering dark.
+ *
+ * `.theme-dark` / `.theme-light` are the stylesheet's manual overrides and win
+ * over the media query, so an explicit class is checked first and
+ * `prefers-color-scheme` only decides when neither is present.
+ */
+export function isAdwaitaDark(element: HTMLElement): boolean {
+    if (element.closest('.theme-dark')) return true;
+    if (element.closest('.theme-light')) return false;
+    return globalThis.matchMedia?.('(prefers-color-scheme: dark)').matches ?? false;
+}
+
+/** Set the accent custom properties for `name`. */
+export function applyAdwaitaAccent(name: AdwAccentColorName, options: ApplyAccentOptions = {}): void {
+    const target = options.target ?? document.documentElement;
+    const dark = options.dark ?? isAdwaitaDark(target);
+
+    target.style.setProperty(ACCENT_BG_PROPERTY, adwaitaAccentBgColor(name));
+    target.style.setProperty(ACCENT_PROPERTY, adwaitaAccentColor(name, dark));
+}
+
+/** Drop the properties, so the stylesheet's own values apply again. */
+export function clearAdwaitaAccent(target: HTMLElement = document.documentElement): void {
+    target.style.removeProperty(ACCENT_BG_PROPERTY);
+    target.style.removeProperty(ACCENT_PROPERTY);
+}

package/src/adw-accent.spec.ts

@@ -0,0 +1,105 @@
+// Accent application against `ACCENT_COLOR_VECTORS` — the same table the core
+// suite drives, here through the REAL computed style of a real element.
+//
+// This is what makes the table renderer-driven rather than a derivation asserted
+// against itself: the browser resolves the custom properties and the assertions
+// read them back with `getComputedStyle`, so a value that never reaches the
+// cascade fails a test naming the accent.
+import { describe, expect, it } from '@gjsify/unit';
+import { ACCENT_COLOR_VECTORS } from '@gjsify/adwaita-core/conformance';
+
+import '@gjsify/adwaita-web';
+import {
+    ACCENT_BG_PROPERTY,
+    ACCENT_PROPERTY,
+    applyAdwaitaAccent,
+    clearAdwaitaAccent,
+    isAdwaitaDark,
+} from './accent.js';
+
+/** A custom property's resolved value, whitespace trimmed. */
+const property = (element: HTMLElement, name: string): string =>
+    getComputedStyle(element).getPropertyValue(name).trim();
+
+export const AdwAccentTest = async () => {
+    await describe('applyAdwaitaAccent (conformance vectors)', async () => {
+        for (const vector of ACCENT_COLOR_VECTORS) {
+            await it(`${vector.name} — the fill and the light standalone colour reach the cascade`, async () => {
+                const host = document.createElement('div');
+                host.className = 'theme-light';
+                document.body.append(host);
+
+                applyAdwaitaAccent(vector.name, { target: host });
+
+                expect(property(host, ACCENT_BG_PROPERTY)).toBe(vector.background);
+                expect(property(host, ACCENT_PROPERTY)).toBe(vector.standaloneLight);
+
+                host.remove();
+            });
+
+            await it(`${vector.name} — the DARK standalone colour differs and is the table's`, async () => {
+                // Asserted as a pair: a renderer that ignored `dark` would pass
+                // every light row above and still be wrong in half its uses.
+                const host = document.createElement('div');
+                host.className = 'theme-dark';
+                document.body.append(host);
+
+                applyAdwaitaAccent(vector.name, { target: host });
+
+                expect(property(host, ACCENT_PROPERTY)).toBe(vector.standaloneDark);
+                expect(vector.standaloneDark).not.toBe(vector.standaloneLight);
+
+                host.remove();
+            });
+        }
+    });
+
+    await describe('accent application', async () => {
+        await it('reads the resolved scheme from the element rather than assuming light', async () => {
+            const dark = document.createElement('div');
+            dark.className = 'theme-dark';
+            const light = document.createElement('div');
+            light.className = 'theme-light';
+            document.body.append(dark, light);
+
+            expect(isAdwaitaDark(dark)).toBe(true);
+            expect(isAdwaitaDark(light)).toBe(false);
+
+            // A nested element inherits the ancestor's scheme — `closest`, not a
+            // class check on the element itself, which is how the stylesheet's
+            // `.theme-dark` scope actually behaves.
+            const nested = document.createElement('span');
+            dark.append(nested);
+            expect(isAdwaitaDark(nested)).toBe(true);
+
+            dark.remove();
+            light.remove();
+        });
+
+        await it('an explicit dark option overrides what the element resolves to', async () => {
+            const host = document.createElement('div');
+            host.className = 'theme-light';
+            document.body.append(host);
+
+            applyAdwaitaAccent('blue', { target: host, dark: true });
+            expect(property(host, ACCENT_PROPERTY)).toBe(ACCENT_COLOR_VECTORS[0].standaloneDark);
+
+            host.remove();
+        });
+
+        await it('clearing restores the stylesheet value instead of leaving the override', async () => {
+            const host = document.createElement('div');
+            host.className = 'theme-light';
+            document.body.append(host);
+
+            applyAdwaitaAccent('red', { target: host });
+            expect(property(host, ACCENT_BG_PROPERTY)).toBe(ACCENT_COLOR_VECTORS[5].background);
+
+            clearAdwaitaAccent(host);
+            // Back to whatever the cascade says — which is NOT red.
+            expect(property(host, ACCENT_BG_PROPERTY)).not.toBe(ACCENT_COLOR_VECTORS[5].background);
+
+            host.remove();
+        });
+    });
+};

package/src/index.ts

@@ -23,6 +23,17 @@ if (typeof document !== 'undefined' && !document.getElementById('adwaita-web-sty
 // `AdwBreakpoint`, and the `breakpoint="…"` attribute wiring the split views use.
 export { addBreakpoints, bindBreakpointSetter } from './breakpoints.js';
 
+// The accent palette and its OkLab standalone derivation are
+// `@gjsify/adwaita-core`'s; this is the browser half that puts them in the cascade.
+export {
+    ACCENT_BG_PROPERTY,
+    ACCENT_PROPERTY,
+    applyAdwaitaAccent,
+    clearAdwaitaAccent,
+    isAdwaitaDark,
+} from './accent.js';
+export type { ApplyAccentOptions } from './accent.js';
+
 export { AdwAvatar } from './elements/adw-avatar.js';
 export { AdwBanner } from './elements/adw-banner.js';
 export { AdwCard } from './elements/adw-card.js';