@gjsify/adwaita-web 0.36.0 → 0.37.0

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

@@ -17,12 +17,10 @@ export declare class AdwSidebar extends HTMLElement {
     /** Guards the `selected` attribute write we make ourselves from re-entering. */
     private _reflecting;
     static get observedAttributes(): string[];
-    /** Zero-based flat index of the selected item, or -1 for no selection. */
     get selected(): number;
     set selected(value: number);
     /** The selected item's spec, or undefined — Adw.Sidebar:selected-item. */
     get selectedItem(): AdwSidebarItemSpec | undefined;
-    /** 'sidebar' (flat navigation list) or 'page' (boxed lists). */
     get mode(): 'sidebar' | 'page';
     set mode(value: 'sidebar' | 'page');
     /** The section/item model. Assigning replaces it, the way adw_sidebar_remove_all + append would. */
@@ -34,25 +32,22 @@ export declare class AdwSidebar extends HTMLElement {
     connectedCallback(): void;
     attributeChangedCallback(name: string): void;
     /**
-     * Re-derive after a declared `<adw-sidebar-item>` / `<adw-sidebar-section>`
-     * attribute changed. The item model keeps its shape, so the selection cannot
-     * move — exactly like the GObject property bindings this stands in for.
+     * Re-derive after a declared `<adw-sidebar-item>` / `<adw-sidebar-section>` attribute
+     * changed. The item model keeps its shape, so the selection cannot move — exactly
+     * like the GObject property bindings this stands in for.
      */
     refresh(): void;
-    /** Snapshot the declared children into specs, and bind them for live updates. */
     private _readDeclaredSections;
     private _readModeAttr;
     /**
      * `parseFloat`, not `parseInt`: the core rejects a fractional position, and
-     * truncating `"1.5"` to row 1 here would hide that from it. An unparseable
-     * value is NaN, which the core turns into "no selection".
+     * truncating `"1.5"` to row 1 here would hide that from it. An unparseable value is
+     * NaN, which the core turns into "no selection".
      */
     private _readSelectedAttr;
     private _reflectSelected;
     private _onSelectionChanged;
-    /** Click handler — the core applies the selection, then `activated` fires. */
     private _activate;
-    /** Rebuild the rendered rows + headers from the core's derived model. */
     private _rebuild;
     private _createHeader;
     private _createRow;

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

@@ -13,11 +13,9 @@ export declare class AdwSpinner extends HTMLElement {
     disconnectedCallback(): void;
     attributeChangedCallback(): void;
     /**
-     * Draw the frame for `now`, in `requestAnimationFrame` timebase.
-     *
-     * Public because the shared ticker is a module-level function rather than a
-     * method — and because a test needs to place the spinner at a known moment
-     * without waiting for real frames.
+     * Draw the frame for `now`, in `requestAnimationFrame` timebase. Public because the
+     * shared ticker is a module-level function, and because a test needs to place the
+     * spinner at a known moment without waiting for real frames.
      */
     drawAt(now: number): void;
     private _build;

package/lib/types/elements/adw-split-button.d.ts

@@ -12,7 +12,6 @@ export declare class AdwSplitButton extends HTMLElement {
     private _openReflected;
     private _initialized;
     static get observedAttributes(): string[];
-    /** Whether the dropdown menu is currently open. */
     get active(): boolean;
     /** Whether the dropdown half is live (there is a menu to show). */
     get dropdownEnabled(): boolean;
@@ -22,16 +21,13 @@ export declare class AdwSplitButton extends HTMLElement {
     /** The symbolic icon name, or `null` when the action half shows a label or nothing. */
     get iconName(): string | null;
     set iconName(value: string);
-    /** The dropdown menu entries. */
     get menuItems(): readonly AdwMenuEntry[];
     set menuItems(value: readonly AdwMenuEntry[]);
     /** The dropdown tooltip as set — `''` while unset. */
     get dropdownTooltip(): string;
     set dropdownTooltip(value: string);
-    /** The direction the popup opens in, and the arrow points. */
     get direction(): SplitButtonDirection;
     set direction(value: SplitButtonDirection);
-    /** Whether an underline in the label marks a mnemonic. */
     get useUnderline(): boolean;
     set useUnderline(value: boolean);
     /** Pop the menu up — `adw_split_button_popup()`. */
@@ -40,25 +36,19 @@ export declare class AdwSplitButton extends HTMLElement {
     popdown(): void;
     connectedCallback(): void;
     attributeChangedCallback(name: string, _previous: string | null, value: string | null): void;
-    /** Seed label/icon/menu/direction/tooltip from the attributes present at connect time. */
     private _syncStateFromAttributes;
     /**
-     * Route a `label` / `icon-name` attribute mutation into the content machine.
-     *
-     * C has no independent "unset" for either slot — clearing one is a side
-     * effect of setting another — so a REMOVED attribute falls back to whichever
-     * sibling is still present, and to the empty child otherwise. That fallback
-     * is what makes `removeAttribute('label')` actually drop the label; it used
-     * to be a silent no-op, so the storybook's icon-only mode rendered the icon
-     * next to a stale "Save".
+     * Route a `label` / `icon-name` attribute mutation into the content machine. C has no
+     * independent "unset" for either slot — clearing one is a side effect of setting
+     * another — so a REMOVED attribute falls back to whichever sibling is still present,
+     * and to the empty child otherwise. Without that fallback
+     * `removeAttribute('label')` is a silent no-op and an icon-only button keeps a stale
+     * label beside its icon.
      */
     private _applyContentAttribute;
     private _onStateChange;
     private _render;
-    /** The action half + the root style classes libadwaita derives from it. */
     private _renderContent;
-    /** The dropdown half: arrow glyph, tooltip/accessible name, expanded state. */
     private _renderDropdown;
-    /** The popover contents, one button per menu entry, dispatched BY POSITION. */
     private _renderMenu;
 }

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

@@ -12,9 +12,9 @@ export declare class AdwSwitchRow extends HTMLElement {
     connectedCallback(): void;
     attributeChangedCallback(name: string): void;
     /**
-     * Push a state transition out to the DOM and emit `notify::active` — but
-     * only when something actually changed, which is the `g_object_notify`
-     * gate libadwaita puts on the same transition (C:224-225 → :76).
+     * Push a state transition out to the DOM and emit `notify::active`, but only when
+     * something actually changed — the `g_object_notify` gate libadwaita puts on the same
+     * transition.
      */
     private _apply;
     private _renderText;

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

@@ -1,13 +1,11 @@
 import type { AdwTabPageSpec, AdwTabPageState } from '@gjsify/adwaita-core';
-/** A page descriptor as `pages` exposes it. */
 export type AdwTabViewPage = AdwTabPageState<HTMLElement>;
-/** The page spec the imperative insertion methods take. */
 export type AdwTabViewPageSpec = AdwTabPageSpec<HTMLElement>;
 /**
- * A single page. Declared as a child of <adw-tab-view>; the element itself
- * becomes the page panel, so its attributes keep driving the tab after connect —
- * the old implementation moved the children out and discarded the element, which
- * is why its `observedAttributes` declaration had nothing to act on.
+ * A single page. Declared as a child of <adw-tab-view>; the element itself becomes the
+ * page panel, so its attributes keep driving the tab after connect — a renderer that
+ * moves the children out and discards the element leaves `observedAttributes` with
+ * nothing to act on.
  */
 export declare class AdwTabPage extends HTMLElement {
     static get observedAttributes(): string[];
@@ -38,7 +36,6 @@ export declare class AdwTabView extends HTMLElement {
      */
     get autohide(): boolean;
     set autohide(value: boolean);
-    /** Whether tabs stretch to fill the bar evenly (Adw.TabBar `expand-tabs`). */
     get expandTabs(): boolean;
     set expandTabs(value: boolean);
     /** Whether the close affordance is omitted (static tab sets). */
@@ -51,17 +48,13 @@ export declare class AdwTabView extends HTMLElement {
      * {@link AdwTabPage.attributeChangedCallback}; not part of the public API.
      */
     syncDeclaredPage(pageEl: AdwTabPage, name: string, value: string | null): void;
-    /** All pages in order. */
     get pages(): readonly AdwTabViewPage[];
-    /** Number of pages. */
     get nPages(): number;
-    /** Length of the pinned prefix. */
     get nPinnedPages(): number;
     /** Id of the selected page, `null` when the view is empty. */
     get selectedId(): string | null;
     /** Index of the selected page, `-1` when the view is empty. */
     get selectedIndex(): number;
-    /** The selected page's panel element, or `null`. */
     get selectedContent(): HTMLElement | null;
     isClosing(id: string): boolean;
     setSelectedPage(id: string | null): boolean;
@@ -113,14 +106,13 @@ export declare class AdwTabView extends HTMLElement {
     private _nextId;
     private _onPagesChange;
     private _insertTab;
-    /** Remove-then-insert, the same shape the model's own reorder has. */
     private _moveTab;
     private _refreshTab;
     /**
-     * `tabCloseVisible` (adw-tab.c:124 + the pinned gate at :645-650). `dragging`
-     * is constantly false — tab drag-and-drop is compositor work and is not
-     * modelled — and `fullyVisible` is measured against the bar's scroll window,
-     * which is exactly what the C term means for a horizontally scrolled bar.
+     * `tabCloseVisible`, with its pinned gate. `dragging` is constantly false — tab
+     * drag-and-drop is compositor work and is not modelled — and `fullyVisible` is
+     * measured against the bar's scroll window, which is what the C term means for a
+     * horizontally scrolled bar.
      */
     private _refreshCloseVisibility;
     private _onSelectionChange;
@@ -129,19 +121,17 @@ export declare class AdwTabView extends HTMLElement {
     private _reflectSelected;
     private _applySelectedAttribute;
     /**
-     * The `Adw.TabView` shortcut table (`init_shortcuts`, adw-tab-view.c:2192+),
-     * plus the ArrowLeft/ArrowRight movement `role=tablist` promises.
-     *
-     * Ctrl+Tab WRAPS and Ctrl+Page-Up/Down does not — the same `last` flag that
-     * separates them in `select_page_cb` (:2017-2041). Alt+0 is page index 9,
-     * because pages count from 0 (:2149-2150).
+     * The `Adw.TabView` shortcut table (`init_shortcuts`), plus the ArrowLeft/ArrowRight
+     * movement `role=tablist` promises. Ctrl+Tab WRAPS and Ctrl+Page-Up/Down does not —
+     * the same `last` flag that separates them in `select_page_cb`. Alt+0 is page index
+     * 9, because pages count from 0.
      */
     private _onKeyDown;
     /**
-     * The `close-page` seam. A CANCELABLE DOM event is the idiomatic spelling of
-     * the C signal's return value: letting it through takes libadwaita's default
-     * (`!pinned`, adw-tab-view.c:1990-1991), and `preventDefault()` defers the
-     * close until the app calls {@link closePageFinish}.
+     * The `close-page` seam. A CANCELABLE DOM event is the idiomatic spelling of the C
+     * signal's return value: letting it through takes libadwaita's default (`!pinned`),
+     * and `preventDefault()` defers the close until the app calls
+     * {@link closePageFinish}.
      */
     private _requestClose;
 }

package/lib/types/elements/adw-toast-overlay.d.ts

@@ -36,16 +36,12 @@ export declare class AdwToastOverlay extends HTMLElement {
     /** Number of toasts queued behind the visible one. */
     get pendingToasts(): number;
     /**
-     * Show a toast notification — the web equivalent of Adw.ToastOverlay.add_toast()
-     * with a freshly-built Adw.Toast.
+     * Show a toast — the web equivalent of Adw.ToastOverlay.add_toast() with a
+     * freshly-built Adw.Toast. Only ONE toast is visible at a time; this one shows
+     * immediately when the slot is free, otherwise it waits its turn.
      *
-     * Like Adw.ToastOverlay, only ONE toast is visible at a time: this one shows
-     * immediately when the slot is free, otherwise it waits its turn behind the
-     * toasts already queued.
-     *
-     * @param title   The text to display.
-     * @param options Either a timeout in milliseconds (legacy shorthand) or an
-     *                {@link AdwToastOptions} bag (title text already supplied here).
+     * `options` is either an {@link AdwToastOptions} bag or, as a legacy shorthand, a
+     * timeout in MILLISECONDS.
      */
     addToast(title: string, options?: number | AdwToastOptions): void;
     /** Dismiss the visible toast early; the next queued toast takes its place. */
@@ -55,10 +51,9 @@ export declare class AdwToastOverlay extends HTMLElement {
     /** Build + attach the strip for `toast` — the DOM half of the queue's `onShow`. */
     private _mountToast;
     /**
-     * Detach the mounted strip — the DOM half of the queue's `onHide`.
-     *
-     * @param immediate Skip the exit transition because the next queued toast is
-     *                  about to take this slot (keeps exactly one strip mounted).
+     * Detach the mounted strip — the DOM half of the queue's `onHide`. `immediate`
+     * skips the exit transition because the next queued toast is about to take this
+     * slot, which is what keeps exactly one strip mounted.
      */
     private _unmountToast;
 }

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

@@ -1,54 +1,44 @@
 import type { AdwViewStackPageInfo as CorePageInfo } from '@gjsify/adwaita-core';
-/** A page descriptor exposed via `pages` (consumed by a bound switcher bar). */
 export type AdwViewStackPageInfo = CorePageInfo<HTMLElement>;
 export declare class AdwViewStack extends HTMLElement {
     private readonly _state;
     private _initialized;
     static get observedAttributes(): string[];
     constructor();
-    /** All pages in declaration/add order. A bound switcher reads this. */
     get pages(): readonly AdwViewStackPageInfo[];
     /** Zero-based index of the visible page, `-1` when nothing is selected. */
     get visibleChildIndex(): number;
     set visibleChildIndex(value: number);
-    /** Name of the visible page, or '' when nothing is selected. */
     get visibleChildName(): string;
     set visibleChildName(name: string | null | undefined);
-    /** The visible page's content element, or null when nothing is selected. */
     get visibleChild(): HTMLElement | null;
     connectedCallback(): void;
     attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
     /**
      * Append a page. It becomes visible when nothing is selected yet, matching
-     * `Adw.ViewStack.add()` — and, unlike before, that auto-pick NOTIFIES.
+     * `Adw.ViewStack.add()`, and that auto-pick NOTIFIES.
      */
     add(content: HTMLElement, name: string, title?: string, icon?: string): AdwViewStackPageInfo;
-    /** Convenience alias mirroring Adw.ViewStack.add_titled() (no icon). */
     addTitled(content: HTMLElement, name: string, title: string): AdwViewStackPageInfo;
     /**
      * Remove the first page named `name` and detach its content. Returns whether
      * anything was removed. When the removed page was the visible one the stack
      * ends up showing NOTHING and emits no event — `stack_remove` clears
-     * `visible_child` without re-picking (adw-view-stack.c:1202-1203).
+     * `visible_child` without re-picking.
      */
     removePage(name: string): boolean;
     /**
      * Show or hide a page (`AdwViewStackPage:visible`). Returns whether the
      * SELECTION moved: hiding the visible page falls back to the next visible
      * one, and making a page visible while nothing is selected selects it
-     * (`update_child_visible`, adw-view-stack.c:1061-1082).
+     * (`update_child_visible`).
      */
     setPageVisible(name: string, visible: boolean): boolean;
     /**
-     * The pages model's `items-changed`, which the DOM stack had no counterpart
-     * for at all.
-     *
-     * `AdwViewSwitcherBar` re-runs `update_bar_revealed` on it
-     * (adw-view-switcher-bar.c:340) and `AdwViewSwitcher` rebinds its buttons
-     * (adw-view-switcher.c:258-263). Both ports listened only on
-     * `notify::visible-child`, so adding a page or hiding a non-selected one
-     * left `revealed` — and the button row — stale, with a manual `refresh()`
-     * as the documented workaround.
+     * The pages model's `items-changed`: `AdwViewSwitcherBar` re-runs
+     * `update_bar_revealed` on it and `AdwViewSwitcher` rebinds its buttons. A listener
+     * on `notify::visible-child` alone leaves `revealed` and the button row stale when a
+     * page is added or a non-selected one hidden.
      */
     private _emitItemsChanged;
     private _onStateChange;

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

@@ -16,7 +16,7 @@ export declare class AdwViewSwitcherBar extends HTMLElement {
     set reveal(value: boolean);
     /**
      * Whether the bar is actually shown. READ-ONLY: a one-page stack keeps it
-     * collapsed however loudly the layout asks (adw-view-switcher-bar.c:125).
+     * collapsed however loudly the layout asks.
      * Write {@link reveal} to make the request.
      */
     get revealed(): boolean;
@@ -26,13 +26,9 @@ export declare class AdwViewSwitcherBar extends HTMLElement {
     /** Bind to a stack element (or null). Unbinds the previous one and rebuilds. */
     setStack(stack: AdwViewStack | null): void;
     /**
-     * Rebuild the buttons by hand.
-     *
-     * Kept as public API — a consumer that mutates a page in place still has a
-     * way to say so — but no longer the ONLY way: the stack emits
-     * `items-changed` now and this bar binds it, which is the mechanism
-     * libadwaita uses (adw-view-switcher-bar.c:340,
-     * adw-view-switcher.c:258-263).
+     * Rebuild the buttons by hand — public API for a consumer that mutated a page in
+     * place. Not the only path: the stack emits `items-changed` and this bar binds it,
+     * which is the mechanism libadwaita uses.
      */
     refresh(): void;
     private _readReveal;

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

@@ -3,29 +3,19 @@ import type { AdwViewSwitcherPage as AdwViewSwitcherPageInfo, AdwViewSwitcherPol
 /**
  * A single page. Children of `<adw-view-switcher>`; consumed at connect time.
  *
- * Deliberately carries NO `observedAttributes`. It used to declare six of them
- * and no `attributeChangedCallback`, which is a dead declaration — the browser
- * computes the list and has nowhere to deliver to — so changing `badge-number`,
- * `title`, `icon-name` or `needs-attention` after connect did nothing at all,
- * where C rebinds on every page `notify` (adw-view-switcher.c:184-193, :223).
- *
- * A callback could not fix it either: the switcher consumes these elements at
- * connect and `replaceChildren`s them away, so a detached page has no `closest`
- * to reach its owner through. The switcher watches them with a `MutationObserver`
- * instead, which keeps working after the detach and needs nothing from this class.
+ * Deliberately carries NO `observedAttributes` and no `attributeChangedCallback`:
+ * the switcher consumes these elements at connect and `replaceChildren`s them
+ * away, so a detached page has no `closest` to reach its owner through. The
+ * switcher watches them with a `MutationObserver` instead — the DOM stand-in for
+ * the per-page `notify` C rebinds on.
  */
 export declare class AdwViewSwitcherPage extends HTMLElement {
 }
 export declare class AdwViewSwitcher 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 so a test can hand in a clock and drive
+     * `VIEW_SWITCHER_DRAG_VECTORS` against the real element. Replace it before the
+     * element connects.
      */
     scheduler: ViewSwitcherScheduler;
     private _stateInstance;
@@ -41,46 +31,36 @@ export declare class AdwViewSwitcher extends HTMLElement {
     private _initialized;
     static get observedAttributes(): string[];
     constructor();
-    /** The policy controlling the button layout ('wide' | 'narrow'). */
     get policy(): AdwViewSwitcherPolicy;
     set policy(value: AdwViewSwitcherPolicy);
     /** Zero-based index of the selected page, `-1` when nothing is selected. */
     get active(): number;
     set active(value: number);
-    /** Name of the selected page, `''` when nothing is selected. */
     get visibleChildName(): string;
     set visibleChildName(name: string | null | undefined);
-    /** The resolved page records a bound layout can read. */
     get pages(): readonly AdwViewSwitcherPageInfo[];
     /**
      * Show or hide a page (`AdwViewStackPage:visible`). Returns whether the
      * SELECTION moved — hiding the selected page falls back to the first still
-     * visible one (adw-view-stack.c:1061-1082).
+     * visible one.
      */
     setPageVisible(name: string, visible: boolean): boolean;
     connectedCallback(): void;
     disconnectedCallback(): void;
     /**
-     * Re-read every declared page and push it into the state.
-     *
-     * Called by `AdwViewSwitcherPage.attributeChangedCallback`, which is what
-     * makes a runtime `badge-number` change reach the button. `setPages` keeps
-     * the selection where it can, so this is a repaint and not a reset.
+     * Re-read every declared page and push it into the state. Driven by the
+     * `MutationObserver` in {@link _watchPages}, which is what makes a runtime
+     * `badge-number` change reach the button. `setPages` keeps the selection where it
+     * can, so this is a repaint and not a reset.
      */
     refreshPages(): void;
     /**
-     * Watch the declared pages for attribute changes.
-     *
-     * A `MutationObserver` rather than an `attributeChangedCallback` on the page:
-     * the switcher consumes those elements at connect and `replaceChildren`s them
-     * out of the tree, so a detached page cannot find its owner — but an observer
-     * bound to it keeps firing. This is the DOM's `notify::` on
-     * `AdwViewStackPage`, which the C's `update_button` handler binds per page
-     * (adw-view-switcher.c:184-193).
+     * Watch the declared pages for attribute changes — the DOM's `notify::` on
+     * `AdwViewStackPage`, which C's `update_button` binds per page. See
+     * {@link AdwViewSwitcherPage} for why an observer and not a callback.
      *
-     * It delivers on a MICROTASK where GTK's notify is synchronous. That is the
-     * DOM's contract for watching a node, it is invisible to a user, and nothing
-     * in this element reads the button back inside the setter.
+     * MODIFICATION: delivers on a MICROTASK where GTK's notify is synchronous —
+     * invisible to a user, and nothing here reads the button back inside a setter.
      */
     private _watchPages;
     attributeChangedCallback(name: string): void;

package/lib/types/elements/adw-wrap-box.d.ts

@@ -1,23 +1,20 @@
 import { type AdwLengthUnit } from '@gjsify/adwaita-core';
 export declare class AdwWrapBox extends HTMLElement {
     private _initialized;
-    static get observedAttributes(): ("align" | "justify" | "justify-last-line" | "child-spacing" | "line-spacing" | "orientation" | "wrap-policy" | "child-spacing-unit" | "natural-line-length" | "pack-direction" | "wrap-reverse" | "line-spacing-unit" | "line-homogeneous" | "natural-line-length-unit")[];
+    static get observedAttributes(): ("align" | "child-spacing" | "child-spacing-unit" | "pack-direction" | "justify" | "justify-last-line" | "line-spacing" | "line-spacing-unit" | "line-homogeneous" | "natural-line-length" | "natural-line-length-unit" | "wrap-reverse" | "wrap-policy" | "orientation")[];
     /** Spacing between children on the same line, in `child-spacing-unit`. */
     get childSpacing(): number;
     set childSpacing(value: number);
-    /** The unit `child-spacing` is written in. Defaults to `px`, as in C. */
     get childSpacingUnit(): AdwLengthUnit;
     set childSpacingUnit(value: AdwLengthUnit);
     /** Spacing between lines, in `line-spacing-unit`. */
     get lineSpacing(): number;
     set lineSpacing(value: number);
-    /** The unit `line-spacing` is written in. Defaults to `px`, as in C. */
     get lineSpacingUnit(): AdwLengthUnit;
     set lineSpacingUnit(value: AdwLengthUnit);
     /** Where the children sit ALONG the line (main axis): 0 start, 0.5 middle, 1 end. */
     get align(): number;
     set align(value: number);
-    /** Whether and how each line is stretched to fill the widget. */
     get justify(): 'none' | 'fill' | 'spread';
     set justify(value: 'none' | 'fill' | 'spread');
     /** Whether the FINAL line is justified too. Default false, as in C. */
@@ -26,38 +23,31 @@ export declare class AdwWrapBox extends HTMLElement {
     /** Whether an overflowing line squeezes its children or lets them spill. */
     get wrapPolicy(): 'minimum' | 'natural';
     set wrapPolicy(value: 'minimum' | 'natural');
-    /** The direction children are packed in each line. */
     get packDirection(): 'start-to-end' | 'end-to-start';
     set packDirection(value: 'start-to-end' | 'end-to-start');
     /** Whether lines wrap upwards (horizontal) / towards the start (vertical). */
     get wrapReverse(): boolean;
     set wrapReverse(value: boolean);
-    /** Whether every line takes the same amount of space. */
     get lineHomogeneous(): boolean;
     set lineHomogeneous(value: boolean);
     /** The natural line length in `natural-line-length-unit`, or `-1` when unset. */
     get naturalLineLength(): number;
     set naturalLineLength(value: number);
-    /** The unit `natural-line-length` is written in. Defaults to `px`, as in C. */
     get naturalLineLengthUnit(): AdwLengthUnit;
     set naturalLineLengthUnit(value: AdwLengthUnit);
-    /** The axis children are packed along. */
     get orientation(): 'horizontal' | 'vertical';
     set orientation(value: 'horizontal' | 'vertical');
-    /** The element children, which are what the layout actually lays out. */
     private get _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`.
+     * `adw_wrap_box_insert_child_after`. 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): boolean;
-    /** `adw_wrap_box_reorder_child_after` (adw-wrap-box.c:1315-1332). Same NULL rule. */
+    /** `adw_wrap_box_reorder_child_after`. Same NULL rule. */
     reorderChildAfter(child: Element, sibling?: Element | null): boolean;
-    /** `adw_wrap_box_remove_all` (adw-wrap-box.c:1406-1414). */
+    /** `adw_wrap_box_remove_all`. */
     removeAll(): void;
     private _applyOrder;
     connectedCallback(): void;

package/lib/types/elements/view-switcher-dom.d.ts

@@ -1,11 +1,9 @@
 import type { AdwViewSwitcherPageInit, ViewSwitcherScheduler } from '@gjsify/adwaita-core';
 import { type AdwIcon } 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.
+ * 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 declare const domViewSwitcherScheduler: ViewSwitcherScheduler;
 /**
@@ -23,22 +21,21 @@ export declare function applySwitcherIcon(icon: AdwIcon, iconName: string): void
 /**
  * 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.
+ * `getAttribute` returns `null` for an absent attribute, which is EXACTLY C's NULL, so
+ * values are passed through unchanged rather than defaulted to `''`. Do not add a
+ * `?? ''`: once an absent title has become the empty string, "the page has no title" is
+ * no longer expressible and the button-visibility rule cannot be implemented.
  */
 export declare function readSwitcherPage(element: Element): AdwViewSwitcherPageInit;
 /**
  * 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).
+ * one, a bare dot when only `needs-attention` is set, nothing otherwise — C's
+ * `AdwIndicatorBin` plus the `.needs-attention` style class.
  */
 export declare function applyIndicator(indicator: HTMLElement, badgeLabel: string, needsAttention: boolean): void;
 /**
  * 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).
+ * property rather than setting it to `""`.
  */
 export declare function applyDescription(element: HTMLElement, description: string): void;

package/lib/types/index.d.ts

@@ -17,6 +17,7 @@ export { AdwIcon, createAdwIcon } from './elements/adw-icon.js';
 export { AdwSwitch } from './elements/adw-switch.js';
 export { AdwCheckbox, AdwRadio } from './elements/adw-checks.js';
 export { AdwProgressBar } from './elements/adw-progress-bar.js';
+export { AdwShortcutLabel } from './elements/adw-shortcut-label.js';
 export { AdwPopover } from './elements/adw-popover.js';
 export type { AdwPopoverAlign, AdwPopoverPosition, AdwPopoverRole } from './elements/adw-popover.js';
 export { AdwSplitButton } from './elements/adw-split-button.js';

package/lib/types/source-view/hex.d.ts

@@ -1,22 +1,16 @@
 /** Bytes represented per visual line in the hex monitor / hexdump gutter. */
 export declare const HEX_ADDRESS_STRIDE = 16;
 /**
- * Format a 1-based CodeMirror line number as a 4-digit uppercase hex address,
- * the way the native GtkSourceView hex gutter renders monitor/hexdump rows:
- * each row advances the address by `stride` bytes from `start`.
- *
- * @param lineNo 1-based line number (CodeMirror's `formatNumber` contract).
- * @param start  base address of the first row (e.g. 0x0600 for a 6502 program).
- * @param stride bytes per row (default 16 — one hexdump row).
+ * Format a 1-based CodeMirror line number as a 4-digit uppercase hex address, the way the
+ * native GtkSourceView hex gutter renders monitor/hexdump rows: each row advances the
+ * address by `stride` bytes from `start` (the base address of the first row, e.g. 0x0600
+ * for a 6502 program). `lineNo` is 1-based, per CodeMirror's `formatNumber` contract.
  */
 export declare function formatHexAddress(lineNo: number, start: number, stride?: number): string;
 /**
- * Format a 1-based CodeMirror line number for the normal (decimal) gutter,
- * offset by `start` so a pane can begin numbering at an arbitrary value —
- * the web twin of the native renderer's `line + startValue`.
- *
- * @param lineNo 1-based line number.
- * @param start  value shown on the first line (default 1 → identity).
+ * Format a 1-based CodeMirror line number for the normal (decimal) gutter, offset so
+ * `start` is the value shown on the first line — the web twin of the native renderer's
+ * `line + startValue`.
  */
 export declare function formatLineNumber(lineNo: number, start?: number): string;
 /**

package/lib/types/style-classes.spec.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Every class `style-classes.md` documents, and what this package does about it.
+ *
+ * Keys are the bare class names, in the document's own spelling. The order is
+ * the document's, so the two can be read side by side.
+ */
+export declare const DOCUMENTED_STYLE_CLASSES: Record<string, {
+    shipped: boolean;
+    reason?: string;
+}>;
+export declare const AdwStyleClassesTest: () => Promise<void>;