@gjsify/adwaita-web 0.31.0 → 0.33.0

package/src/elements/adw-wrap-box.ts

@@ -1,70 +1,274 @@
 // <adw-wrap-box> — A box-like container that lays its children out in a line and
-// wraps them onto new lines when they run out of room (the web analog of
-// flexbox `flex-wrap: wrap` with a gap). Mirrors Adw.WrapBox.
-// Attributes:
-//   child-spacing   (px, default 0) — spacing between children on the same line
-//                                      → CSS column-gap
-//   line-spacing    (px, default 0) — spacing between lines → CSS row-gap
-//   orientation     ("horizontal" | "vertical", default "horizontal") — the main
-//                                      axis children are packed along
-//   align           (0..1, default 0) — alignment of children within each line
-//                                      (cross axis); 0 = start, 0.5 = center, 1 = end
-//   justify         ("none" | "fill" | "spread", default "none") — whether/how
-//                                      each line is stretched to fill the widget
-//   justify-last-line (boolean) — also justify the last (incomplete) line
-//   line-homogeneous  (boolean) — make every line take the same amount of space
-//   pack-direction  ("start-to-end" | "end-to-start", default "start-to-end") —
-//                                      direction children are packed within a line
-//   wrap-reverse    (boolean) — reverse the wrap direction (lines wrap upwards)
-// Events: notify::child-spacing, notify::line-spacing (CustomEvent, bubbles —
-//   mirrors GObject signal naming).
+// wraps them onto new lines when they run out of room (the web analog of flexbox
+// `flex-wrap: wrap` with a gap). Mirrors Adw.WrapBox.
+//
+// Attributes — all fourteen of the widget's properties, each with a
+// `notify::<property>` (adw-wrap-box.c:284-497). The element used to carry nine
+// attributes and notify for two, so a consumer binding to any of the other
+// twelve was listening to a signal that could not fire.
+//
+//   child-spacing / line-spacing        (int >= 0, default 0) -> column-gap / row-gap
+//   child-spacing-unit / line-spacing-unit ("px" | "pt" | "sp", default "px")
+//   orientation      ("horizontal" | "vertical", default "horizontal")
+//   pack-direction   ("start-to-end" | "end-to-start", default "start-to-end")
+//   align            (0..1, default 0) — MAIN-axis offset of the whole line block
+//   justify          ("none" | "fill" | "spread", default "none")
+//   justify-last-line (boolean)
+//   line-homogeneous  (boolean)
+//   wrap-reverse      (boolean)
+//   wrap-policy      ("minimum" | "natural", default "natural")
+//   natural-line-length (int >= -1, default -1 = unset) + -unit
+//
+// The property CONTRACT — the normalisers and the justify/align/last-line
+// decision — is `@gjsify/adwaita-core`'s `wrap-box.ts`, held to
+// `WRAP_BOX_LINE_VECTORS` and friends, which the NativeScript suite drives too.
+// This element used to carry its own copy of all of it.
+//
 // Reference: refs/libadwaita/src/adw-wrap-box.c / adw-wrap-layout.c (Adw.WrapBox)
 // Reference: refs/adwaita-web/adwaita-web/scss/_wrap_box.scss
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
-/** Adw.JustifyMode → flexbox justify-content. */
-const JUSTIFY_MAP: Record<string, string> = {
-    none: 'flex-start',
-    fill: 'space-between',
-    spread: 'space-between',
-};
+import {
+    ADW_WRAP_BOX_NATURAL_LINE_LENGTH_UNSET,
+    normalizeNaturalLineLength,
+    normalizeWrapBoxAlign,
+    normalizeWrapBoxJustify,
+    normalizeWrapBoxLengthUnit,
+    normalizeWrapBoxPackDirection,
+    normalizeWrapBoxSpacing,
+    normalizeWrapPolicy,
+    resolveWrapBoxChildOrder,
+    resolveWrapBoxLine,
+    wrapBoxLengthToPx,
+    wrapPolicyFlexShrink,
+    type AdwLengthUnit,
+} from '@gjsify/adwaita-core';
+
+/**
+ * The attributes that carry a property, in the order the C installs them.
+ *
+ * Doubles as the `notify::` roster: every entry gets an event on a real change,
+ * so adding an attribute without its notification is not expressible here.
+ */
+const PROPERTY_ATTRIBUTES = [
+    'child-spacing',
+    'child-spacing-unit',
+    'pack-direction',
+    'align',
+    'justify',
+    'justify-last-line',
+    'line-spacing',
+    'line-spacing-unit',
+    'line-homogeneous',
+    'natural-line-length',
+    'natural-line-length-unit',
+    'wrap-reverse',
+    'wrap-policy',
+    'orientation',
+] as const;
+
+/** One attribute's normalised value, for the "did it really change" comparison. */
+type PropertyValue = string | number | boolean;
+
+/**
+ * `align` as a `justify-content` keyword.
+ *
+ * C offsets the whole line block by `roundf (length_delta * align)` — a
+ * continuum. Flexbox has three main-axis positions, so the nearest one is taken;
+ * that is the renderer's approximation, not libadwaita's rule, which is why it
+ * lives here and not in the conformance table.
+ */
+function alignToJustifyContent(align: number): string {
+    if (align < 0.25) return 'flex-start';
+    if (align < 0.75) return 'center';
+    return 'flex-end';
+}
 
 export class AdwWrapBox extends HTMLElement {
     private _initialized = false;
 
     static get observedAttributes() {
-        return [
-            'child-spacing',
-            'line-spacing',
-            'orientation',
-            'align',
-            'justify',
-            'justify-last-line',
-            'line-homogeneous',
-            'pack-direction',
-            'wrap-reverse',
-        ];
-    }
-
-    /** Spacing between children on the same line, in px (CSS column-gap). */
+        return [...PROPERTY_ATTRIBUTES];
+    }
+
+    // --- properties ---
+
+    /** Spacing between children on the same line, in `child-spacing-unit`. */
     get childSpacing(): number {
-        return parseFloat(this.getAttribute('child-spacing') || '0');
+        return normalizeWrapBoxSpacing(this.getAttribute('child-spacing'));
     }
 
     set childSpacing(value: number) {
         this.setAttribute('child-spacing', String(value));
     }
 
