@gjsify/adwaita-core 0.30.0 → 0.32.0

package/lib/types/index.d.ts

@@ -1,10 +1,49 @@
+export { ActionRowState, BUTTON_ROW_ACTIVATABLE, ButtonRowState, SwitchRowState, WindowTitleState, deriveRowLabels, } from './action-row.js';
+export type { ActionRowRenderState, AdwRowLabelInput, AdwRowLabels, ButtonRowRenderState, WindowTitleRenderState, } from './action-row.js';
+export { ADW_ABOUT_DIALOG_LABELS, ADW_CREDITS_SECTION_TITLES, ADW_LICENSES, ADW_LICENSE_ALIASES, ADW_LICENSE_DEFAULTS, ADW_LICENSE_WARRANTY_TEMPLATE, ADW_TRANSLATOR_CREDITS_SENTINELS, GTK_LICENSE, aboutDialogVisibility, creditsSections, isLicenseType, legalSectionVisible, licenseText, licenseTypeForSpdxId, parseCreditPerson, setLicense, setLicenseType, translatorCreditsPeople, } from './about-dialog.js';
+export type { AdwAboutDialogProps, AdwAboutDialogVisibility, AdwCreditPerson, AdwCreditsInput, AdwCreditsSection, AdwCreditsSectionInput, AdwLicenseAlias, AdwLicenseInfo, AdwLicenseNotify, AdwLicenseState, AdwLicenseTransition, AdwLicenseType, } from './about-dialog.js';
+export { AVATAR_COLOR_COUNT, AVATAR_COLORS, avatarColor, avatarColorClass, avatarFontSize, avatarInitials, avatarMaxFontSize, avatarMode, flattenAvatarGradient, gStrHash, randomAvatarColorClass, } from './avatar.js';
+export type { AdwAvatarColor, AdwAvatarMode } from './avatar.js';
+export { ADW_BANNER_BUTTON_STYLES, ADW_BANNER_BUTTON_STYLE_CLASSES, ADW_BANNER_DEFAULTS, bannerButtonStyleClasses, bannerButtonText, bannerButtonVisible, bannerRenderState, isBannerButtonStyle, parseBannerButtonStyle, } from './banner.js';
+export type { AdwBannerButtonStyle, AdwBannerProps, AdwBannerRenderState } from './banner.js';
+export { ADW_BUTTON_CONTENT_DEFAULTS, BUTTON_CONTENT_FALLBACK_ICON, BUTTON_CONTENT_STYLE_CLASS, buttonContentEllipsize, buttonContentIconExpands, buttonContentIconIsEmpty, buttonContentIconName, buttonContentLabelText, buttonContentLabelVisible, buttonContentRenderState, buttonContentStyleTargetIndex, } from './button-content.js';
+export type { AdwButtonContentProps, AdwButtonContentRenderState, ButtonContentAncestor, ButtonContentEllipsize, } from './button-content.js';
+export { RadioGroupState, resolveCheckState } from './checks.js';
+export type { AdwCheckState, RadioGroupChange, RadioGroupListener } from './checks.js';
 export { AdwBreakpoint, evaluateBreakpointCondition, parseBreakpointCondition } from './breakpoint.js';
 export type { AdwBreakpointHandlers, BreakpointBound, BreakpointConditionGroup, BreakpointConditionLeaf, BreakpointConditionNode, BreakpointDimension, BreakpointSize, } from './breakpoint.js';
 export { DEFAULT_ICON_COLOR, DEFAULT_ICON_COLOR_DARK, adwaitaColorScheme, isThemeIconColor, onAdwaitaColorSchemeChanged, setAdwaitaColorScheme, themeIconColor, toggleAdwaitaColorScheme, } from './color-scheme.js';
 export type { AdwColorScheme } from './color-scheme.js';
+export { ADW_DATA_GRID_ROW_VARIANTS, DATA_GRID_CELL_CLASS, DATA_GRID_ROW_CLASS, dataGridCellText, dataGridColumnAlign, dataGridColumnClasses, dataGridRowInteractive, dataGridTrackTemplate, dataGridTracks, normalizeDataGridColumns, normalizeDataGridVariant, } from './data-grid.js';
+export type { AdwDataGridAlign, AdwDataGridCellValue, AdwDataGridColumn, AdwDataGridRow, AdwDataGridRowVariant, DataGridTrack, } from './data-grid.js';
 export { AdwToast, AdwToastQueue, DEFAULT_TOAST_TIMEOUT } from './toast.js';
 export type { AdwToastOptions, AdwToastQueueHandlers, AdwToastQueueOptions, ToastScheduler, ToastTimerHandle, } from './toast.js';
