@gjsify/adwaita-web 0.36.0 → 0.38.0

package/lib/types/elements/adw-entry-row.d.ts

@@ -27,7 +27,6 @@ export declare class AdwEntryRow extends HTMLElement {
      * the two SCSS partials are near-identical but each scopes to its own tag.
      */
     protected get _classPrefix(): string;
-    /** The editable text. */
     get text(): string;
     set text(value: string);
     /** `Adw.EntryRow:text-length` — the number of CHARACTERS, not UTF-16 units. */
@@ -44,54 +43,52 @@ export declare class AdwEntryRow extends HTMLElement {
     /** `Adw.EntryRow:activates-default` — Enter may submit the surrounding form. */
     get activatesDefault(): boolean;
     set activatesDefault(value: boolean);
-    /** Whether the embedded entry currently has focus. */
     get editing(): boolean;
     connectedCallback(): void;
     attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
     /**
-     * Add a widget after the editable area — `adw_entry_row_add_suffix`
-     * (adw-entry-row.c:885-899), which APPENDS into a box, so several suffixes
-     * coexist and the password row's own peek toggle survives a consumer's.
+     * Add a widget after the editable area — `adw_entry_row_add_suffix`, which APPENDS
+     * into a box, so several suffixes coexist and the password row's own peek toggle
+     * survives a consumer's.
      */
     addSuffix(node: Node): void;
     /**
-     * Add a widget before the editable area — `adw_entry_row_add_prefix`
-     * (C:864-880). PREPENDS, like the `gtk_box_prepend` it mirrors, so several
-     * prefixes stack in reverse call order exactly as they do in GTK.
+     * Add a widget before the editable area — `adw_entry_row_add_prefix`. PREPENDS, like
+     * the `gtk_box_prepend` it mirrors, so several prefixes stack in reverse call order
+     * exactly as they do in GTK.
      */
     addPrefix(node: Node): void;
     /**
      * Drive the trailing indicator — `adw_entry_row_set_show_indicator`
-     * (adw-entry-row-private.h, C:1281-1296). Private-to-the-library upstream,
-     * public here because `<adw-password-entry-row>` is a separate custom element
-     * rather than a C subclass with access to the private header.
+     * (adw-entry-row-private.h). Private-to-the-library upstream, public here because
+     * `<adw-password-entry-row>` is a separate custom element rather than a C subclass
+     * with access to the private header.
      */
     setShowIndicator(show: boolean): void;
-    /** `adw_entry_row_set_indicator_icon_name` (C:1263-1273). */
+    /** `adw_entry_row_set_indicator_icon_name`. */
     setIndicatorIconName(iconName: string): void;
-    /** `adw_entry_row_set_indicator_tooltip` (C:1275-1279). */
+    /** `adw_entry_row_set_indicator_tooltip`. */
     setIndicatorTooltip(tooltip: string): void;
-    /** Apply the pending edit — the apply button click (C:229-241). */
+    /** Apply the pending edit — the apply button click. */
     apply(): void;
-    /** Focus the entry without selecting — `adw_entry_row_grab_focus_without_selecting` (C:1379-1389). */
+    /** Focus the entry without selecting — `adw_entry_row_grab_focus_without_selecting`. */
     grabFocusWithoutSelecting(): boolean;
     /** Subclass hook: runs after the DOM exists and the state is seeded, before the first render. */
     protected _onConnected(): void;
     private _build;
     /**
-     * Re-home the children the author wrote. libadwaita's buildable maps an
-     * untyped `<child>` to a suffix (C:796-812); `slot="prefix"` is the web
-     * spelling of its `type="prefix"`.
+     * Re-home the children the author wrote. libadwaita's buildable maps an untyped
+     * `<child>` to a suffix; `slot="prefix"` is the web spelling of `type="prefix"`.
      */
     private _adoptAuthored;
     /**
-     * `pressed_cb` (C:201-227): a click landing on the row, the editable area,
-     * the indicator or either affordance box grabs focus; anything else (a suffix
-     * control, the apply button) is left alone. The pencil is `can-target=False`
-     * in the .ui, so a click on it picks the editable area — hence it focuses too.
+     * `pressed_cb`: a click landing on the row, the editable area, the indicator or
+     * either affordance box grabs focus; anything else (a suffix control, the apply
+     * button) is left alone. The pencil is `can-target=False` in the .ui, so a click on
+     * it picks the editable area — hence it focuses too.
      */
     private _maybeFocus;
-    /** `text_activated_cb` (C:243-266) — exactly one of the two signals. */
+    /** `text_activated_cb` — exactly one of the two signals. */
     private _activate;
     private _renderTitle;
     /** Paint one render snapshot. Overridden (via `super`) by the password row. */

package/lib/types/elements/adw-icon.d.ts

@@ -17,9 +17,7 @@ export declare class AdwIcon extends HTMLElement {
     private _render;
 }
 /**
- * Build one icon node: the three lines every caller would otherwise write.
- *
- * `extraClasses` are the caller's own positioning/context classes, added
- * alongside the managed `.adw-icon` + mask class rather than replacing them.
+ * Build one icon node. `extraClasses` are the caller's own positioning/context
+ * classes, added alongside the managed `.adw-icon` + mask class, not replacing them.
  */
 export declare function createAdwIcon(iconName: string | null, ...extraClasses: string[]): AdwIcon;

package/lib/types/elements/adw-inline-view-switcher.d.ts

@@ -6,14 +6,10 @@ export declare class AdwViewStackPage extends HTMLElement {
 }
 export declare class AdwInlineViewSwitcher extends HTMLElement {
     /**
-     * The dwell timer, injectable.
-     *
-     * It used to be `new ViewSwitcherState({ scheduler: domViewSwitcherScheduler })`
-     * inline, which left NOWHERE to hand a clock in — so
-     * `VIEW_SWITCHER_DRAG_VECTORS` was driven by the core suite alone, and the
-     * conformance header claimed all three suites drove it. `scheduler` is a
-     * property so a test can replace it before the element connects; the DOM one
-     * is the default, exactly as before.
+     * The dwell timer, injectable: a property rather than an inline
+     * `new ViewSwitcherState({ scheduler: domViewSwitcherScheduler })`, so a test can
+     * replace the clock before the element connects and drive
+     * `VIEW_SWITCHER_DRAG_VECTORS` here too. The DOM scheduler is the default.
      */
     scheduler: ViewSwitcherScheduler;
     private _stateInstance;
@@ -35,54 +31,45 @@ export declare class AdwInlineViewSwitcher extends HTMLElement {
     set active(value: number);
     /**
      * Index of the ACTIVE TOGGLE, `-1` when the visible page has none because it
-     * is hidden — the port-safe `GTK_INVALID_LIST_POSITION`
-     * (adw-inline-view-switcher.c:441-446).
+     * is hidden — the port-safe `GTK_INVALID_LIST_POSITION`.
      */
     get activeToggle(): number;
-    /** What the toggles display: 'labels', 'icons' or 'both'. */
     get displayMode(): AdwInlineViewSwitcherDisplayMode;
     set displayMode(value: AdwInlineViewSwitcherDisplayMode);
     /** Name of the visible page, `''` when nothing is selected. */
     get visibleChildName(): string;
     set visibleChildName(name: string | null | undefined);
-    /** The resolved page records. */
     get pages(): readonly AdwViewSwitcherPage[];
     /**
      * Show or hide a page. Returns whether the SELECTION moved. Rebuilds the
      * toggle row, because a hidden page has no toggle at all — C reacts to a
-     * page's `notify::visible` with `recreate_toggles`
-     * (adw-inline-view-switcher.c:425, :471-477).
+     * page's `notify::visible` with `recreate_toggles`.
      */
     setPageVisible(name: string, visible: boolean): boolean;
     connectedCallback(): void;
     disconnectedCallback(): void;
     /**
-     * Re-read every declared page and push it into the state.
-     *
-     * Driven by {@link _watchPages}, which is what makes a runtime
-     * `badge-number` or `icon-name` change reach the toggle — C rebinds on every
-     * page `notify` (adw-view-switcher.c:184-193) and this element did not.
+     * Re-read every declared page and push it into the state. Driven by
+     * {@link _watchPages}, which is what makes a runtime `badge-number` or `icon-name`
+     * change reach the toggle, as C's per-page `notify` bindings do.
      */
     refreshPages(): void;
     /**
      * Watch the declared pages for attribute changes — the DOM's `notify::` on
-     * `AdwViewStackPage`, which C binds per page (adw-view-switcher.c:184-193).
-     *
-     * A `MutationObserver` rather than an `attributeChangedCallback`: this
-     * element consumes the page elements at connect and `replaceChildren`s them
-     * out of the tree, so a detached page cannot find its owner. It delivers on
-     * a MICROTASK where GTK's notify is synchronous — invisible to a user, and
-     * nothing here reads the toggle back inside the setter.
+     * `AdwViewStackPage`. A `MutationObserver` rather than an
+     * `attributeChangedCallback`, because this element consumes the page elements at
+     * connect and `replaceChildren`s them out of the tree, so a detached page cannot
+     * find its owner. It delivers on a MICROTASK where GTK's notify is synchronous —
+     * invisible to a user, and nothing here reads the toggle back inside the setter.
      */
     private _watchPages;
     attributeChangedCallback(name: string): void;
     private _readDisplayModeAttr;
     /**
-     * Rebuild the toggle row from the derived models. One node per VISIBLE page,
-     * in compacted order — the structural half of `recreate_toggles`. Selection
-     * alone never lands here: `selection_changed_cb` only sets the active toggle
-     * (adw-inline-view-switcher.c:434-453), and rebuilding mid-drag would drop
-     * the dwell the drag has already armed.
+     * Rebuild the toggle row from the derived models: one node per VISIBLE page, in
+     * compacted order — the structural half of `recreate_toggles`. Selection alone never
+     * lands here (`selection_changed_cb` only sets the active toggle), because
+     * rebuilding mid-drag would drop the dwell the drag has already armed.
      */
     private _rebuildToggles;
     private _onStateChange;

package/lib/types/elements/adw-navigation-split-view.d.ts

@@ -24,12 +24,10 @@ export declare class AdwNavigationSplitView extends HTMLElement {
     /** Which side the sidebar is packed on — `start` (default) or `end`. */
     get sidebarPosition(): AdwPackType;
     set sidebarPosition(value: AdwPackType);
-    /** The sidebar page's tag of record, or `null`. */
     get sidebarTag(): string | null;
-    /** The content page's tag of record, or `null`. */
     get contentTag(): string | null;
     /**
-     * `navigation.push` with `tag` — `navigation_push_cb` (:644-685).
+     * `navigation.push` with `tag` — `navigation_push_cb`.
      *
      * An unmatched tag DELEGATES to the parent before it may become a critical,
      * which is how nested split views forward a push outwards; on this port that
@@ -37,27 +35,24 @@ export declare class AdwNavigationSplitView extends HTMLElement {
      * sets. Returns what the routing decided.
      */
     push(tag: string): NavigationActionResult;
-    /** `navigation.pop` — `navigation_pop_cb` (:687-702). */
+    /** `navigation.pop` — `navigation_pop_cb`. */
     pop(): NavigationActionResult;
     connectedCallback(): void;
     /** `Adw.NavigationPage:tag` off the slotted pane, or `null` when untagged. */
     private _tagOf;
     /**
-     * Mirror the state's `showContent` onto the attribute, so the DOM keeps
-     * telling the truth after a `navigation.push` moved it.
-     *
-     * Guarded the way the overlay view's reflection is: writing the attribute
-     * re-enters `attributeChangedCallback`, which without the flag is a loop.
+     * Mirror the state's `showContent` onto the attribute, so the DOM keeps telling the
+     * truth after a `navigation.push` moved it. Guarded like the overlay view's
+     * reflection: writing the attribute re-enters `attributeChangedCallback`, which
+     * without the flag is a loop.
      */
     private _reflectShowContent;
     disconnectedCallback(): void;
     attributeChangedCallback(name: string): void;
     private _syncWidth;
-    /** A pixel attribute, falling back to the widget's own default. */
     private _widthAttr;
-    /** The reading direction `start` / `end` resolve against (`get_start_or_end`, :220-227). */
+    /** The reading direction `start` / `end` resolve against (`get_start_or_end`). */
     private get _direction();
     private _syncClasses;
-    /** (Re)bind the `breakpoint` condition to `collapsed`. */
     private _syncBreakpoint;
 }

package/lib/types/elements/adw-navigation-view.d.ts

@@ -11,7 +11,6 @@ export declare class AdwNavigationPage extends HTMLElement {
     get canPop(): boolean;
     set canPop(value: boolean);
     attributeChangedCallback(name: string, previous: string | null): void;
-    /** Put an attribute back the way it was, without re-entering the sync. */
     revertAttribute(name: string, value: string | null): void;
 }
 export declare class AdwNavigationView extends HTMLElement {
@@ -21,21 +20,16 @@ export declare class AdwNavigationView extends HTMLElement {
     private readonly _diagnose;
     private readonly _state;
     static get observedAttributes(): string[];
-    /** Whether push/pop transitions are animated. */
     get animateTransitions(): boolean;
     set animateTransitions(value: boolean);
     /** Whether pressing Escape pops the visible page (Adw.NavigationView:pop-on-escape). */
     get popOnEscape(): boolean;
     set popOnEscape(value: boolean);
-    /** The currently-visible page (top of the stack), or null when empty. */
     get visiblePage(): AdwNavigationPage | null;
-    /** The tag of the visible page, or null. */
     get visiblePageTag(): string | null;
-    /** The number of pages on the navigation stack. */
     get depth(): number;
     /** The navigation stack, bottom-first (Adw.NavigationView:navigation-stack). */
     get navigationStack(): readonly AdwNavigationPage[];
-    /** Every page this view knows — static and dynamically pushed. */
     get pages(): readonly AdwNavigationPage[];
     /** Whether the automatic back button is shown (AdwBackButton's visibility rule). */
     get canGoBack(): boolean;
@@ -85,9 +79,8 @@ export declare class AdwNavigationView extends HTMLElement {
      * Replace the whole navigation stack (mirrors AdwNavigationView.replace). The
      * last page becomes visible; the transition is never animated.
      *
-     * String entries are resolved BEFORE anything is mutated — the C does the same
-     * in replace_with_tags:3136-3147, and resolving late is what used to lose a
-     * dynamically-pushed page and blank the view.
+     * String entries are resolved BEFORE anything is mutated, as `replace_with_tags`
+     * does: resolving late loses a dynamically-pushed page and blanks the view.
      */
     replace(pages: ReadonlyArray<AdwNavigationPage | string | null>): void;
     /** Replace the stack with the pages carrying `tags` (mirrors AdwNavigationView.replace_with_tags). */
@@ -103,7 +96,6 @@ export declare class AdwNavigationView extends HTMLElement {
     private _render;
     private _attach;
     private _detach;
-    /** Inject (or remove) the automatic back button on the visible page. */
     private _syncBackButton;
     private _removeBackButton;
 }

package/lib/types/elements/adw-overlay-split-view.d.ts

@@ -5,10 +5,9 @@ export declare class AdwOverlaySplitView extends HTMLElement {
     private _backdropEl;
     private _disposeBreakpoint;
     /**
-     * The single source of truth for the property interplay, shared with the
-     * NativeScript renderer (ADR 0004). The element owns the attributes and the
-     * painting; every rule about what `collapsed` + `show-sidebar` + `pin-sidebar`
-     * MEAN together lives in core, held to `OVERLAY_COLLAPSE_VECTORS`.
+     * The property interplay, shared with the NativeScript renderer (ADR 0004): the
+     * element owns the attributes and the painting, core owns what `collapsed` +
+     * `show-sidebar` + `pin-sidebar` mean together, held to `OVERLAY_COLLAPSE_VECTORS`.
      */
     private _state;
     /** Re-entrancy guard for {@link _reflectShowSidebar}. */
@@ -23,9 +22,7 @@ export declare class AdwOverlaySplitView extends HTMLElement {
     /**
      * Every attribute {@link _readAttribute} handles must be listed here — an
      * unobserved attribute never reaches `attributeChangedCallback`, so its branch
-     * is DEAD after construction. `pin-sidebar` was missing, which made the
-     * property that suppresses the collapse coupling settable only in the markup
-     * a parser saw: `view.setAttribute('pin-sidebar', '')` did nothing at all.
+     * is dead after construction and the property is settable only in parsed markup.
      */
     static get observedAttributes(): string[];
     get showSidebar(): boolean;
@@ -36,18 +33,13 @@ export declare class AdwOverlaySplitView extends HTMLElement {
     get maxSidebarWidth(): number;
     get sidebarWidthFraction(): number;
     connectedCallback(): void;
-    /** The DOM surgery and the state, which happen once per element lifetime. */
     private _buildOnce;
     /**
-     * Everything that must be re-established every time the element enters a
-     * document — NOT once per lifetime.
-     *
-     * `connectedCallback` returns early on the second connect (the DOM is
-     * already built), so anything torn down in `disconnectedCallback` used to be
-     * gone for good: moving the view between parents — which is what a slideshow
-     * or a client-side route change does — killed the ResizeObserver and left
-     * `_measuredWidth` frozen at whatever it last saw, or at 0 if the view had
-     * never been visible. That is the other half of the docs-site regression.
+     * Everything that must be re-established every time the element enters a document,
+     * NOT once per lifetime: `_buildOnce` returns early on the second connect, so
+     * anything torn down in `disconnectedCallback` and rebound only there would be gone
+     * for good — moving the view between parents (a slideshow, a client-side route
+     * change) would kill the ResizeObserver and freeze `_measuredWidth`.
      */
     private _bindToDocument;
     disconnectedCallback(): void;
@@ -55,61 +47,45 @@ export declare class AdwOverlaySplitView extends HTMLElement {
     private readonly _onKeyDown;
     attributeChangedCallback(_name: string, _old: string | null, _val: string | null): void;
     /**
-     * Push ONE attribute into the state, then reflect back what the state made
-     * of it.
-     *
-     * Per-attribute rather than a re-read of all of them, because `show-sidebar`
-     * is a value the state ALSO owns: collapsing auto-hides an unpinned sidebar,
-     * and a blanket re-read would immediately clobber that decision with the
-     * stale attribute.
+     * Push ONE attribute into the state, then reflect back what the state made of it.
+     * Per-attribute rather than a re-read of all of them: `show-sidebar` is a value the
+     * state ALSO owns (collapsing auto-hides an unpinned sidebar), so a blanket re-read
+     * would clobber that decision with the stale attribute.
      */
     private _readAttribute;
     /**
-     * Mirror the state's `showSidebar` back onto the attribute, so the DOM keeps
-     * telling the truth after an auto-hide.
-     *
-     * Guarded: writing the attribute re-enters `attributeChangedCallback`, and
-     * without the flag that is an infinite reflection loop rather than a render.
+     * Mirror the state's `showSidebar` back onto the attribute, so the DOM keeps telling
+     * the truth after an auto-hide. Guarded: writing the attribute re-enters
+     * `attributeChangedCallback`, and without the flag that is an infinite reflection
+     * loop rather than a render.
      */
     private _reflectShowSidebar;
-    /** (Re)bind the `breakpoint` condition to `collapsed`. */
     private _syncBreakpoint;
     openSidebar(): void;
     hideSidebar(): void;
     toggleSidebar(): void;
     /**
-     * The reading direction `start` / `end` are resolved against.
-     *
-     * `get_start_or_end` (adw-overlay-split-view.c:227-234) returns
-     * `GTK_PACK_END` under RTL, so a `start` sidebar is drawn on the RIGHT.
-     * Neither renderer mirrored any of it; the browser has the direction for
-     * free and only had to read it.
+     * The reading direction `start` / `end` are resolved against: `get_start_or_end`
+     * returns `GTK_PACK_END` under RTL, so a `start` sidebar is drawn on the RIGHT.
      */
     private get _direction();
-    /** The sizing properties as the core takes them. */
     private get _widthSpec();
-    /** The sidebar's allocated width in px — `get_sidebar_width` (:441-466). */
+    /** The sidebar's allocated width in px — `get_sidebar_width`. */
     private get _sidebarWidth();
     private _syncClasses;
     /**
-     * Place the sidebar for the current progress — `allocate_uncollapsed`
-     * (:572-610) and `allocate_collapsed` (:653-703), through the core.
-     *
-     * The slide used to be `marginRight: -offsetWidth` REGARDLESS of which edge
-     * the sidebar is on, so an `end` sidebar slid the wrong way; and it was only
-     * two states, so a swipe had nothing to drive. `layoutOverlaySplitView`
-     * returns the pane rect for any progress including the overshoot, which is
-     * what makes a continuous gesture expressible at all.
+     * Place the sidebar for the current progress — `allocate_uncollapsed` /
+     * `allocate_collapsed`, through the core. `layoutOverlaySplitView` returns the pane
+     * rect for ANY progress, overshoot included, which is what makes a continuous
+     * gesture expressible; the offset also has to follow the edge the sidebar is on, or
+     * an `end` sidebar slides the wrong way.
      */
     private _syncGeometry;
     private _syncSidebarWidth;
     /**
-     * The pan gesture the five `OVERLAY_SWIPE_*` tables describe.
-     *
-     * There was no gesture code in either renderer — grep for `pan` in both
-     * split views returned zero — so `showProgress` was only ever 0 or 1 and the
-     * tables shipped unexercised. Pointer events give the browser the whole
-     * gesture in three handlers; every DECISION in them is core's.
+     * The `Adw.Swipeable` pan gesture the five `OVERLAY_SWIPE_*` tables describe.
+     * Pointer events give the browser the whole gesture in three handlers; every
+     * DECISION in them is core's.
      */
     private _bindSwipe;
 }

package/lib/types/elements/adw-password-entry-row.d.ts

@@ -12,14 +12,13 @@ export declare class AdwPasswordEntryRow extends AdwEntryRow {
     /** Whether Caps Lock is engaged, as last observed from a keyboard event. */
     get capsLockOn(): boolean;
     /**
-     * Feed the platform's Caps Lock state in — GDK gets it from the keyboard
-     * device (adw-password-entry-row.c:111-115). Public because a host that
-     * knows better than `KeyboardEvent.getModifierState` (a virtual keyboard, a
-     * test) can drive it directly.
+     * Feed the platform's Caps Lock state in — GDK gets it from the keyboard device.
+     * Public so a host that knows better than `KeyboardEvent.getModifierState` (a virtual
+     * keyboard, a test) can drive it directly.
      */
     setCapsLockOn(on: boolean): void;
     protected _onConnected(): void;
     attributeChangedCallback(name: string, oldValue: string | null, value: string | null): void;
-    /** `notify_visibility_cb` (C:62-81), applied to the DOM. */
+    /** `notify_visibility_cb`, applied to the DOM. */
     private _renderPassword;
 }

package/lib/types/elements/adw-popover.d.ts

@@ -13,23 +13,18 @@ export declare class AdwPopover extends HTMLElement {
     private _onDocumentPointerDown;
     private _onDocumentKeyDown;
     static get observedAttributes(): string[];
-    /** Whether the popover is showing. */
     get open(): boolean;
     set open(value: boolean);
     /**
-     * The element the surface is positioned against and hands focus back to.
-     * Defaults to `parentElement`, which is the common case: the popover is the
-     * last child of the widget that owns it.
+     * The element the surface is positioned against and hands focus back to. Defaults to
+     * `parentElement`: the popover is normally the last child of the widget that owns it.
      */
     get anchor(): HTMLElement | null;
     set anchor(value: HTMLElement | null);
-    /** Which side of the anchor the surface sits on. */
     get position(): AdwPopoverPosition;
     set position(value: AdwPopoverPosition);
-    /** Which edge of the anchor the surface lines up with. */
     get align(): AdwPopoverAlign;
     set align(value: AdwPopoverAlign);
-    /** The surface's ARIA role. */
     get popoverRole(): AdwPopoverRole;
     /** The navigable rows, in DOM order. Hidden rows are skipped — a filtered list navigates what it shows. */
     get items(): HTMLElement[];

package/lib/types/elements/adw-preferences-dialog.d.ts

@@ -1,14 +1,11 @@
 import type { PreferencesSearchResult, SearchPreferencesOptions } from '@gjsify/adwaita-core';
 /**
- * A single preferences page. Child of <adw-preferences-dialog>. Carries optional
- * `title` / `icon-name` / `name` / `use-underline` attributes and any
- * <adw-preferences-group> content — mirrors Adw.PreferencesPage.
+ * A single preferences page (Adw.PreferencesPage), child of <adw-preferences-dialog>.
  *
- * The dialog keeps the page ELEMENT rather than hoisting its children out,
- * because the page's identity is load-bearing: `adw_preferences_dialog_add`
- * binds title / icon-name / name / use-underline / visible onto the view-stack
- * page (adw-preferences-dialog.c:707-711), and `create_search_row_subtitle`
- * needs the title back the moment a second page is visible.
+ * The dialog keeps the page ELEMENT rather than hoisting its children out, because the
+ * page's identity is load-bearing: `adw_preferences_dialog_add` binds title / icon-name
+ * / name / use-underline / visible onto the view-stack page, and
+ * `create_search_row_subtitle` needs the title back the moment a second page is visible.
  */
 export declare class AdwPreferencesPage extends HTMLElement {
     static get observedAttributes(): string[];
@@ -21,7 +18,6 @@ export declare class AdwPreferencesPage extends HTMLElement {
     /** `AdwPreferencesPage:use-underline` — the title carries a mnemonic. */
     get useUnderline(): boolean;
     set useUnderline(value: boolean);
-    /** The page's groups, in document order. */
     get groups(): HTMLElement[];
 }
 export declare class AdwPreferencesDialog extends HTMLElement {
@@ -33,7 +29,6 @@ export declare class AdwPreferencesDialog extends HTMLElement {
     private _pagesEl;
     private _closeBtn;
     static get observedAttributes(): string[];
-    /** Whether the dialog is revealed. */
     get open(): boolean;
     set open(value: boolean);
     /** Whether the user can dismiss the dialog (scrim / Escape / close button). */
@@ -49,39 +44,31 @@ export declare class AdwPreferencesDialog extends HTMLElement {
     /** Dismiss the dialog regardless of `can-close` (mirrors Adw.Dialog.force_close). */
     forceClose(): void;
     /**
-     * `adw_preferences_dialog_add` (adw-preferences-dialog.c:693-716) — add a
-     * page at ANY time.
-     *
-     * Before this the pages were snapshotted once, in `connectedCallback`; a
-     * page appended later stayed a sibling of the scrim and rendered OUTSIDE
-     * the dialog card. GTK and the NativeScript port both accept a page
-     * whenever it arrives.
+     * `adw_preferences_dialog_add` — add a page at ANY time. A page that is only
+     * snapshotted in `connectedCallback` stays a sibling of the scrim and renders
+     * OUTSIDE the dialog card; GTK and the NativeScript port both accept one whenever
+     * it arrives.
      */
     add(page: AdwPreferencesPage): void;
     /**
-     * `adw_preferences_dialog_remove` (:723-745). C logs
-     * `ADW_CRITICAL_CANNOT_REMOVE_CHILD` and no-ops for a page it does not own;
-     * returning `false` is the same contract without a console write.
+     * `adw_preferences_dialog_remove`. C logs `ADW_CRITICAL_CANNOT_REMOVE_CHILD` and
+     * no-ops for a page it does not own; returning `false` is the same contract without
+     * a console write.
      *
-     * NOT named `remove`: `ChildNode.remove()` already exists on every element
-     * and takes no arguments, so overriding it with a different signature makes
-     * the class un-assignable to `HTMLElement` — which `customElements.define`
-     * requires.
+     * NOT named `remove`: `ChildNode.remove()` exists on every element and takes no
+     * arguments, so overriding it with a different signature makes the class
+     * un-assignable to `HTMLElement` — which `customElements.define` requires.
      */
     removePage(page: AdwPreferencesPage): boolean;
-    /** The dialog's pages, in add order. */
     get pages(): AdwPreferencesPage[];
     /**
-     * The preferences search (`filter_search_results` +
-     * `create_search_row_subtitle`), over this dialog's live page subtree.
-     *
-     * The whole pipeline is `@gjsify/adwaita-core`'s, so this dialog and the
-     * NativeScript one answer identically for the same tree — including the
-     * three corpus filters (visible page → visible group → titled visible row)
-     * and the case fold that makes `strasse` find `Straße`.
+     * The preferences search (`filter_search_results` + `create_search_row_subtitle`),
+     * over this dialog's live page subtree. The pipeline is `@gjsify/adwaita-core`'s,
+     * including the three corpus filters (visible page → visible group → titled visible
+     * row) and the case fold that makes `strasse` find `Straße`.
      *
-     * An empty query returns the WHOLE corpus, which is what C does and what
-     * makes the results list non-empty before the user types.
+     * An empty query returns the WHOLE corpus, as C does, which is what makes the
+     * results list non-empty before the user types.
      */
     search(query: string, options?: SearchPreferencesOptions): PreferencesSearchResult<Element>[];
     connectedCallback(): void;

package/lib/types/elements/adw-preferences-group.d.ts

@@ -10,20 +10,19 @@ export declare class AdwPreferencesGroup extends HTMLElement {
     get description(): string;
     set description(value: string);
     /**
-     * `adw_preferences_group_add` (adw-preferences-group.c:396-411): a row goes
-     * into the boxed list, a `header-suffix` child into the header.
+     * `adw_preferences_group_add`: a row goes into the boxed list, a `header-suffix`
+     * child into the header.
      *
-     * Exposed as a method AND wired to a `MutationObserver` on the host, because
-     * both spellings occur: `group.addRow(row)` in code, `group.append(row)` in
-     * a framework's rendering. Before this, a child appended after connect
-     * stayed a bare child of the host — outside the card, and invisible to the
-     * row count that decides whether the card is painted at all.
+     * Exposed as a method AND wired to a `MutationObserver` on the host, because both
+     * spellings occur — `group.addRow(row)` in code, `group.append(row)` from a
+     * framework's rendering — and a bare child of the host would sit outside the card,
+     * invisible to the row count that decides whether the card is painted at all.
      */
     addRow(child: Node): void;
     /**
-     * `adw_preferences_group_remove` (:421-440). C logs
-     * `ADW_CRITICAL_CANNOT_REMOVE_CHILD` and no-ops for a child it does not
-     * own; returning `false` is the same contract without a console write.
+     * `adw_preferences_group_remove`. C logs `ADW_CRITICAL_CANNOT_REMOVE_CHILD` and
+     * no-ops for a child it does not own; returning `false` is the same contract
+     * without a console write.
      */
     removeRow(child: Node): boolean;
     connectedCallback(): void;
@@ -33,10 +32,9 @@ export declare class AdwPreferencesGroup extends HTMLElement {
      * Adopt children appended to the HOST after the subtree was built, so
      * `group.append(row)` behaves like `adw_preferences_group_add`.
      *
-     * C gets this for free — `gtk_widget_observe_children` on the listbox drives
-     * `update_listbox_visibility` through `items-changed`
-     * (adw-preferences-group.c:335-339) — and a DOM element needs the observer
-     * to have the same rule hold over time rather than only at connect.
+     * C gets this for free: `gtk_widget_observe_children` on the listbox drives
+     * `update_listbox_visibility` through `items-changed`. A DOM element needs the
+     * observer for the same rule to hold over time rather than only at connect.
      */
     private _observeHost;
     private _renderHeader;

package/lib/types/elements/adw-progress-bar.d.ts

@@ -26,10 +26,9 @@ export declare class AdwProgressBar extends HTMLElement {
     get disabled(): boolean;
     set disabled(value: boolean);
     /**
-     * Switch the bar to indeterminate — GtkProgressBar's method name for the
-     * same intent. See the module header: the bouncing block is a CSS animation
-     * here, so this ENTERS the state and repeat calls are no-ops; GTK's
-     * `pulse-step` arithmetic is not verifiable in this tree and is not faked.
+     * Switch the bar to indeterminate — GtkProgressBar's method name for the same
+     * intent. The bouncing block is a CSS animation here, so this ENTERS the state and
+     * repeat calls are no-ops (see the module header).
      */
     pulse(): void;
     connectedCallback(): void;

package/lib/types/elements/adw-shortcut-label.d.ts

@@ -0,0 +1,20 @@
+export declare class AdwShortcutLabel extends HTMLElement {
+    private _initialized;
+    static get observedAttributes(): string[];
+    connectedCallback(): void;
+    attributeChangedCallback(name: string): void;
+    get accelerator(): string;
+    set accelerator(value: string);
+    get disabledText(): string;
+    set disabledText(value: string);
+    private _render;
+    /**
+     * The rendered direction, which is what the sequence arrow follows.
+     *
+     * `getComputedStyle` is the only thing that sees an inherited `dir` — the
+     * attribute alone is set on an ancestor most of the time. A detached element
+     * has no computed style to read, so the attribute is the fallback.
+     */
+    private _direction;
+    private _nodeElement;
+}