@gjsify/adwaita-web 0.36.0 → 0.37.0

package/src/style-classes.spec.ts

@@ -0,0 +1,181 @@
+// libadwaita's DOCUMENTED style-class surface, held against the compiled
+// stylesheet.
+//
+// THE INCIDENT
+//
+// `refs/libadwaita/doc/style-classes.md` is the contract an app author reads:
+// `.card` on a box, `.boxed-list` on a list, `.toolbar` on a bar, `.linked`
+// around a button group. Twenty-one of those classes had no rule in this package
+// at all (#1049) — a consumer following the upstream documentation got nothing,
+// silently.
+//
+// WHY THIS READS THE COMPILED CSS AND NOT THE SCSS
+//
+// A source grep cannot answer the question, and got it wrong in both directions:
+//
+//   - `.osd` and `.linked` appeared in `scss/` only inside COMMENTS, so a text
+//     search reported them as present while the code spelled its own
+//     `.adw-linked` and shipped no `.osd` at all.
+//   - `.error` / `.warning` / `.success` are generated by an `@each` in
+//     `_labels.scss` (`.#{$e_type}`), so they appear in no source text at all and
+//     a text search reports them missing.
+//
+// The compiled stylesheet is what a consumer actually loads, so that is what is
+// asserted. `:not(…)` is stripped before matching, because a selector mentioning
+// a class in order to EXCLUDE it (`.toolbar … :not(.opaque)`) is the opposite of
+// shipping it.
+//
+// THE LEDGER IS THE POINT
+//
+// Every documented class has an entry, and a class that is NOT shipped must say
+// why — so the next reader sees the difference between "we decided against it"
+// and "nobody noticed". `scripts/check-adwaita-style-classes.mjs` holds this
+// ledger against the upstream document itself, so a libadwaita bump that adds a
+// class cannot leave the ledger silently short.
+//
+// Reference: refs/libadwaita/doc/style-classes.md
+import { describe, expect, it } from '@gjsify/unit';
+
+import { ADWAITA_WEB_CSS } from './styles.generated.js';
+
+/** Ships a rule in the compiled stylesheet. */
+const SHIPPED = { shipped: true } as const;
+
+/** Deprecated upstream, with a named replacement — deliberately not ported. */
+const deprecated = (replacement: string) =>
+    ({ shipped: false, reason: `deprecated upstream — use ${replacement}` }) as const;
+
+/** No counterpart in this renderer (yet), with the reason. */
+const unported = (reason: string) => ({ shipped: false, reason }) as const;
+
+/**
+ * Every class `style-classes.md` documents, and what this package does about it.
+ *
+ * Keys are the bare class names, in the document's own spelling. The order is
+ * the document's, so the two can be read side by side.
+ */
+export const DOCUMENTED_STYLE_CLASSES: Record<string, { shipped: boolean; reason?: string }> = {
+    // Buttons
+    'suggested-action': SHIPPED,
+    'destructive-action': SHIPPED,
+    flat: SHIPPED,
+    raised: SHIPPED,
+    circular: SHIPPED,
+    pill: SHIPPED,
+    // Toggle groups
+    round: SHIPPED,
+    // Linked controls
+    linked: SHIPPED,
+    // Toolbars + spacers
+    toolbar: SHIPPED,
+    spacer: SHIPPED,
+    // Dimmed + typography
+    dimmed: SHIPPED,
+    'title-1': SHIPPED,
+    'title-2': SHIPPED,
+    'title-3': SHIPPED,
+    'title-4': SHIPPED,
+    heading: SHIPPED,
+    document: SHIPPED,
+    body: SHIPPED,
+    caption: SHIPPED,
+    'caption-heading': SHIPPED,
+    monospace: SHIPPED,
+    numeric: SHIPPED,
+    // Colors
+    error: SHIPPED,
+    warning: SHIPPED,
+    success: SHIPPED,
+    // Boxed lists & cards
+    'boxed-list': SHIPPED,
+    'boxed-list-separate': SHIPPED,
+    card: SHIPPED,
+    activatable: SHIPPED,
+    // Sidebars
+    'navigation-sidebar': SHIPPED,
+    // App icons
+    'lowres-icon': SHIPPED,
+    'icon-dropshadow': SHIPPED,
+    // Selection mode
+    'selection-mode': SHIPPED,
+    // OSD
+    osd: SHIPPED,
+    // Surfaces
+    background: SHIPPED,
+    view: SHIPPED,
+    frame: SHIPPED,
+    // Compact status page
+    compact: SHIPPED,
+    // Menu popovers
+    menu: SHIPPED,
+    // Development window
+    devel: SHIPPED,
+    // Inline
+    inline: unported(
+        'applies to GtkSearchBar, AdwTabBar and GtkTextView. This renderer ports none of ' +
+            'the three — <adw-tab-view> is the tab CONTENT, not AdwTabBar — and upstream ' +
+            'excludes GtkSourceView, which is the one text widget here (<adw-source-view>). ' +
+            'The class ships with the first of those three widgets, not before.',
+    ),
+    // Undershoot indicators
+    'undershoot-top': SHIPPED,
+    'undershoot-bottom': SHIPPED,
+    'undershoot-start': SHIPPED,
+    'undershoot-end': SHIPPED,
+    // Property rows
+    property: SHIPPED,
+    // Deprecated
+    content: deprecated('.boxed-list, which upstream calls completely equivalent'),
+    sidebar: deprecated('.navigation-sidebar plus a separator for the border'),
+    'app-notification': deprecated('<adw-toast-overlay>'),
+    'large-title': deprecated('.title-1'),
+    opaque: deprecated('.suggested-action with the accent tokens overridden'),
+    'dim-label': deprecated('.dimmed'),
+};
+
+/**
+ * Selector text of every rule in the stylesheet, with `:not(…)` removed.
+ *
+ * Matching against selectors rather than the whole file keeps a class name in a
+ * comment or in a `content:` string from counting as a rule.
+ */
+const selectorText = (css: string): string =>
+    [...css.matchAll(/(?:^|\}|\*\/)([^{}]+)\{/g)].map((match) => match[1].replace(/:not\([^)]*\)/g, '')).join('\n');
+
+const definesClass = (selectors: string, name: string): boolean =>
+    new RegExp(`\\.${name.replace(/-/g, '\\-')}(?![-\\w])`).test(selectors);
+
+export const AdwStyleClassesTest = async () => {
+    await describe('documented style classes', async () => {
+        const selectors = selectorText(ADWAITA_WEB_CSS);
+
+        await it('ships a rule for every class libadwaita documents', async () => {
+            const missing = Object.entries(DOCUMENTED_STYLE_CLASSES)
+                .filter(([, entry]) => entry.shipped)
+                .map(([name]) => name)
+                .filter((name) => !definesClass(selectors, name));
+
+            // Named in the failure so the message says WHICH contract broke.
+            expect(missing.join(', ')).toBe('');
+        });
+
+        await it('keeps the ledger honest about the ones it does not ship', async () => {
+            // The reverse direction: a class that quietly gained a rule must move
+            // to SHIPPED, or the reason next to it is now a lie. Every non-shipped
+            // entry also has to carry that reason.
+            const unexpected = Object.entries(DOCUMENTED_STYLE_CLASSES)
+                .filter(([, entry]) => !entry.shipped)
+                .filter(([name, entry]) => definesClass(selectors, name) || !entry.reason)
+                .map(([name]) => name);
+
+            expect(unexpected.join(', ')).toBe('');
+        });
+
+        await it('is a real stylesheet and not an empty string', async () => {
+            // The two assertions above both pass vacuously against an empty CSS
+            // bundle — a stale or unbuilt `styles.generated.ts` would read as a
+            // clean bill of health.
+            expect(selectors.length > 10_000).toBe(true);
+        });
+    });
+};

package/src/style-isolation.spec.ts

@@ -1,14 +1,11 @@
-// Style-isolation regression test (browser axis). Guards the boundary reset
-// (scss/_reset.scss, ADR 0010): a host page's inherited typography must not leak
-// into an adwaita-web widget. It also guards that the widget's tag is listed in
-// the reset's `$adw-components` — if it weren't, the reset wouldn't apply and
-// these assertions would fail.
+// The boundary reset (scss/_reset.scss, ADR 0010): a host page's inherited typography must
+// not leak into an adwaita-web widget. Also guards that the widget's tag is listed in the
+// reset's `$adw-components` — without it the reset would not apply and these fail.
 import { describe, expect, it } from '@gjsify/unit';
 
 export const AdwStyleIsolationTest = async () => {
     await describe('style isolation (boundary reset)', async () => {
         await it('re-roots typography so a host font does not inherit into a widget', async () => {
-            // A container styled like a hostile host theme.
             const host = document.createElement('div');
             host.style.fontFamily = 'Georgia, "Times New Roman", serif';
             host.style.color = 'rgb(255, 0, 255)';