-export { AdwAlertResponses } from './dialog.js';
-export type { AdwAlertResponse, AdwResponseAppearance, AdwResponseOptions, OrderedConfirmResponses } from './dialog.js';
-export { ComboState, ExpanderState, SpinState, ToggleGroupState } from './rows.js';
-export type { AdwComboOption, ComboStateChange, ComboStateListener, ExpanderStateListener, SpinStateChange, SpinStateListener, ToggleGroupStateChange, ToggleGroupStateListener, } from './rows.js';
+export { AdwAlertResponses, BottomSheetPresentation, resolveBottomSheetClose } from './dialog.js';
+export type { AdwAlertResponse, AdwResponseAppearance, AdwResponseOptions, BottomSheetCloseOutcome, BottomSheetCloseSource, BottomSheetCloseState, BottomSheetPresentationListener, BottomSheetPresentationOptions, BottomSheetTeardownCallback, OrderedConfirmResponses, } from './dialog.js';
+export { ComboState, ExpanderState, SpinState, ToggleGroupState, normalizeComboOptions } from './rows.js';
+export type { AdwComboOption, AdwComboOptionInput, ComboStateChange, ComboStateListener, ExpanderStateListener, SpinStateChange, SpinStateListener, ToggleGroupStateChange, ToggleGroupStateListener, } from './rows.js';
+export { glibClamp, gStrStrip, stringIsNotEmpty } from './glib.js';
+export { ViewStackState, normalizeIconName, resolvePageTitle } from './view-stack.js';
+export type { AdwViewStackPageInfo, AdwViewStackPageSpec, ViewStackStateChange, ViewStackStateListener, } from './view-stack.js';
+export { BACK_BUTTON_FALLBACK_TOOLTIP, NavigationViewState, describeNavigationDiagnostic } from './navigation-view.js';
+export type { AdwNavigationPageProps, NavigationChangeReason, NavigationDiagnostic, NavigationDiagnosticCode, NavigationDiagnosticListener, NavigationPagePropsResolver, NavigationShortcutResult, NavigationStackChange, NavigationStackListener, NavigationViewOptions, } from './navigation-view.js';
+export { ADW_SIDEBAR_NO_SELECTION, SidebarState, adjustSidebarSelection, clampSidebarSelection, flattenSidebarItems, sidebarHeaders, } from './sidebar.js';
+export type { AdwSidebarItemSpec, AdwSidebarMode, AdwSidebarSectionSpec, SidebarActivation, SidebarFlatItem, SidebarHeaderSpec, SidebarItemFilter, SidebarSelectionChange, SidebarStateListener, } from './sidebar.js';
+export { CAPS_LOCK_ICON_NAME, CAPS_LOCK_TOOLTIP, EMPTY_ANIMATION_DURATION_MS, ENTRY_ROW_APPLY_ICON_NAME, ENTRY_ROW_APPLY_TOOLTIP, ENTRY_ROW_EDIT_ICON_NAME, ENTRY_ROW_MAX_LENGTH_LIMIT, ENTRY_ROW_TITLE_SPACING, EntryRowState, PASSWORD_CONCEAL_ICON_NAME, PASSWORD_CONCEAL_LABEL, PASSWORD_REVEAL_ICON_NAME, PASSWORD_REVEAL_LABEL, PasswordEntryRowState, clampEntryText, entryTextLength, } from './entry-row.js';
+export type { EntryRowActivation, EntryRowRenderState, EntryRowStateListener, PasswordEntryRowRenderState, PasswordEntryRowStateListener, } from './entry-row.js';
+export { ADW_SWIPE_BORDER, DEFAULT_DPI, DEFAULT_MAX_SIDEBAR_WIDTH, DEFAULT_MIN_SIDEBAR_WIDTH, DEFAULT_SIDEBAR_WIDTH_FRACTION, DEFAULT_SIDEBAR_WIDTH_UNIT, INSTANT_SPLIT_VIEW_ANIMATOR, NAVIGATION_SPLIT_VIEW_CRITICALS, NavigationSplitViewState, OverlaySplitViewState, adwLengthToPx, isSidebarAtVisualStart, layoutNavigationSplitView, layoutOverlaySplitView, measureSplitViewHorizontal, resolveNaturalSidebarWidth, resolveNavigationAction, resolveNavigationSidebarWidth, resolveNavigationStack, resolveOverlaySidebarWidth, resolveSidebarBounds, resolveSwipeArea, resolveSwipeRelease, resolveSwipeSnapPoints, resolveSwipeStart, swipeCancelProgress, tagsConflict, } from './split-view.js';
+export type { AdwLengthUnit, AdwPackType, AdwTextDirection, NavigationActionInput, NavigationActionResult, NavigationPageRef, NavigationSplitViewChange, NavigationSplitViewHandlers, NavigationSplitViewLayout, NavigationSplitViewListener, NavigationSplitViewOptions, NavigationSplitViewProperty, NavigationStackPlan, OverlaySplitViewChange, OverlaySplitViewLayout, OverlaySplitViewListener, OverlaySplitViewOptions, OverlaySplitViewProperty, SidebarBounds, SidebarWidthInput, SidebarWidthSpec, SplitViewAnimation, SplitViewAnimationRequest, SplitViewAnimator, SplitViewMeasureInput, SplitViewPane, SplitViewPaneRect, SwipeReleasePlan, } from './split-view.js';
+export { DEFAULT_DROPDOWN_TOOLTIP, SPLIT_BUTTON_DISABLED_OPACITY, SplitButtonState, isSplitButtonDirection, menuButtonArrowIcon, menuButtonPopupDirection, parseMenuEntries, resolveDropdownTooltip, splitButtonArrowIcon, splitButtonPopupDirection, splitButtonRootState, splitButtonStyleClasses, } from './split-button.js';
+export type { AdwArrowIcon, AdwMenuEntry, SplitButtonChange, SplitButtonContentMode, SplitButtonDirection, SplitButtonHalfState, SplitButtonListener, SplitButtonProperty, SplitButtonStyleClass, } from './split-button.js';
+export { DEFAULT_INDICATOR_DESCRIPTION_STRINGS, INLINE_VIEW_SWITCHER_DISPLAY_MODES, VIEW_SWITCHER_BADGE_LIMIT, VIEW_SWITCHER_DRAG_SWITCH_DELAY, VIEW_SWITCHER_FALLBACK_ICON, VIEW_SWITCHER_NO_SELECTION, VIEW_SWITCHER_POLICIES, ViewSwitcherBarState, ViewSwitcherDragSwitch, ViewSwitcherState, buildInlineToggles, buildViewSwitcherButtons, createViewSwitcherPage, inlineToggleTooltip, isInlineViewSwitcherDisplayMode, isViewSwitcherButtonVisible, isViewSwitcherPolicy, pageIndexForToggle, shouldRevealViewSwitcherBar, stripMnemonic, toggleIndexForPage, viewSwitcherBadgeLabel, viewSwitcherButtonOrientation, viewSwitcherIconName, viewSwitcherIndicatorDescription, viewSwitcherLabel, viewSwitcherPageFromStackPage, viewSwitcherPagesFromStack, } from './view-switcher.js';
+export type { AdwInlineViewSwitcherDisplayMode, AdwViewSwitcherPage, AdwViewSwitcherPageInit, AdwViewSwitcherPolicy, IndicatorDescriptionStrings, InlineToggleModel, ViewSwitcherBarChange, ViewSwitcherBarListener, ViewSwitcherButtonModel, ViewSwitcherDragSwitchOptions, ViewSwitcherScheduler, ViewSwitcherStateChange, ViewSwitcherStateListener, ViewSwitcherStateOptions, ViewSwitcherTimerHandle, } from './view-switcher.js';
+export { DEFAULT_TAB_AUTOHIDE, TabViewState, isDescendantOfPage, successorAfterClose, tabCloseVisible, tabIconState, tabTooltip, tabTooltipIsMarkup, tabsRevealed, } from './tab-view.js';
+export type { AdwTabPageSpec, AdwTabPageState, TabIconState, TabViewHandlers, TabViewPagesChange, TabViewPagesChangeKind, TabViewPagesListener, TabViewSelectionChange, TabViewSelectionListener, } from './tab-view.js';
+export { CAROUSEL_SCROLL_TIMEOUT_MS, CAROUSEL_SETTLE_EPSILON, CarouselState, carouselClampPosition, carouselClosestSnapPoint, carouselNavigateTarget, carouselPageAtPosition, carouselRange, carouselReorderShift, carouselSizesFromSnapPoints, carouselSnapPoints, carouselWheelStep, } from './carousel.js';
+export type { CarouselChangeReason, CarouselDirection, CarouselOrientation, CarouselPageChangedListener, CarouselRange, CarouselReorderShiftInput, CarouselScrollOptions, CarouselScrollRequest, CarouselScrollSource, CarouselStateChange, CarouselStateListener, CarouselStateOptions, CarouselWheelInput, } from './carousel.js';
+export { UNTITLED_PAGE_LABEL, collectSearchRows, countVisiblePages, createSearchRowSubtitle, defaultCaseFolder, derivePreferencesGroupHeader, escapeMarkup, makeComparable, rowMatchesQuery, searchPreferences, stripMarkup, } from './preferences.js';
+export type { CaseFolder, MakeComparableOptions, PreferencesGroupHeaderInput, PreferencesGroupHeaderState, PreferencesSearchEntry, PreferencesSearchGroup, PreferencesSearchPage, PreferencesSearchResult, PreferencesSearchRow, SearchPreferencesOptions, SearchRowSubtitleInput, } from './preferences.js';
+export { ADW_CLAMP_DEFAULTS, ADW_CLAMP_SIZE_CLASSES, ADW_SPINNER_MAX_SIZE, ADW_SPINNER_MIN_SIZE, ADW_TOOLBAR_BAR_CLASSES, ADW_TOOLBAR_VIEW_CLASSES, ADW_TOOLBAR_VIEW_DEFAULTS, clampAllocate, clampChildSize, clampSizeFromChild, clampThresholds, normalizeClampSize, parseToolbarStyle, resolveSpinnerSize, spinnerGeometry, toolbarBarStyleClasses, toolbarViewAllocate, toolbarViewClasses, toolbarViewContentForSize, toolbarViewMeasure, } from './chrome.js';
+export type { AdwClampSizeClass, AdwMeasurement, AdwToolbarStyle, ClampAllocation, ClampParams, ClampThresholds, SpinnerGeometry, ToolbarViewAllocateInput, ToolbarViewAllocation, ToolbarViewClassInput, ToolbarViewClasses, ToolbarViewContentForSize, ToolbarViewContentForSizeInput, ToolbarViewMeasureInput, } from './chrome.js';
+export { POPOVER_ITEM_RADIUS, POPOVER_MENU_PADDING, POPOVER_PADDING, POPOVER_RADIUS, PopoverState, resolvePopoverKey, } from './popover.js';
+export type { PopoverKeyAction, PopoverKeyContext, PopoverKeyResolution, PopoverStateChange, PopoverStateListener, } from './popover.js';

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