-    /** Spacing between lines, in px (CSS row-gap). */
+    /** The unit `child-spacing` is written in. Defaults to `px`, as in C. */
+    get childSpacingUnit(): AdwLengthUnit {
+        return normalizeWrapBoxLengthUnit(this.getAttribute('child-spacing-unit'));
+    }
+
+    set childSpacingUnit(value: AdwLengthUnit) {
+        this.setAttribute('child-spacing-unit', value);
+    }
+
+    /** Spacing between lines, in `line-spacing-unit`. */
     get lineSpacing(): number {
-        return parseFloat(this.getAttribute('line-spacing') || '0');
+        return normalizeWrapBoxSpacing(this.getAttribute('line-spacing'));
     }
 
     set lineSpacing(value: number) {
         this.setAttribute('line-spacing', String(value));
     }
 
+    /** The unit `line-spacing` is written in. Defaults to `px`, as in C. */
+    get lineSpacingUnit(): AdwLengthUnit {
+        return normalizeWrapBoxLengthUnit(this.getAttribute('line-spacing-unit'));
+    }
+
+    set lineSpacingUnit(value: AdwLengthUnit) {
+        this.setAttribute('line-spacing-unit', value);
+    }
+
+    /** Where the children sit ALONG the line (main axis): 0 start, 0.5 middle, 1 end. */
+    get align(): number {
+        return normalizeWrapBoxAlign(this.getAttribute('align'));
+    }
+
+    set align(value: number) {
+        this.setAttribute('align', String(value));
+    }
+
+    /** Whether and how each line is stretched to fill the widget. */
+    get justify(): 'none' | 'fill' | 'spread' {
+        return normalizeWrapBoxJustify(this.getAttribute('justify'));
+    }
+
+    set justify(value: 'none' | 'fill' | 'spread') {
+        this.setAttribute('justify', value);
+    }
+
+    /** Whether the FINAL line is justified too. Default false, as in C. */
+    get justifyLastLine(): boolean {
+        return this.hasAttribute('justify-last-line');
+    }
+
+    set justifyLastLine(value: boolean) {
+        this.toggleAttribute('justify-last-line', !!value);
+    }
+
+    /** Whether an overflowing line squeezes its children or lets them spill. */
+    get wrapPolicy(): 'minimum' | 'natural' {
+        return normalizeWrapPolicy(this.getAttribute('wrap-policy'));
+    }
+
+    set wrapPolicy(value: 'minimum' | 'natural') {
+        this.setAttribute('wrap-policy', value);
+    }
+
+    /** The direction children are packed in each line. */
+    get packDirection(): 'start-to-end' | 'end-to-start' {
+        return normalizeWrapBoxPackDirection(this.getAttribute('pack-direction'));
+    }
+
+    set packDirection(value: 'start-to-end' | 'end-to-start') {
+        this.setAttribute('pack-direction', value);
+    }
+
+    /** Whether lines wrap upwards (horizontal) / towards the start (vertical). */
+    get wrapReverse(): boolean {
+        return this.hasAttribute('wrap-reverse');
+    }
+
+    set wrapReverse(value: boolean) {
+        this.toggleAttribute('wrap-reverse', !!value);
+    }
+
+    /** Whether every line takes the same amount of space. */
+    get lineHomogeneous(): boolean {
+        return this.hasAttribute('line-homogeneous');
+    }
+
+    set lineHomogeneous(value: boolean) {
+        this.toggleAttribute('line-homogeneous', !!value);
+    }
+
+    /** The natural line length in `natural-line-length-unit`, or `-1` when unset. */
+    get naturalLineLength(): number {
+        return normalizeNaturalLineLength(this.getAttribute('natural-line-length'));
+    }
+
+    set naturalLineLength(value: number) {
+        this.setAttribute('natural-line-length', String(value));
+    }
+
+    /** The unit `natural-line-length` is written in. Defaults to `px`, as in C. */
+    get naturalLineLengthUnit(): AdwLengthUnit {
+        return normalizeWrapBoxLengthUnit(this.getAttribute('natural-line-length-unit'));
+    }
+
+    set naturalLineLengthUnit(value: AdwLengthUnit) {
+        this.setAttribute('natural-line-length-unit', value);
+    }
+
+    /** The axis children are packed along. */
+    get orientation(): 'horizontal' | 'vertical' {
+        return this.getAttribute('orientation') === 'vertical' ? 'vertical' : 'horizontal';
+    }
+
+    set orientation(value: 'horizontal' | 'vertical') {
+        this.setAttribute('orientation', value);
+    }
+
+    // --- child list (adw_wrap_box_insert_child_after / reorder / remove_all) ---
+    //
+    // `adw_wrap_box_append`, `_prepend` and `_remove` are deliberately NOT
+    // redeclared: `ParentNode.append` / `.prepend` and `Node.removeChild` are
+    // those three, with the same semantics, and shadowing them would give this
+    // element two spellings of one operation. Only the three the DOM has no
+    // counterpart for are added.
+
+    /** The element children, which are what the layout actually lays out. */
+    private get _children(): Element[] {
+        return [...this.children];
+    }
+
+    /**
+     * `adw_wrap_box_insert_child_after` (adw-wrap-box.c:1283-1300).
+     *
+     * A NULL/absent `sibling` inserts at the FIRST position, not the last —
+     * `gtk_widget_insert_after`'s documented rule, pinned by
+     * `WRAP_BOX_CHILD_ORDER_VECTORS`. Returns whether the insert happened; a
+     * refusal is where C would have hit a `g_return_if_fail`.
+     */
+    insertChildAfter(child: Element, sibling: Element | null = null): boolean {
+        return this._applyOrder('insert-after', child, sibling);
+    }
+
+    /** `adw_wrap_box_reorder_child_after` (adw-wrap-box.c:1315-1332). Same NULL rule. */
+    reorderChildAfter(child: Element, sibling: Element | null = null): boolean {
+        return this._applyOrder('reorder-after', child, sibling);
+    }
+
+    /** `adw_wrap_box_remove_all` (adw-wrap-box.c:1406-1414). */
+    removeAll(): void {
+        for (const child of this._children) this.removeChild(child);
+    }
+
+    private _applyOrder(op: 'insert-after' | 'reorder-after', child: Element, sibling: Element | null): boolean {
+        const next = resolveWrapBoxChildOrder({ children: this._children, child, sibling, op });
+        if (next === null) return false;
+        // Move exactly the one node: `insertBefore` relocates a node already in
+        // the tree, and a null reference node appends. Re-appending the whole
+        // resolved list would reach the same order while detaching and
+        // re-attaching every sibling, which resets focus and any element state.
+        const at = next.indexOf(child);
+        this.insertBefore(child, next[at + 1] ?? null);
+        return true;
+    }
+
+    // --- lifecycle ---
+
     connectedCallback() {
         if (this._initialized) return;
         this._initialized = true;
@@ -74,41 +278,58 @@ export class AdwWrapBox extends HTMLElement {
     attributeChangedCallback(name: string, old: string | null, value: string | null) {
         if (!this._initialized) return;
         this._sync();
-        if (old === value) return;
-        if (name === 'child-spacing') {
-            this.dispatchEvent(
-                new CustomEvent('notify::child-spacing', {
-                    bubbles: true,
-                    detail: { childSpacing: this.childSpacing },
-                }),
-            );
-        } else if (name === 'line-spacing') {
-            this.dispatchEvent(
-                new CustomEvent('notify::line-spacing', {
-                    bubbles: true,
-                    detail: { lineSpacing: this.lineSpacing },
-                }),
-            );
+        // C compares AFTER normalising and returns early when nothing changed
+        // (adw-wrap-box.c:592-593), so `child-spacing="-5"` on a box already at 0
+        // notifies nobody. The same gate applies to every property, not just the
+        // two spacings this element used to special-case.
+        const next = this._normalized(name, value);
+        if (next === this._normalized(name, old)) return;
+        this.dispatchEvent(new CustomEvent(`notify::${name}`, { bubbles: true, detail: { [name]: next } }));
+    }
+
+    /** One attribute's value as the widget stores it — the notify comparison key. */
+    private _normalized(name: string, raw: string | null): PropertyValue {
+        switch (name) {
+            case 'child-spacing':
+            case 'line-spacing':
+                return normalizeWrapBoxSpacing(raw);
+            case 'child-spacing-unit':
+            case 'line-spacing-unit':
+            case 'natural-line-length-unit':
+                return normalizeWrapBoxLengthUnit(raw);
+            case 'align':
+                return normalizeWrapBoxAlign(raw);
+            case 'justify':
+                return normalizeWrapBoxJustify(raw);
+            case 'wrap-policy':
+                return normalizeWrapPolicy(raw);
+            case 'pack-direction':
+                return normalizeWrapBoxPackDirection(raw);
+            case 'natural-line-length':
+                return normalizeNaturalLineLength(raw);
+            case 'orientation':
+                return raw === 'vertical' ? 'vertical' : 'horizontal';
+            default:
+                // The three booleans: a present attribute is true whatever it says.
+                return raw !== null;
         }
     }
 
     private _sync() {
         const style = this.style;
-        const vertical = this.getAttribute('orientation') === 'vertical';
-        const reverseWrap = this.hasAttribute('wrap-reverse');
-        const packEndToStart = this.getAttribute('pack-direction') === 'end-to-start';
+        const vertical = this.orientation === 'vertical';
 
         // Main axis is the packing direction; lines wrap along the cross axis.
         const direction = vertical ? 'column' : 'row';
-        const reversed = packEndToStart ? `${direction}-reverse` : direction;
-        style.flexDirection = reversed;
-        style.flexWrap = reverseWrap ? 'wrap-reverse' : 'wrap';
+        style.flexDirection = this.packDirection === 'end-to-start' ? `${direction}-reverse` : direction;
+        style.flexWrap = this.wrapReverse ? 'wrap-reverse' : 'wrap';
 
         // child-spacing is along the line (main axis), line-spacing is between
         // lines (cross axis). For a horizontal box that maps to column-gap /
-        // row-gap respectively; the mapping flips for a vertical box.
-        const childGap = `${this.childSpacing}px`;
-        const lineGap = `${this.lineSpacing}px`;
+        // row-gap respectively; the mapping flips for a vertical box. Both are
+        // resolved through their OWN unit first, which is why they can disagree.
+        const childGap = `${wrapBoxLengthToPx(this.childSpacing, this.childSpacingUnit)}px`;
+        const lineGap = `${wrapBoxLengthToPx(this.lineSpacing, this.lineSpacingUnit)}px`;
         if (vertical) {
             style.rowGap = childGap;
             style.columnGap = lineGap;
@@ -116,23 +337,53 @@ export class AdwWrapBox extends HTMLElement {
             style.columnGap = childGap;
             style.rowGap = lineGap;
         }
+        // Read back by the last-line filler, which has to cancel exactly one
+        // main-axis gap so it can never push a full line into a new one.
+        style.setProperty('--adw-wrap-box-child-spacing', childGap);
+
+        const justify = this.justify;
+        const justifyLastLine = this.justifyLastLine;
+        const align = this.align;
 
-        // justify-content stretches each complete line along the main axis; the
-        // last (incomplete) line is only stretched when justify-last-line is set.
-        const justify = this.getAttribute('justify') ?? 'none';
-        style.justifyContent = JUSTIFY_MAP[justify] ?? 'flex-start';
+        // A flex container has ONE `justify-content` and applies it to every
+        // line, so it carries the COMPLETE-line rule; the final-line rule is
+        // published beside it for the stylesheet, which reaches that line through
+        // the only two selectors CSS offers — `:only-child` (a box with one child
+        // has one line, and it is the last) and the generated `::after` filler.
+        // The pair is deliberately never collapsed into one attribute: flexbox
+        // cannot express "every line but the last", and pretending otherwise is
+        // what made `justify-last-line` a no-op in the first place.
+        const line = resolveWrapBoxLine({ justify, justifyLastLine, align, lastLine: false, childrenInLine: 2 });
+        const lastLine = resolveWrapBoxLine({ justify, justifyLastLine, align, lastLine: true, childrenInLine: 2 });
+        this.dataset.lineJustify = line.justify;
+        this.dataset.lastLineJustify = lastLine.justify;
 
-        // align (0..1) positions children within each line on the cross axis.
-        // It is only honoured when the line is not justified.
-        const align = Math.max(0, Math.min(1, parseFloat(this.getAttribute('align') || '0')));
-        let crossAlign = 'flex-start';
-        if (align >= 0.75) crossAlign = 'flex-end';
-        else if (align >= 0.25) crossAlign = 'center';
-        style.alignItems = crossAlign;
+        // SPREAD widens the gaps; FILL grows the children (stylesheet) and leaves
+        // the gaps alone; NONE offsets the whole line block by `align` — along
+        // the MAIN axis, never the cross one.
+        style.justifyContent = line.growGaps ? 'space-between' : alignToJustifyContent(line.align);
 
         // line-homogeneous makes every line take the same amount of space, which
         // flexbox approximates by stretching the lines across the cross axis.
-        style.alignContent = this.hasAttribute('line-homogeneous') ? 'stretch' : 'flex-start';
+        style.alignContent = this.lineHomogeneous ? 'stretch' : 'flex-start';
+
+        // `wrap-policy` decides whether an overflowing line squeezes its children
+        // or lets them spill. CSS defaults `flex-shrink` to 1, i.e. to
+        // ADW_WRAP_MINIMUM — the value libadwaita does NOT default to, so an
+        // unset policy has been drawing the wrong one on every wrap box. What
+        // flexbox cannot do either way is pack MORE children onto a line, since
+        // line breaking runs on hypothetical sizes; see `wrapPolicyFlexShrink`.
+        style.setProperty('--adw-wrap-box-child-shrink', String(wrapPolicyFlexShrink(this.wrapPolicy)));
+
+        // DELIBERATE DEVIATION: libadwaita's `natural-line-length` caps the box's
+        // NATURAL size request, leaving a larger allocation free to happen; CSS
+        // has no property that caps only the intrinsic contribution, so this is a
+        // max-size on the main axis and therefore caps the allocation too. It is
+        // the intended use (limiting line length inside a popover) either way.
+        const natural = wrapBoxLengthToPx(this.naturalLineLength, this.naturalLineLengthUnit);
+        const cap = natural === ADW_WRAP_BOX_NATURAL_LINE_LENGTH_UNSET ? '' : `${natural}px`;
+        style.maxWidth = vertical ? '' : cap;
+        style.maxHeight = vertical ? cap : '';
     }
 }
 

package/src/elements/view-switcher-dom.ts

@@ -0,0 +1,108 @@
+// The DOM half of the view-switcher family — what `@gjsify/adwaita-core` cannot
+// decide because it is genuinely per-renderer.
+//
+// Everything that decides WHAT a switcher shows (the button-visibility rule, the
+// `image-missing` fallback, the badge label + screen-reader description, the
+// mnemonic-stripped label, the tooltip, the reveal gate, the two index spaces)
+// lives in `@gjsify/adwaita-core` and is pinned by the conformance vectors.
+// What is left, and lives here, is how a derived model becomes nodes: an icon
+// NAME turned into a CSS mask class, an indicator span, and a `setTimeout`
+// wrapped in the scheduler seam the core takes for the drag-hover dwell.
+//
+// Shared by all three switcher elements because it was three copies before:
+// `<adw-view-switcher>`, `<adw-inline-view-switcher>` and
+// `<adw-view-switcher-bar>` each built their own icon span and their own page
+// parsing, and the copies had already drifted (a titleless page rendered `''` in
+// one and `page-<index>` in another).
+//
+// Reference: refs/libadwaita/src/adw-view-switcher.c
+// Reference: refs/libadwaita/src/adw-indicator-bin.c
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Modifications: Implemented for @gjsify/adwaita-web Web Components.
+
+import { viewSwitcherIconName } from '@gjsify/adwaita-core';
+import type { AdwViewSwitcherPageInit, ViewSwitcherScheduler, ViewSwitcherTimerHandle } from '@gjsify/adwaita-core';
+
+import { type AdwIcon, createAdwIcon } from './adw-icon.js';
+
+/**
+ * The browser's timer behind the core's scheduler seam.
+ *
+ * One shared instance rather than one per element: it holds no state, and the
+ * seam exists so the CORE stays free of a global timer, not so each element
+ * invents its own.
+ */
+export const domViewSwitcherScheduler: ViewSwitcherScheduler = {
+    schedule(callback: () => void, ms: number): ViewSwitcherTimerHandle {
+        return setTimeout(callback, ms);
+    },
+    cancel(handle: ViewSwitcherTimerHandle): void {
+        clearTimeout(handle as ReturnType<typeof setTimeout>);
+    },
+};
+
+/**
+ * Build a switcher button's icon node, carrying its own position class.
+ *
+ * The core resolves NULL/empty to `image-missing` (which the stylesheet carries
+ * a real glyph for); the `-symbolic` strip and the CSS-token guard are
+ * `normalizeIconName`'s, applied by `<adw-icon>` — that strip is this package's
+ * own mask-class convention and has no counterpart in C, where the name reaches
+ * `GtkImage` untouched.
+ */
+export function createSwitcherIcon(iconName: string, extra: string): AdwIcon {
+    return createAdwIcon(viewSwitcherIconName(iconName), extra);
+}
+
+/** Repaint an existing switcher icon from a page's declared name. */
+export function applySwitcherIcon(icon: AdwIcon, iconName: string): void {
+    icon.iconName = viewSwitcherIconName(iconName);
+}
+
+/**
+ * Read a declared page element into the core's page init.
+ *
+ * `getAttribute` returns `null` for an absent attribute, which is EXACTLY C's
+ * NULL — so the values are passed through unchanged rather than defaulted to
+ * `''`. That `?? ''` is what made the button-visibility rule unimplementable in
+ * the old code: once an absent title has become the empty string, "the page has
+ * no title" is no longer expressible.
+ */
+export function readSwitcherPage(element: Element): AdwViewSwitcherPageInit {
+    const badge = Number.parseInt(element.getAttribute('badge-number') ?? '', 10);
+    return {
+        // A page with no `name` is the page named '' — the same choice
+        // `<adw-view-stack>` made, and for the same reason: C stores the name
+        // verbatim (adw-view-stack.c:1170) and an invented `page-<index>` is
+        // addressable by a name the author never wrote.
+        name: element.getAttribute('name') ?? '',
+        title: element.getAttribute('title'),
+        iconName: element.getAttribute('icon-name'),
+        // `hidden` is the DOM spelling of AdwViewStackPage:visible.
+        visible: !element.hasAttribute('hidden'),
+        useUnderline: element.hasAttribute('use-underline'),
+        badgeNumber: Number.isNaN(badge) ? 0 : badge,
+        needsAttention: element.hasAttribute('needs-attention'),
+    };
+}
+
+/**
+ * Paint `AdwIndicatorBin`'s badge/dot onto a span: the badge text when there is
+ * one, a bare dot when only `needs-attention` is set, nothing otherwise
+ * (adw-indicator-bin.c:58-68 + the `.needs-attention` style class).
+ */
+export function applyIndicator(indicator: HTMLElement, badgeLabel: string, needsAttention: boolean): void {
+    indicator.textContent = badgeLabel;
+    indicator.classList.toggle('needs-attention', needsAttention && badgeLabel.length === 0);
+    indicator.hidden = badgeLabel.length === 0 && !needsAttention;
+}
+
+/**
+ * Mirror the derived screen-reader description onto the element, REMOVING the
+ * attribute when there is none — `update_description_cb` resets the accessible
+ * property rather than setting it to `""` (adw-view-switcher-button.c:104-113).
+ */
+export function applyDescription(element: HTMLElement, description: string): void {
+    if (description) element.setAttribute('aria-description', description);
+    else element.removeAttribute('aria-description');
+}