@gjsify/adwaita-web 0.35.0 → 0.37.0

package/src/adw-checks.spec.ts

@@ -1,17 +1,15 @@
 // DOM-level tests for <adw-checkbox> and <adw-radio>, plus the browser side of
 // the `RADIO_GROUP_VECTORS` conformance table.
 //
-// THE ONE CLAIM WORTH THE MOST HERE: the browser's native radio exclusivity is
-// NOT enough. `<input type="radio" name="g">` unchecks its sibling INPUT and
-// stops there — the sibling `<adw-radio>` HOST keeps its `checked` attribute,
-// which is the element's published state AND the selector `_checks.scss` paints
-// from, so a group left to the browser draws two selected radios. Every vector
-// below reads back the HOST attribute of every member for exactly that reason.
+// The browser's native radio exclusivity is NOT enough: `<input type="radio" name="g">`
+// unchecks its sibling INPUT and stops there, while the sibling `<adw-radio>` HOST keeps
+// its `checked` attribute — the element's published state and the selector
+// `_checks.scss` paints from — so a group left to the browser draws two selected radios.
+// Every vector below reads back the HOST attribute of every member for that reason.
 //
-// The vectors run under a per-scenario group-name prefix: `RadioGroupState` is
-// document-global by design (as a bare `<input type=radio name=x>` outside a
-// form is), so two scenarios sharing the literal name `colour` would share a
-// selection. The prefix is the isolation, not a change to what is being tested.
+// The vectors run under a per-scenario group-name prefix because `RadioGroupState` is
+// document-global by design (as a bare `<input type=radio name=x>` outside a form is),
+// so two scenarios sharing the literal name `colour` would share a selection.
 
 import { describe, expect, it } from '@gjsify/unit';
 import { RADIO_GROUP_VECTORS } from '@gjsify/adwaita-core/conformance';
@@ -60,12 +58,11 @@ export const AdwChecksTest = async () => {
             expect(input).toBeTruthy();
             expect(input.type).toBe('checkbox');
             expect(indicator).toBeTruthy();
-            // The focus ring is `input:focus-visible ~ .adw-check-indicator`, so
-            // the input MUST precede the indicator.
+            // The focus ring is `input:focus-visible ~ .adw-check-indicator`, so the
+            // input MUST precede the indicator.
             expect(input.nextElementSibling).toBe(indicator);
             expect(el.checked).toBe(false);
             expect(input.getAttribute('aria-checked')).toBe('false');
-            // An empty label takes no space.
             expect(label.hidden).toBe(true);
             parent.remove();
         });