@@ -0,0 +1,343 @@
+/** The three headless `AdwNavigationPage` properties a renderer registers a page with. */
+export interface AdwNavigationPageProps {
+    /**
+     * `AdwNavigationPage:tag` — unique within one view, or `null` for untagged.
+     * `''` is a legal tag: the C tag table is a plain `g_str_hash` table and only
+     * a NULL tag is skipped (add_page:1281).
+     */
+    tag?: string | null;
+    /** `AdwNavigationPage:title` — defaults to `''`, never null (adw_navigation_page_init:794). */
+    title?: string;
+    /** `AdwNavigationPage:can-pop` — defaults to `true` (adw_navigation_page_init:795). */
+    canPop?: boolean;
+}
+/**
+ * Why the stack moved. Maps 1:1 onto the C signals so a renderer can re-emit
+ * them without re-deriving the cause: `'add'`/`'push'` → `::pushed`, `'pop'` →
+ * one `::popped` per entry in {@link NavigationStackChange.popped}, `'replace'` →
+ * `::replaced`. `'add'` is split out from `'push'` only because it is the
+ * auto-push add_page:1284-1285 performs, which is never animated.
+ */
+export type NavigationChangeReason = 'add' | 'push' | 'pop' | 'replace';
+/** One stack mutation, as a single payload. */
+export interface NavigationStackChange<P> {
+    /** The new navigation stack, bottom-first (`adw_navigation_view_get_navigation_stack`). */
+    stack: readonly P[];
+    /** The new visible page — the top of {@link stack} — or `null` for an empty stack. */
+    visiblePage: P | null;
+    /** {@link visiblePage}'s tag, or `null`. Never `''` for an untagged page. */
+    visiblePageTag: string | null;
+    /**
+     * The page that was visible before this mutation. `previousVisiblePage !==
+     * visiblePage` is exactly the condition under which libadwaita notifies
+     * `visible-page` — including the `replace()` corner where the old visible
+     * page was destroyed rather than switched away from (replace:3078-3079).
+     */
+    previousVisiblePage: P | null;
+    /** Why the stack moved. */
+    reason: NavigationChangeReason;
+    /**
+     * The popped pages, TOP-FIRST — `::popped` is emitted in this order.
+     * pop_from_stack:989-994 builds the list with `g_slist_prepend` while walking
+     * bottom-up, then iterates it forward. Always empty unless `reason` is `'pop'`.
+     */
+    popped: readonly P[];
+    /** Pages unregistered by this mutation — the renderer destroys their views now. */
+    removed: readonly P[];
+    /**
+     * The outgoing visible page, destroyed only once the transition finishes
+     * (pop_from_stack:1007 skips it; transition_done_cb:1042 does it). The
+     * renderer hands it back by calling {@link NavigationViewState.finishTransition}.
+     */
+    removeAfterTransition: P | null;
+    /**
+     * Whether this transition animates. `false` for the auto-push (add_page:1285),
+     * for every `replace()` (replace:3075), and whenever there is no outgoing page
+     * to slide away from (switch_page:857-858).
+     */
+    animate: boolean;
+    /** Transition direction: `true` when the new page comes from BELOW (pop/replace). */
+    pop: boolean;
+    /**
+     * Whether `visible-page-tag` re-notifies: switch_page:927-930 notifies only
+     * when the outgoing OR the incoming page carries a tag.
+     */
+    tagNotify: boolean;
+}
+/** The four `g_critical` sites of the family, as structured data. */
+export type NavigationDiagnosticCode = 'duplicate-tag' | 'already-in-stack' | 'tag-not-found' | 'not-in-stack';
+/**
+ * A rejected mutation. Replaces `g_critical`: today web writes `console.warn`
+ * with two of the four cases and NS is silent, which is itself a divergence.
+ */
+export interface NavigationDiagnostic {
+    /** Which rule rejected the call. */
+    code: NavigationDiagnosticCode;
+    /** The offending tag, where the C message names one. */
+    tag?: string | null;
+    /** The offending page's title, where the C message names one instead. */
+    title?: string;
+}
+/** Subscriber for {@link NavigationViewState} stack changes. */
+export type NavigationStackListener<P> = (change: NavigationStackChange<P>) => void;
+/** Sink for rejected mutations — the injected `g_critical`. */
+export type NavigationDiagnosticListener = (diagnostic: NavigationDiagnostic) => void;
+/**
+ * Supplies {@link AdwNavigationPageProps} for a page a mutation is registering
+ * on the fly. `replace()` may introduce pages the view has never seen; a renderer
+ * reads their properties from its own markup (DOM attributes, XML) and this is
+ * the seam that lets it, without core touching a platform API.
+ */
+export type NavigationPagePropsResolver<P> = (page: P) => AdwNavigationPageProps | undefined;
+/**
+ * What a shortcut handler must do with the key event. `'stop'` is
+ * `GDK_EVENT_STOP` — notably also returned WITHOUT popping when the visible page
+ * has `can-pop = FALSE`, so the key is not forwarded to an enclosing navigation
+ * view (pop_shortcut_cb:1150-1152).
+ */
+export type NavigationShortcutResult = 'stop' | 'propagate';
+/** Construction defaults + the diagnostic seam. */
+export interface NavigationViewOptions {
+    /** `AdwNavigationView:animate-transitions`, default `true` (init:2142). */
+    animateTransitions?: boolean;
+    /** `AdwNavigationView:pop-on-escape`, default `true` (init:2143). */
+    popOnEscape?: boolean;
+    /** Where rejected mutations are reported. Unset = silent. */
+    onDiagnostic?: NavigationDiagnosticListener;
+}
+/** The default back-button tooltip when the previous page has no title. */
+export declare const BACK_BUTTON_FALLBACK_TOOLTIP = "Back";
+/** The `g_critical` message libadwaita prints for `diagnostic` — kept verbatim. */
+export declare function describeNavigationDiagnostic(diagnostic: NavigationDiagnostic): string;
+/**
+ * The whole `Adw.NavigationView` machine, headless.
+ *
+ * A renderer registers its page handles ({@link add} / {@link push}), drives the
+ * mutators, and reacts to one {@link NavigationStackChange} per mutation. It keeps
+ * ZERO navigation state of its own — the stack, the tag index, the
+ * static-vs-dynamic ownership and the deferred-destroy queue all live here.
+ */
+export declare class NavigationViewState<P = unknown> {
+    private readonly _registry;
+    private readonly _tags;
+    private readonly _stack;
+    private readonly _listeners;
+    private readonly _onDiagnostic;
+    private _animateTransitions;
+    private _popOnEscape;
+    /** The outgoing page owed a destroy once the transition ends (C's `hiding_page`). */
+    private _pendingRemoval;
+    constructor(options?: NavigationViewOptions);
+    /** Subscribe to stack changes. Returns an unsubscribe function. */
+    subscribe(listener: NavigationStackListener<P>): () => void;
+    /** The navigation stack, bottom-first. A snapshot — mutating it does nothing. */
+    get stack(): readonly P[];
+    /** Number of pages on the stack. */
+    get depth(): number;
+    /** Every registered page (static + dynamically pushed), in registration order. */
+    get pages(): readonly P[];
+    /** The top of the stack, or `null` when the stack is empty (get_visible_page:3165). */
+    get visiblePage(): P | null;
+    /** The visible page's tag, or `null` — never `''` for an untagged page (get_visible_page_tag:3195). */
+    get visiblePageTag(): string | null;
+    /** Whether push/pop transitions animate. */
+    get animateTransitions(): boolean;
+    /** Whether Escape pops the visible page. */
+    get popOnEscape(): boolean;
+    /** Set `animate-transitions`. Returns whether it changed. */
+    setAnimateTransitions(value: boolean): boolean;
+    /** Set `pop-on-escape`. Returns whether it changed. */
+    setPopOnEscape(value: boolean): boolean;
+    /** Whether `page` is known to this view. */
+    isRegistered(page: P): boolean;
+    /** Whether `page` currently sits on the navigation stack. */
+    isInStack(page: P): boolean;
+    /** Whether `page` is a DYNAMIC page — pushed but never added, so destroyed when popped. */
+    isRemoveOnPop(page: P): boolean;
+    /** `page`'s tag, or `null` (also `null` for an unregistered page). */
+    tagOf(page: P): string | null;
+    /** `page`'s title. `''` when untitled or unregistered — the C title is never NULL. */
+    titleOf(page: P): string;
+    /** `page`'s `can-pop`. `true` for an unregistered page, matching the property default. */
+    canPopOf(page: P): boolean;
+    /**
+     * The page with this tag, or `null` (find_page:2774).
+     *
+     * Byte-exact: the C table is `g_str_hash`/`g_str_equal`, so NFC and NFD
+     * spellings of the same word are DIFFERENT keys and `''` is a valid one.
+     * Dynamically-pushed pages are found too — `maybe_add_page` routes through
+     * `add_page`, which indexes the tag (:1281-1282).
+     */
+    findPage(tag: string): P | null;
+    /**
+     * The page popping `page` would reveal (get_previous_page:3228) — `null` when
+     * `page` is the root page or is not on the stack.
+     */
+    getPreviousPage(page: P): P | null;
+    /**
+     * Permanently add `page` (adw_navigation_view_add:2719). A page added this way
+     * survives being popped.
+     *
+     * Two rules that were missing from the renderers:
+     *   1. Adding a page that is on the stack as a DYNAMIC page converts it to a
+     *      permanent one and does nothing else (:2725-2730) — the stack does not
+     *      move and no change is emitted.
+     *   2. The auto-push fires whenever the stack is EMPTY, not only for the very
+     *      first page ever added (add_page:1284) — so `add()` after `replace([])`
+     *      pushes again.
+     *
+     * Returns `false` (with a `duplicate-tag` diagnostic) when the tag collides.
+     */
+    add(page: P, props?: AdwNavigationPageProps): boolean;
+    /**
+     * Remove `page` (adw_navigation_view_remove:2750 → remove_page:1312).
+     *
+     * If the page is on the stack the removal is DEFERRED: the page is marked
+     * remove-on-pop and destroyed when it is popped (:1323-1326). Otherwise it is
+     * unregistered immediately and its tag freed. Returns `false` only for a page
+     * this view does not know.
+     */
+    remove(page: P): boolean;
+    /**
+     * Set `page`'s tag (adw_navigation_page_set_tag:2437). Silent no-op when
+     * unchanged (:2448); rejected with `duplicate-tag` when another page already
+     * owns the tag, in which case the OLD tag is kept (:2456-2460).
+     */
+    setTag(page: P, tag: string | null): boolean;
+    /**
+     * Set `page`'s title (adw_navigation_page_set_title:2508). Drives the header-bar
+     * title and the NEXT page's back-button tooltip. `null`/`undefined` is rejected
+     * — the C has `g_return_if_fail (title != NULL)` (:2514).
+     */
+    setTitle(page: P, title: string): boolean;
+    /**
+     * Set `page`'s `can-pop` (adw_navigation_page_set_can_pop:2569). Gates
+     * shortcuts, gestures and the back button — deliberately NOT {@link pop}.
+     */
+    setCanPop(page: P, canPop: boolean): boolean;
+    /**
+     * Push `page` onto the stack (adw_navigation_view_push:2800).
+     *
+     * A page the view has never seen is registered as DYNAMIC (destroyed when
+     * popped, maybe_add_page:1307-1308); an already-registered one keeps its
+     * permanence, because maybe_add_page returns early for it (:1296-1297). That
+     * asymmetry is why a static page survives a push/pop round trip.
+     *
+     * Returns `false` with `already-in-stack` when the page is already on the
+     * stack (push_to_stack:942-952), or with `duplicate-tag` when its tag collides.
+     */
+    push(page: P, props?: AdwNavigationPageProps): boolean;
+    /**
+     * Push the page carrying `tag` (adw_navigation_view_push_by_tag:2829). An
+     * unknown tag is rejected with `tag-not-found` and changes nothing.
+     */
+    pushByTag(tag: string): boolean;
+    /**
+     * Pop the visible page (adw_navigation_view_pop:2869). `false` when there is
+     * no visible page or no page beneath it.
+     *
+     * Deliberately IGNORES `can-pop`: the C function contains no such test and the
+     * property docs say so in as many words — "Manually calling
+     * [method@NavigationView.pop] […] will still work" (:2560-2561). Use
+     * {@link popFromShortcut} for the gated path.
+     */
+    pop(): boolean;
+    /**
+     * Pop until `page` is visible (adw_navigation_view_pop_to_page:2913) — ONE
+     * atomic splice, so ONE visible-page notification carrying every popped page,
+     * not N sequential pops. Ignores `can-pop` on the pages it passes.
+     *
+     * `false` (silently) when `page` is already visible; `false` with
+     * `not-in-stack` when it is off-stack.
+     */
+    popToPage(page: P): boolean;
+    /**
+     * Pop until the page carrying `tag` is visible (adw_navigation_view_pop_to_tag:2958).
+     * An unknown tag yields `tag-not-found`; a known but off-stack one yields
+     * `not-in-stack`.
+     */
+    popToTag(tag: string): boolean;
+    /**
+     * Replace the whole stack (adw_navigation_view_replace:3002). Never animates
+     * (:3075) and emits no `popped` — `::replaced` is its own signal.
+     *
+     * `null` entries are skipped (:3021, :3052) and a page listed twice is
+     * rejected on its second occurrence (:3055-3059). Old DYNAMIC pages are
+     * destroyed only when they are absent from the new set (:3033-3034); that
+     * guard is what makes replacing the stack with the tag of a pushed page work.
+     * An empty array leaves no visible page.
+     *
+     * `props` supplies registration properties for pages the view has not seen.
+     */
+    replace(pages: readonly (P | null)[], props?: NavigationPagePropsResolver<P>): void;
+    /**
+     * Replace the stack with the pages carrying `tags`
+     * (adw_navigation_view_replace_with_tags:3124).
+     *
+     * Every tag is resolved BEFORE any mutation; an unknown one reports
+     * `tag-not-found` and becomes a null slot {@link replace} then skips, rather
+     * than aborting the call. Resolving up front is exactly what the web port's
+     * `replace()` failed to do.
+     */
+    replaceWithTags(tags: readonly string[]): void;
+    /**
+     * Report that the outgoing transition finished (transition_done_cb:1029-1075),
+     * and receive the pages the renderer must now destroy.
+     *
+     * This is the injected timing seam replacing `AdwAnimation`'s "done" callback.
+     * A renderer that does not animate calls it straight after the change — which
+     * is precisely what `adw_animation_skip` does in the C when `animate` is FALSE.
+     * A page pushed back onto the stack before the transition finished survives,
+     * because the C routes this through `adw_navigation_view_remove` and its
+     * on-the-stack check (:1042 → remove_page:1323).
+     */
+    finishTransition(): readonly P[];
+    /**
+     * Whether the automatic back button is shown — `get_previous_page(visible) !==
+     * null && can_pop(visible)` (adw-back-button.c update_page:84-108). This is the
+     * ONLY place `can-pop` decides whether a page can be left.
+     */
+    canGoBack(): boolean;
+    /**
+     * The back button's tooltip: the title of the page the button would reveal,
+     * falling back to `fallback` only when that title is empty
+     * (adw-back-button.c query_tooltip:399-419). `null` when there is no back
+     * button at all.
+     */
+    backButtonTooltip(fallback?: string): string | null;
+    /**
+     * The `can-pop`-aware pop behind Alt+Left and the back mouse button
+     * (pop_shortcut_cb:1142-1158).
+     *
+     * Returns `'stop'` WITHOUT popping when the visible page has `can-pop = FALSE`
+     * — deliberately, so the key is not forwarded to an enclosing navigation view.
+     */
+    popFromShortcut(): NavigationShortcutResult;
+    /** Escape-to-pop: {@link popFromShortcut} gated on `pop-on-escape` (escape_shortcut_cb:1175-1182). */
+    popFromEscape(): NavigationShortcutResult;
+    private _diagnose;
+    private _emit;
+    private _emitChange;
+    /** `add_page` (:1263) — register, index the tag, and auto-push into an empty stack. */
+    private _addPage;
+    /** `maybe_add_page` (:1290) — register an unknown page as DYNAMIC; keep a known one as it is. */
+    private _maybeAddPage;
+    /** `push_to_stack` (:933) — the append plus its already-in-stack guard. */
+    private _pushToStack;
+    /** `pop_from_stack` (:969) — one splice, one switch, then the per-page destroys. */
+    private _popFromStack;
+    /**
+     * `switch_page` (:824), minus the rendering: flush a still-pending deferred
+     * destroy, decide whether this transition animates, and queue the new one.
+     */
+    private _beginSwitch;
+    /**
+     * Settle the deferred destroy owed by the last pop — the shared body of
+     * {@link finishTransition} and the mid-transition flush in {@link _beginSwitch}.
+     * Both go through `adw_navigation_view_remove` in the C (:1042 / :868), so both
+     * inherit `remove_page`'s on-the-stack check: a page pushed BACK before the
+     * transition ended survives and is merely re-marked remove-on-pop.
+     */
+    private _resolvePendingRemoval;
+    private _unregister;
+}