@@ -110,9 +107,8 @@ export const AdwChecksTest = async () => {
         });
 
         await it('a click on the hidden input toggles exactly once', () => {
-            // The input is 0x0 so a pointer never reaches it, but keyboard
-            // activation and `input.click()` do — and the host listener must not
-            // toggle a second time on the way out.
+            // The input is 0x0 so a pointer never reaches it, but keyboard activation and
+            // `input.click()` do — and the host listener must not toggle a second time.
             const { el, parent } = mountCheckbox();
             const events = record(el, 'notify::checked');
             parts(el).input.click();
@@ -143,18 +139,17 @@ export const AdwChecksTest = async () => {
             el.checked = true;
             el.indeterminate = true;
             const { input } = parts(el);
-            // HTML has a native mixed CHECKBOX, and an explicit aria-checked so
-            // the radio (which has no native mixed) reads the same way.
+            // HTML has a native mixed CHECKBOX; the radio has none, so an explicit
+            // aria-checked makes it read the same way.
             expect(input.indeterminate).toBe(true);
             expect(input.getAttribute('aria-checked')).toBe('mixed');
             parent.remove();
         });
 
         await it('draws the dash even when also checked', () => {
-            // `check, radio { &:indeterminate { … dash.svg } }`
-            // (_checks.scss:79-81) is re-declared AFTER both `:checked` rules at
-            // equal specificity, so the dash wins. Comparing the three states
-            // against each other proves the cascade, not just that a mask exists.
+            // In `_checks.scss` the `:indeterminate` glyph is re-declared AFTER both
+            // `:checked` rules at equal specificity, so the dash wins. Comparing all
+            // three states proves the cascade, not just that a mask exists.
             const parent = host();
             const make = (attrs: string[]) => {
                 const el = document.createElement('adw-checkbox') as AdwCheckbox;
@@ -173,7 +168,7 @@ export const AdwChecksTest = async () => {
 
         await it('activating an indeterminate checkbox clears it and checks', () => {
             // HTML's pre-click activation steps, not a reading of
-            // GtkCheckButton:inconsistent — GTK's is not verifiable in this tree.
+            // GtkCheckButton:inconsistent, which is not verifiable in this tree.
             const { el, parent } = mountCheckbox();
             el.indeterminate = true;
             el.click();
@@ -192,33 +187,31 @@ export const AdwChecksTest = async () => {
 
             for (const el of [check, radio]) {
                 const style = getComputedStyle(parts(el).indicator);
-                // GTK sizes the CONTENT box at 14px and grows the drawn control
-                // with `padding: 3px` (_checks.scss:22-26) — content-box, not
-                // the ADR-0010 descendant border-box pin.
+                // GTK sizes the CONTENT box at 14px and grows the drawn control with
+                // `padding: 3px` — content-box, not the ADR-0010 border-box pin.
                 expect(style.width).toBe('14px');
                 expect(style.height).toBe('14px');
                 expect(style.paddingTop).toBe('3px');
             }
 
-            // `check { border-radius: 6px }` (:67-68) vs
-            // `radio { border-radius: 100% }` (:73-74).
+            // `check { border-radius: 6px }` vs
+            // `radio { border-radius: 100% }`.
             expect(getComputedStyle(parts(check).indicator).borderTopLeftRadius).toBe('6px');
             expect(getComputedStyle(parts(radio).indicator).borderTopLeftRadius).toContain('%');
             parent.remove();
         });
 
         await it('a checked radio FILLS, with the SAME accent background as a checked check', () => {
-            // refs/adwaita-web's `_radio.scss:22-33` colours only the border and
-            // the dot, leaving the indicator on the view background; libadwaita
-            // fills the whole control from the block it SHARES with the checkbox
-            // (:52-60). libadwaita wins — so the two fills must be identical.
+            // refs/adwaita-web's `_radio.scss` colours only the border and the dot,
+            // leaving the indicator on the view background; libadwaita fills the whole
+            // control from the block it SHARES with the checkbox, and libadwaita wins —
+            // so the two fills must be identical.
             //
-            // THREE elements rather than one flipped in place: the indicator
-            // TRANSITIONS `background`, so a computed read taken right after
-            // `checked = true` returns the INTERPOLATED colour — still the old
-            // one. Declaring the state before insertion leaves no transition to
-            // be part-way through. The names are distinct so seeding one group
-            // cannot reach the reference radio.
+            // THREE elements rather than one flipped in place: the indicator TRANSITIONS
+            // `background`, so a computed read right after `checked = true` returns the
+            // INTERPOLATED colour. Declaring the state before insertion leaves no
+            // transition part-way through, and distinct names keep seeding one group from
+            // reaching the reference radio.
             const parent = host();
             const plain = document.createElement('adw-radio') as AdwRadio;
             plain.setAttribute('name', 'fill-plain');
@@ -243,8 +236,6 @@ export const AdwChecksTest = async () => {
         for (const [index, vector] of RADIO_GROUP_VECTORS.entries()) {
             await it(`${vector.name} — ${vector.rule}`, () => {
                 const parent = host();
-                // Per-scenario prefix: the registry is document-global, so two
-                // scenarios sharing a literal group name would share a selection.
                 const scope = (name: string) => `v${index}-${name}`;
 
                 const members = vector.members.map(([name, value]) => {
@@ -272,9 +263,8 @@ export const AdwChecksTest = async () => {
                     expect(parts(el).input.checked).toBe(shouldHold);
                 }
 
-                // Every emitted change repaints the winner, and the loser too
-                // when there was one — that second repaint is the whole reason
-                // the group state exists.
+                // Every emitted change repaints the winner AND the loser when there was
+                // one; that second repaint is why the group state exists.
                 const expectedEvents = vector.emitted.reduce(
                     (total, change) => total + (change.deselected === null ? 1 : 2),
                     0,
@@ -327,10 +317,9 @@ export const AdwChecksTest = async () => {
         });
 
         await it('a NAMELESS radio is not in a group', () => {
-            // HTML forms a radio button group only from a non-empty `name`.
-            // Without that rule every nameless radio in the document would land
-            // in one `''` group and fight over it — which is exactly what a
-            // registry keyed by name does if nothing guards the empty key.
+            // HTML forms a radio group only from a non-empty `name`; without that rule
+            // every nameless radio lands in one `''` group and fights over it, which is
+            // what a registry keyed by name does unless it guards the empty key.
             const parent = host();
             const first = document.createElement('adw-radio') as AdwRadio;
             const second = document.createElement('adw-radio') as AdwRadio;

package/src/adw-drop-down.spec.ts

@@ -1,17 +1,14 @@
-// DOM-level behaviour tests for <adw-drop-down>. Runs in a real browser via the
-// @gjsify/adwaita-web browser test axis. Asserts option parsing, selected↔value
-// sync, notify-on-change semantics, popover open/close, item selection, search
-// filtering and the disabled guard.
+// DOM-level behaviour tests for <adw-drop-down>, in a real browser via the
+// @gjsify/adwaita-web browser test axis.
 //
-// The SELECTION half is driven by the SAME table the NativeScript renderer
-// asserts against (`COMBO_SELECTION_VECTORS`, `@gjsify/adwaita-core/conformance`)
-// — replayed against the real element through the API a consumer would use, and
-// read back as what a user would see: the button label, `selected`/`selectedValue`
-// and the `change` stream. `<adw-combo-row>` composes the same `ComboState` but
-// cannot drive the table, because two of its four step ops have no DOM spelling:
-// its options come from the `items` attribute at connect time only (`items` is not
-// even observed), and it publishes no select-by-value setter. So this element is
-// the browser's driver for both.
+// The SELECTION half is driven by the SAME table the NativeScript renderer asserts
+// against (`COMBO_SELECTION_VECTORS`, `@gjsify/adwaita-core/conformance`), replayed
+// through the API a consumer would use and read back as what a user would see: the
+// button label, `selected`/`selectedValue` and the `change` stream. `<adw-combo-row>`
+// composes the same `ComboState` but cannot drive the table — two of its four step ops
+// have no DOM spelling, since its options come from the `items` attribute at connect
+// time only (`items` is not observed) and it publishes no select-by-value setter. So
+// this element is the browser's driver for both.
 import { describe, it, expect } from '@gjsify/unit';
 
 import { COMBO_SELECTION_VECTORS } from '@gjsify/adwaita-core/conformance';
@@ -53,9 +50,8 @@ function applyStep(dd: AdwDropDown, step: ComboSelectionStep): void {
         case 'select':
             openChooser(dd);
             if (step.index < 0) {
-                // The dismissed chooser: the popover closes with nothing picked,
-                // which here is an outside pointerdown rather than a cancelled
-                // native sheet.
+                // The dismissed chooser: the popover closes with nothing picked — here an
+                // outside pointerdown rather than a cancelled native sheet.
                 document.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true }));
                 return;
             }
@@ -65,13 +61,12 @@ function applyStep(dd: AdwDropDown, step: ComboSelectionStep): void {
 }
 
 /**
- * The ONE row this element answers differently, and does so on purpose: its
- * published `selected` contract REJECTS an out-of-range set (`_selectIndex` gates
- * on `ComboState.hasIndex`), where the core state accepts it and reports an empty
- * value — the split `ComboState.hasIndex`'s doc comment records and
- * `<adw-combo-row>` takes the other side of. The row is still driven below,
- * against the element's answer rather than the state's, so neither policy can
- * change silently.
+ * The ONE row this element answers differently, on purpose: its published `selected`
+ * contract REJECTS an out-of-range set (`_selectIndex` gates on `ComboState.hasIndex`)
+ * where the core state accepts it and reports an empty value — the split
+ * `ComboState.hasIndex`'s doc records and `<adw-combo-row>` takes the other side of. The
+ * row is still driven below, against the element's answer, so neither policy can change
+ * silently.
  */
 const DROP_DOWN_REJECTS = 'an index past the end';
 
@@ -102,10 +97,9 @@ export const AdwDropDownTest = async () => {
                 expect(dd.selected).toBe(vector.selected);
                 expect(dd.selectedValue).toBe(vector.value);
                 expect(labelText(dd)).toBe(vector.label);
-                // `change` is this element's DOM spelling of the `interactive`
-                // flag: it fires for a user pick and never for a programmatic
-                // set, so the interactive frames of the emission stream ARE the
-                // events a listener sees.
+                // `change` is this element's DOM spelling of the `interactive` flag: it
+                // fires for a user pick and never for a programmatic set, so the
+                // interactive frames of the stream ARE the events a listener sees.
                 expect(changes).toStrictEqual(
                     vector.emitted
                         .filter((change) => change.interactive)
@@ -119,11 +113,10 @@ export const AdwDropDownTest = async () => {
             const vector = vectorNamed(DROP_DOWN_REJECTS);
             const { dd, changes } = mountRecording();
 
-            // Everything up to the out-of-range set…
             for (const step of vector.steps.slice(0, -1)) applyStep(dd, step);
             const before = { selected: dd.selected, value: dd.selectedValue, label: labelText(dd) };
-            // …and then the set itself, which the core state would accept and
-            // report as nothing-to-draw (`value`/`label` both empty below).
+            // The out-of-range set itself, which the core state would accept and report
+            // as nothing-to-draw (`value`/`label` both empty below).
             expect(vector.value).toBe('');
             expect(vector.label).toBe('');
             applyStep(dd, vector.steps[vector.steps.length - 1]);
@@ -210,8 +203,8 @@ export const AdwDropDownTest = async () => {
         });
 
         await it('setting options + selected before connect does not crash + applies on connect', async () => {
-            // Regression: the property setters ran before connectedCallback built
-            // the DOM, so _updateLabel touched an undefined label element.
+            // The property setters can run BEFORE connectedCallback builds the DOM, where
+            // _updateLabel would touch an undefined label element.
             const dd = document.createElement('adw-drop-down') as AdwDropDown;
             dd.options = ['a', 'b', 'c'];
             dd.selected = 2;

package/src/adw-header-bar.spec.ts

@@ -1,14 +1,12 @@
 // DOM-level tests for <adw-header-bar>'s title.
 //
-// `title` was read exactly once, in `connectedCallback`, and the element declared
-// no `observedAttributes` at all — so every later write was a silent no-op. A
-// header bar whose title tracks the open document kept whatever it was created
-// with, and nothing in the build was in a position to notice: the attribute was
-// still THERE, and the element still rendered A title.
+// `title` must be OBSERVED, not read once at `connectedCallback`: a header bar tracking
+// the open document keeps its construction-time title otherwise, and nothing notices
+// because the attribute is still there and A title still renders.
 //
 // `Adw.HeaderBar` builds its centre from `title`/`subtitle` through a derived
-// `AdwWindowTitle` bound to the properties, unless a `title-widget` replaces it
-// — which is the either/or the `slot="center"` case below asserts.
+// `AdwWindowTitle` bound to the properties, unless a `title-widget` replaces it — the
+// either/or the `slot="center"` case below asserts.
 
 import { describe, expect, it } from '@gjsify/unit';
 

package/src/adw-icon.spec.ts

@@ -1,16 +1,11 @@
-// DOM-level tests for <adw-icon>, driven by the SAME `normalizeIconName` vectors
-// the core suite asserts against (`@gjsify/adwaita-core/conformance`), plus the
-// REGRESSION PROOF for the drift the element was extracted to close.
+// DOM-level tests for <adw-icon>, driven by the SAME `normalizeIconName` vectors the
+// core suite asserts against (`@gjsify/adwaita-core/conformance`).
 //
-// The drift: `<span class="adw-icon adw-icon--<name>" aria-hidden="true">` was
-// built by hand at twenty-three sites across seventeen files, nine of them
-// re-deriving `name.replace(/-symbolic$/, '')` on the spot. Exactly ONE site —
-// `<adw-split-button>` — also checked the result was a single CSS token. So
-// `icon-name="a b"` interpolated into `class="adw-icon adw-icon--a b"` and shipped
-// a stray `b` class through `<adw-menu-button>`, for its own icon AND for every
-// JSON menu entry's, while the one element that guarded kept passing its spec.
-// The vectors below now run against the ELEMENT, so a renderer that starts
-// building the class by hand again fails naming the input.
+// The icon-name class must never be built by hand: a name is only usable once it is
+// known to be a SINGLE CSS token, and hand-built spans skipped that check, so
+// `icon-name="a b"` interpolated a stray second class and shipped it through
+// `<adw-menu-button>` for its own icon and for every JSON menu entry's. The vectors run
+// against the ELEMENT, so hand-building the class again fails naming the input.
 import { describe, expect, it } from '@gjsify/unit';
 
 import { VIEW_STACK_ICON_NAME_VECTORS } from '@gjsify/adwaita-core/conformance';
@@ -39,13 +34,11 @@ export const AdwIconTest = async () => {
                 el.iconName = icon ?? null;
 
                 expect(el.resolvedIconName).toBe(normalized);
-                // The base class is unconditional — a nameless icon is still an
-                // icon box, which is what `<adw-status-page>` hides rather than
-                // omits.
+                // The base class is unconditional: a nameless icon is still an icon box,
+                // which `<adw-status-page>` hides rather than omits.
                 expect(el.classList.contains('adw-icon')).toBe(true);
-                // …and NOTHING else is on the node. This is the assertion the
-                // hand-rolled copies could not make: `icon-name="a b"` used to
-                // leave a stray `b` here.
+                // …and NOTHING else is on the node — the assertion a hand-rolled copy
+                // cannot make, where `icon-name="a b"` leaves a stray `b`.
                 expect(extraClasses(el)).toStrictEqual(normalized === '' ? [] : [`adw-icon--${normalized}`]);
                 host.remove();
             });
@@ -66,8 +59,8 @@ export const AdwIconTest = async () => {
             expect(extraClasses(el)).toStrictEqual(['adw-drop-down-arrow', 'adw-icon--go-down', 'start']);
 
             el.iconName = 'go-next';
-            // Exactly one mask class at a time, and the caller's are untouched —
-            // a `className =` assignment would have taken them with it.
+            // Exactly one mask class at a time, and the caller's are untouched: a
+            // `className =` assignment would take them with it.
             expect(extraClasses(el)).toStrictEqual(['adw-drop-down-arrow', 'adw-icon--go-next', 'start']);
 
             el.iconName = null;
@@ -86,10 +79,9 @@ export const AdwIconTest = async () => {
             const styled = getComputedStyle(el);
             expect(styled.width).toBe('32px');
             expect(styled.height).toBe('32px');
-            // Sizing only the box would leave a 16px glyph floating in it. Only
-            // the axis we set is asserted: `mask-size: 32px` means "32px wide,
-            // height from the aspect ratio", and the CSSOM re-serializes the
-            // omitted half (Firefox reports `32px auto`, in the inline style too).
+            // Sizing only the box leaves a 16px glyph floating in it. Only the axis set is
+            // asserted: `mask-size: 32px` means "32px wide, height from the aspect ratio",
+            // and the CSSOM re-serializes the omitted half (Firefox reports `32px auto`).
             expect(styled.maskSize.split(' ')[0]).toBe('32px');
             expect(styled.webkitMaskSize.split(' ')[0]).toBe('32px');
 
@@ -99,10 +91,10 @@ export const AdwIconTest = async () => {
         });
 
         await it('paints in the INHERITED colour, not the boundary reset colour', () => {
-            // `.adw-icon` masks with `currentColor`, and <adw-icon> is a custom
-            // element — so the ADR-0010 `$adw-components` reset re-roots `color`
-            // on it. Without `color: inherit` in `_icon.scss` every icon would
-            // repaint in `--window-fg-color` regardless of the button it sits in.
+            // `.adw-icon` masks with `currentColor` and <adw-icon> is a custom element, so
+            // the ADR-0010 `$adw-components` reset re-roots `color` on it: without
+            // `color: inherit` in `_icon.scss` every icon repaints in `--window-fg-color`
+            // regardless of the button it sits in.
             const { el: box, host } = mount<HTMLElement>('div');
             box.style.color = 'rgb(255, 0, 0)';
             const icon = document.createElement('adw-icon') as AdwIcon;
@@ -142,10 +134,9 @@ export const AdwIconTest = async () => {
         });
 
         await it('every icon in the package is an <adw-icon>', () => {
-            // The point of the extraction, asserted structurally: build a page of
-            // the widgets that draw icons and check no bare span carries the
-            // base class. A new hand-rolled `<span class="adw-icon …">` fails
-            // here even if it happens to guard its own name correctly.
+            // Asserted structurally: a page of every icon-drawing widget, and no bare span
+            // carrying the base class — so a new hand-rolled `<span class="adw-icon …">`
+            // fails here even when it guards its own name correctly.
             const { el: page, host } = mount<HTMLElement>('div');
             page.innerHTML = `
                 <adw-button icon="go-next" label="Next"></adw-button>

package/src/adw-progress-bar.spec.ts

@@ -1,13 +1,11 @@
 // DOM-level tests for <adw-progress-bar>.
 //
-// Three things here are worth more than the attribute round-trips: the CLAMP is
-// GLib's (`glibClamp`, shared from `@gjsify/adwaita-core`, not a local
-// `Math.min/max`), the ZERO fraction has to make the indicator VANISH rather
-// than draw a rounded stub (`> trough.empty > progress { all: unset }`,
-// _progress-bar.scss:85), and the text node has to actually PICK UP `.dimmed` +
-// `.numeric` from `_labels.scss` — that composition is the reason those classes
-// exist, and a `@extend` that silently reached nothing would look identical in
-// the source.
+// Three things matter more than the attribute round-trips: the CLAMP is GLib's
+// (`glibClamp` from `@gjsify/adwaita-core`, not a local `Math.min/max`); a ZERO fraction
+// makes the indicator VANISH rather than draw a rounded stub
+// (`> trough.empty > progress { all: unset }` in `_progress-bar.scss`); and the text node
+// really PICKS UP `.dimmed` + `.numeric` from `_labels.scss` — a `@extend` that reached
+// nothing would look identical in the source.
 
 import { describe, expect, it } from '@gjsify/unit';
 
@@ -124,8 +122,8 @@ export const AdwProgressBarTest = async () => {
         });
 
         await it('the text node composes .dimmed and .numeric from _labels.scss', () => {
-            // `> text { @extend .dimmed; @extend .numeric; }`
-            // (_progress-bar.scss:17-21) — this asserts the extends actually
+            // `> text { @extend.dimmed; @extend.numeric; }`
+            // (_progress-bar.scss) — this asserts the extends actually
             // REACHED the utility classes, which a source read cannot tell.
             const { el, host } = mount();
             el.showText = true;
@@ -138,8 +136,8 @@ export const AdwProgressBarTest = async () => {
 
     await describe('<adw-progress-bar> variants', async () => {
         await it('is an 8px trough by default and a 2px hairline with osd', () => {
-            // The 8px is libadwaita's (_progress-bar.scss:6) and the 2px is its
-            // `.osd` variant (:59-83) — NOT the vendored web port's 6px, which
+            // The 8px is libadwaita's (_progress-bar.scss) and the 2px is its
+            // `.osd` variant — NOT the vendored web port's 6px, which
             // has no OSD variant at all.
             //
             // TWO bars rather than one flipped in place, on purpose: the trough

package/src/adw-row-state.spec.ts

@@ -85,15 +85,14 @@ export const AdwRowStateTest = async () => {
                 const value = row.querySelector('.adw-row-value') as HTMLSpanElement;
                 const select = row.querySelector('select') as HTMLSelectElement;
 
-                // The ARROW: `.adw-row-value::after` is masked in, and the
-                // `[data-presents-chooser='false']` block removes it. Asserted
-                // as "not none" rather than against the authored `inline-block`,
-                // because `.adw-row-value` is a flex container and blockifies
-                // its children's display.
+                // The ARROW: `.adw-row-value::after` is masked in and the
+                // `[data-presents-chooser='false']` block removes it. Asserted as "not
+                // none" rather than against the authored `inline-block`, because
+                // `.adw-row-value` is a flex container and blockifies its children.
                 expect(getComputedStyle(value, '::after').display === 'none').toBe(!presentsChooser);
-                // ...and the ROW being activatable, which on this port is the
-                // overlaid <select> taking clicks at all. Hiding the arrow
-                // without this leaves a row that still opens a one-entry popup.
+                // …and the ROW being activatable, which here is the overlaid <select>
+                // taking clicks at all: hiding the arrow alone leaves a row that still
+                // opens a one-entry popup.
                 expect(select.disabled).toBe(!presentsChooser);
 
                 host.remove();
@@ -108,8 +107,8 @@ export const AdwRowStateTest = async () => {
             const select = row.querySelector('select') as HTMLSelectElement;
             expect(select.disabled).toBe(true);
 
-            // `items` is read at connect only, so the model is replaced through
-            // the state the element composes — the same path a consumer has.
+            // `items` is read at connect only, so the model is replaced through the state
+            // the element composes — the same path a consumer has.
             (
                 row as unknown as { _state: { setOptions(o: { label: string; value: string }[]): void } }
             )._state.setOptions([

package/src/adw-shortcut-label.spec.ts

@@ -0,0 +1,112 @@
+// <adw-shortcut-label> against `SHORTCUT_LABEL_VECTORS` — the same table the
+// core suite drives, so a divergence between the parse and what this element
+// actually renders fails a test naming the accelerator.
+//
+// The serialiser below walks the REAL DOM and produces the table's compact form.
+// That is the whole point of the shared format: if this file built its own
+// expectation strings instead, the two suites could agree with each other while
+// both disagreeing with libadwaita.
+import { describe, expect, it } from '@gjsify/unit';
+import { SHORTCUT_LABEL_VECTORS } from '@gjsify/adwaita-core/conformance';
+
+import '@gjsify/adwaita-web';
+
+/** The rendered element in the table's compact form (see conformance/shortcut-label.ts). */
+const serialize = (host: HTMLElement): string =>
+    [...host.children]
+        .map((child) => {
+            if (child.classList.contains('adw-shortcut-label-disabled'))
+                return `(disabled: ${child.textContent ?? ''})`;
+            if (child.classList.contains('dimmed')) return child.textContent ?? '';
+
+            return [...child.children]
+                .map((cap) => {
+                    const side = cap.querySelector('.adw-shortcut-label-side');
+                    // The marker rides INSIDE the keycap, so its text has to come
+                    // back out of the label before the two are compared.
+                    const label = (cap.textContent ?? '').slice(
+                        0,
+                        (cap.textContent ?? '').length - (side?.textContent?.length ?? 0),
+                    );
+                    return `[${side ? `${label} (${side.textContent})` : label}]`;
+                })
+                .join('');
+        })
+        .join(' ')
+        .trim();
+
+export const AdwShortcutLabelTest = async () => {
+    await describe('<adw-shortcut-label> (conformance vectors)', async () => {
+        for (const vector of SHORTCUT_LABEL_VECTORS) {
+            // The Apple glyph set is a build constant in the C and an option in
+            // core; the ELEMENT reads its platform from nothing, so the two
+            // Apple rows have no element to drive. They stay core-only.
+            if (vector.platform === 'apple') continue;
+
+            await it(`${vector.accelerator || '(empty)'} — ${vector.rule}`, async () => {
+                const host = document.createElement('adw-shortcut-label');
+                host.setAttribute('accelerator', vector.accelerator);
+                if (vector.disabledText !== undefined) host.setAttribute('disabled-text', vector.disabledText);
+                // RTL comes from the rendered direction, so the vector's
+                // direction has to be a real attribute on a CONNECTED element.
+                if (vector.direction === 'rtl') host.setAttribute('dir', 'rtl');
+                document.body.appendChild(host);
+
+                expect(serialize(host)).toBe(vector.expected);
+                if (vector.accessibleLabel !== undefined) {
+                    expect(host.getAttribute('aria-label')).toBe(vector.accessibleLabel);
+                }
+
+                host.remove();
+            });
+        }
+
+        await it('re-renders when the accelerator changes', async () => {
+            const host = document.createElement('adw-shortcut-label');
+            host.setAttribute('accelerator', '<Control>C');
+            document.body.appendChild(host);
+
+            let notified = 0;
+            host.addEventListener('notify::accelerator', () => notified++);
+            host.setAttribute('accelerator', '<Control>V');
+
+            expect(serialize(host)).toBe('[Ctrl][V]');
+            expect(notified).toBe(1);
+
+            host.remove();
+        });
+
+        await it('draws the keycaps of one combination left-to-right inside an RTL context', async () => {
+            // `gtk_widget_set_direction (box, GTK_TEXT_DIR_LTR)` (:380): the
+            // modifier order belongs to the shortcut, not to the surrounding
+            // text — only the SEQUENCE arrow flips.
+            const host = document.createElement('adw-shortcut-label');
+            host.setAttribute('dir', 'rtl');
+            host.setAttribute('accelerator', '<Control>C+<Control>X');
+            document.body.appendChild(host);
+
+            const box = host.querySelector<HTMLElement>('.adw-shortcut-label-keys');
+            expect(box?.getAttribute('dir')).toBe('ltr');
+            expect(getComputedStyle(box as HTMLElement).direction).toBe('ltr');
+            expect(host.querySelector('.dimmed')?.textContent).toBe('←');
+
+            host.remove();
+        });
+
+        await it('gives its keycaps the styling libadwaita gives them', async () => {
+            // The rule exists, and it reaches the node the element builds — the
+            // half a class-name assertion cannot see (`_shortcuts-dialog.scss:42-53`).
+            const host = document.createElement('adw-shortcut-label');
+            host.setAttribute('accelerator', '<Control>C');
+            document.body.appendChild(host);
+
+            const cap = host.querySelector<HTMLElement>('.keycap');
+            const style = getComputedStyle(cap as HTMLElement);
+            expect(style.borderTopLeftRadius).toBe('6px');
+            expect(style.paddingTop).toBe('6px');
+            expect(Number.parseFloat(style.minWidth)).toBe(20);
+
+            host.remove();
+        });
+    });
+};