package/lib/types/navigation-view.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/popover.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Padding inside a popover's content box, in px — `popover > contents { padding: 8px }`
+ * (_popovers.scss:14).
+ *
+ * NOT what a MENU popover uses: `popover.menu > contents` re-declares
+ * `padding: 0` and moves the inset onto the item box as `$menu_margin` (6px)
+ * (_menus.scss:58-66) — two element selectors plus a class, so it wins over the
+ * plain `popover > contents` above. Both numbers are real; which one applies is
+ * decided by the `.menu` class, not by this constant. See {@link POPOVER_MENU_PADDING}.
+ */
+export declare const POPOVER_PADDING = 8;
+/**
+ * Padding around the item box of a MENU popover, in px — `$menu_margin`
+ * (_common.scss:11), applied by `popover.menu > contents > … > stack > box`
+ * (_menus.scss:61-64) after that same rule zeroes the contents padding.
+ *
+ * This is the number the three hand-rolled copies actually used (`--spacing-xs`,
+ * 6px). They were not wrong about the inset — they were wrong about the radius,
+ * and one of them about the shadow.
+ */
+export declare const POPOVER_MENU_PADDING = 6;
+/**
+ * Corner radius of a popover surface, in px — `$popover_radius`, defined as
+ * `$menu_radius + 6` = `9 + 6` (_common.scss:10,13) and applied at
+ * _popovers.scss:15.
+ *
+ * All three copies got this wrong: two used `--card-radius` (12px, `$card_radius`)
+ * and one `--button-radius` (9px, `$button_radius`).
+ */
+export declare const POPOVER_RADIUS = 15;
+/**
+ * Corner radius of a menu item row, in px — `$menu_radius` (_common.scss:10),
+ * applied by `modelbutton` at _menus.scss:138.
+ */
+export declare const POPOVER_ITEM_RADIUS = 9;
+/** Payload of a {@link PopoverState} change. */
+export interface PopoverStateChange {
+    /** Whether the popover is now open. */
+    open: boolean;
+    /**
+     * True for a user gesture ({@link PopoverState.toggle} — the anchor was
+     * clicked — or {@link PopoverState.dismiss} — an outside click or Escape);
+     * false for a programmatic {@link PopoverState.popup} / {@link PopoverState.popdown}.
+     */
+    interactive: boolean;
+}
+/** Subscriber for {@link PopoverState} changes. */
+export type PopoverStateListener = (change: PopoverStateChange) => void;
+/**
+ * The open/closed state of a popover, with the programmatic-vs-interactive
+ * distinction the other core states carry ({@link ComboState}, {@link SpinState},
+ * {@link SplitButtonState}): a renderer re-emits `notify::*` only for the
+ * interactive changes, so an application calling `popup()` does not look like a
+ * user click.
+ *
+ * NAMING: the state exposes a `open` GETTER, so the mutators cannot also be
+ * called `open()`/`close()` — a class cannot carry both under one name. They
+ * take GTK's own vocabulary instead ({@link popup} / {@link popdown}, after
+ * `adw_split_button_popup()` / `..._popdown()`), which is also what the
+ * `<adw-popover>` element exposes. `SplitButtonState` resolved the same clash
+ * as `openMenu()`/`closeMenu()`.
+ *
+ * Idempotent: setting the current value again is a no-op and notifies nobody.
+ */
+export declare class PopoverState {
+    private _open;
+    private readonly _listeners;
+    /** Subscribe to open-state changes. Returns an unsubscribe function. */
+    subscribe(listener: PopoverStateListener): () => void;
+    private _emit;
+    private _setOpen;
+    /** Whether the popover is showing. */
+    get open(): boolean;
+    /** Show the popover programmatically. Returns whether it changed. */
+    popup(): boolean;
+    /** Hide the popover programmatically. Returns whether it changed. */
+    popdown(): boolean;
+    /** The anchor was activated by the user; flips open/closed. Returns whether it changed. */
+    toggle(): boolean;
+    /**
+     * The user dismissed the popover — an outside click, or Escape. Distinct
+     * from {@link popdown} only in the `interactive` flag, which is the whole
+     * point: a dismissal is a gesture, a `popdown()` call is not.
+     */
+    dismiss(): boolean;
+}
+/** What a key press asks the renderer to do. */
+export type PopoverKeyAction = 
+/** Dismiss the popover and return focus to the anchor. */
+'close'
+/** Move focus to `index`. */
+ | 'focus'
+/** Activate the item at `index` (and let the renderer close + notify). */
+ | 'activate'
+/** Not ours — let the key through to whatever owns it. */
+ | 'none';
+/** The list state a key press is resolved against. */
+export interface PopoverKeyContext {
+    /**
+     * How many items are navigable RIGHT NOW. For a filtered list (the drop-down's
+     * search) that is the VISIBLE count, not the model length — filtering is the
+     * renderer's business, and this function only ever sees the surviving list.
+     */
+    itemCount: number;
+    /** Focused item's index in that same list; `-1` when focus is elsewhere (the search entry, the surface). */
+    currentIndex: number;
+    /**
+     * Whether a search entry sits atop the popover. It matters only while
+     * `currentIndex` is `-1` (i.e. the entry has focus and owns the caret) — see
+     * {@link resolvePopoverKey}.
+     */
+    hasSearch?: boolean;
+}
+/** {@link resolvePopoverKey}'s answer. */
+export interface PopoverKeyResolution {
+    /** What to do. */
+    action: PopoverKeyAction;
+    /** Item index for `focus`/`activate`; `-1` for `close` and `none`. */
+    index: number;
+}
+/**
+ * Resolve a key press inside an open popover to a focus/activation move.
+ *
+ * This is the `(current ± 1 + n) % n` arithmetic `adw-menu-button` and
+ * `adw-drop-down` each spelled out, reconciled. Where the two copies differed:
+ *
+ * - **`ArrowUp` from no focus.** BOTH copies computed `(-1 - 1 + n) % n`, which
+ *   is `n - 2` — the second-to-LAST item. Reachable in the drop-down on every
+ *   open with `enable-search`, since it focuses the search entry. Fixed here to
+ *   `n - 1`: ArrowUp from nothing enters the list at the END, the convention the
+ *   ARIA menu/listbox patterns describe and the mirror of ArrowDown → `0`.
+ *   Not verifiable against GTK in this tree — see the caveat below.
+ * - **`Enter`/`Space`.** The drop-down activated the focused item; the menu
+ *   button had no case and leaned on the browser activating a focused `<button>`
+ *   natively. Reported as `'activate'` for both: a renderer that calls
+ *   `preventDefault()` and then `.click()` activates exactly once, where relying
+ *   on the native path makes the behaviour depend on the item's tag.
+ * - **`Home`/`End` with a search entry focused.** The drop-down stole them
+ *   unconditionally, so Home could not move the caret to the start of the query
+ *   the user was typing. `'none'` here while `hasSearch && currentIndex < 0`.
+ * - The `+ n` in `(current + 1 + n) % n` is defensive only — for `current` in
+ *   `[-1, n)` it is arithmetically identical to `(current + 1) % n`. Not a
+ *   divergence, just two spellings.
+ *
+ * NOT VERIFIABLE IN THIS TREE: `refs/gtk` is empty and libadwaita vendors no
+ * `adw-popover.c`, so `GtkPopover`'s own `position` / `autohide` / `has-arrow`
+ * semantics — and GTK's exact keynav from an unfocused list — cannot be read
+ * from source here. The wrap arithmetic below is the reconciliation of our two
+ * copies against the ARIA patterns, not a claim about GTK's C.
+ *
+ * `Tab` is deliberately unhandled (`'none'`): GTK popovers trap focus, and doing
+ * that in the DOM is a renderer concern (`inert`, a focus sentinel) with no
+ * portable arithmetic to share.
+ */
+export declare function resolvePopoverKey(key: string, context: PopoverKeyContext): PopoverKeyResolution;

package/lib/types/popover.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;