@gjsify/adwaita-core 0.47.0 → 0.48.0

package/lib/types/index.d.ts

@@ -24,8 +24,12 @@ export { AdwToast, AdwToastQueue, DEFAULT_TOAST_TIMEOUT } from './toast.js';
 export type { AdwToastOptions, AdwToastQueueHandlers, AdwToastQueueOptions, ToastScheduler, ToastTimerHandle, } from './toast.js';
 export { AdwAlertResponses, BottomSheetPresentation, resolveBottomSheetClose } from './dialog.js';
 export type { AdwAlertResponse, AdwResponseAppearance, AdwResponseOptions, BottomSheetCloseOutcome, BottomSheetCloseSource, BottomSheetCloseState, BottomSheetPresentationListener, BottomSheetPresentationOptions, BottomSheetTeardownCallback, OrderedConfirmResponses, } from './dialog.js';
-export { ADW_COMBO_NO_SELECTION, ComboState, ExpanderState, SpinState, ToggleGroupState, normalizeComboOptions, } from './rows.js';
-export type { AdwComboOption, AdwComboOptionInput, ComboStateChange, ComboStateListener, ExpanderStateListener, SpinStateChange, SpinStateListener, ToggleGroupStateChange, ToggleGroupStateListener, } from './rows.js';
+export { ADW_COMBO_NO_SELECTION, clampListSelection, listItemsChanged, normalizeComboOptions, parseListModel, } from './list.js';
+export type { AdwComboOption, AdwComboOptionInput, AdwListItemsChanged, AdwListModel, AdwListModelInput, } from './list.js';
+export { ADW_ADJUSTMENT_DEFAULTS, adjustmentRange, clampAdjustmentValue, normalizeAdjustment, parseAdjustment, snapAdjustmentValue, SpinState, } from './adjustment.js';
+export type { AdwAdjustment, AdwAdjustmentInput, SpinStateChange, SpinStateListener, SpinStateRangeListener, } from './adjustment.js';
+export { ComboState, ExpanderState, ToggleGroupState } from './rows.js';
+export type { ComboItemsListener, ComboStateChange, ComboStateListener, ExpanderStateListener, 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';
@@ -44,11 +48,13 @@ export { ADW_LENGTH_UNITS, DEFAULT_DPI, adwLengthToPx, normalizeLengthUnit } fro
 export type { AdwLengthUnit } from './length-unit.js';
 export { ADW_SWIPE_BORDER, 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, isSidebarAtVisualStart, layoutNavigationSplitView, layoutOverlaySplitView, measureSplitViewHorizontal, resolveNaturalSidebarWidth, resolveNavigationAction, resolveNavigationSidebarWidth, resolveNavigationStack, resolveOverlaySidebarWidth, resolveSidebarBounds, resolveSwipeArea, resolveSwipeRelease, resolveSwipeSnapPoints, resolveSwipeStart, swipeCancelProgress, tagsConflict, } from './split-view.js';
 export type { 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_DROPDOWN_TOOLTIP, SPLIT_BUTTON_DISABLED_OPACITY, SplitButtonState, isSplitButtonDirection, menuButtonArrowIcon, menuButtonPopupDirection, resolveDropdownTooltip, splitButtonArrowIcon, splitButtonPopupDirection, splitButtonRootState, splitButtonStyleClasses, } from './split-button.js';
+export type { AdwArrowIcon, SplitButtonChange, SplitButtonContentMode, SplitButtonDirection, SplitButtonHalfState, SplitButtonListener, SplitButtonProperty, SplitButtonStyleClass, } from './split-button.js';
+export { ADW_MENU_SURFACE_NATIVESCRIPT, ADW_MENU_SURFACE_WEB, assertMenuRenderable, flattenMenu, menuItemAt, menuNodeAt, menuRefusals, normalizeMenuModel, parseDetailedAction, parseMenuModel, resolveMenuItemState, } from './menu.js';
+export type { AdwDetailedAction, AdwMenuAction, AdwMenuActions, AdwMenuDisplayHint, AdwMenuEntryInput, AdwMenuFlatRow, AdwMenuHiddenWhen, AdwMenuInput, AdwMenuItem, AdwMenuItemInput, AdwMenuItemRole, AdwMenuItemState, AdwMenuModel, AdwMenuNode, AdwMenuPath, AdwMenuRefusal, AdwMenuSection, AdwMenuSectionInput, AdwMenuSubmenu, AdwMenuSubmenuInput, AdwMenuSurface, AdwMenuTextDirection, } from './menu.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 { DEFAULT_TAB_AUTOHIDE, TabViewState, isDescendantOfPage, successorAfterClose, tabCloseVisible, tabIconState, tabTooltip, tabTooltipIsMarkup, tabViewItemsChanged, tabsRevealed, } from './tab-view.js';
 export type { AdwTabPageSpec, AdwTabPageState, TabIconState, TabViewHandlers, TabViewPagesChange, TabViewPagesChangeKind, TabViewPagesListener, TabViewSelectionChange, TabViewSelectionListener, } from './tab-view.js';
 export { ADW_SWIPE_DECELERATION_TOUCH, ADW_SWIPE_DECELERATION_TOUCHPAD, ADW_SWIPE_DRAG_THRESHOLD, ADW_SWIPE_EPSILON, ADW_SWIPE_HISTORY_THRESHOLD_MS, ADW_SWIPE_PARABOLA_MULTIPLIER, ADW_SWIPE_TOUCHPAD_BASE_DISTANCE_H, ADW_SWIPE_TOUCHPAD_BASE_DISTANCE_V, ADW_SWIPE_VELOCITY_CURVE_THRESHOLD, ADW_SWIPE_VELOCITY_THRESHOLD_TOUCH, ADW_SWIPE_VELOCITY_THRESHOLD_TOUCHPAD, SwipeTracker, swipeBounds, swipeClosestPointIndex, swipeEndProgress, swipeNextPointIndex, swipePreviousPointIndex, swipeProjectedPointIndex, swipeSlope, swipeVelocityThreshold, } from './swipe.js';
 export type { AdwSwipeEnd, AdwSwipeEndInput, AdwSwipeRange, AdwSwipeSource } from './swipe.js';

package/lib/types/list.d.ts

@@ -0,0 +1,109 @@
+/** One selectable item — the display text plus the value it is addressed by. */
+export interface AdwComboOption {
+    /** Display label shown in the row + chooser. */
+    label: string;
+    /** Underlying value the item is addressed by. */
+    value: string;
+}
+/**
+ * What an author may write for one item before {@link normalizeComboOptions} has seen it:
+ * a bare string (value === label, the `Gtk.StringList` case), or a partial descriptor
+ * where either half may stand in for the other.
+ */
+export type AdwComboOptionInput = string | {
+    value?: unknown;
+    label?: unknown;
+};
+/** A normalised portable list model — what a `model` property holds on every surface. */
+export type AdwListModel = ReadonlyArray<AdwComboOption>;
+/** What a `model` property ACCEPTS: the widened form of {@link AdwListModel}. */
+export type AdwListModelInput = ReadonlyArray<AdwComboOptionInput>;
+/**
+ * Raw authored items → the stable `{ value, label }` descriptors every list surface
+ * works with.
+ *
+ * A bare string is both value and label (`Gtk.StringList`'s model, which is what
+ * `Adw.ComboRow` is fed in the common case). In a descriptor either half stands in for the
+ * missing other, so `{ label: 'Apple' }` is addressable by the value `'Apple'` rather than
+ * by `undefined`. ONE home for the rule, so no two list widgets can accept two different
+ * item vocabularies.
+ *
+ * TOTAL — it throws for no input. The doors this reaches are a property assignment and a
+ * markup attribute, and an author's typo must not take the widget down.
+ */
+export declare function normalizeComboOptions(raw: AdwListModelInput | null | undefined): AdwComboOption[];
+/**
+ * The MARKUP door: a JSON attribute → the normalised model.
+ *
+ * Total in both of its failure modes, which are different things and both an author slip:
+ * unparseable JSON and well-formed JSON that is not an array (an object, a number)
+ * each yield the empty model. Neither may stop the element upgrading — the reasoning
+ * `parseMenuModel` records for the same door on the same surfaces.
+ *
+ * It lives here rather than in each element because it was written twice, byte for byte,
+ * in `<adw-combo-row>` and `<gtk-drop-down>`: the second copy is where a helper is lifted.
+ */
+export declare function parseListModel(raw: string | null | undefined): AdwComboOption[];
+/**
+ * The "no item is selected" index — the TS mirror of `GTK_INVALID_LIST_POSITION`
+ * (`AdwComboRow:selected`'s default and empty value).
+ *
+ * libadwaita spells it `G_MAXUINT` because the property is a `guint`; `-1` is the idiomatic
+ * TS sentinel and the spelling {@link ADW_SIDEBAR_NO_SELECTION} uses for the same GTK
+ * constant. Without it, an EMPTY model and a model whose first item has an empty label are
+ * indistinguishable — both report index 0 with an empty value — so a renderer that wants to
+ * draw a placeholder has nothing to test.
+ */
+export declare const ADW_COMBO_NO_SELECTION = -1;
+/**
+ * Where a selection lands after the model under it was REPLACED.
+ *
+ * `GtkSingleSelection` autoselects, so a position the new model does not have falls back
+ * to 0 — including the sentinel, which is how a widget recovers a selection when its model
+ * grows. An EMPTY model has no 0 to fall back to and lands on
+ * {@link ADW_COMBO_NO_SELECTION}.
+ *
+ * The test is membership and not `selected >= length`: the sentinel is BELOW the range, so
+ * a one-sided comparison leaves a `-1` in place and a model that was emptied and refilled
+ * comes back with nothing selected.
+ *
+ * Lifted out of `ComboState.setModel` so a second list widget cannot re-derive it. The
+ * cross-renderer rule it encodes was already conformance data — `conformance/rows.ts`
+ * carries it as "the ports' shared answer" — it just had no name of its own.
+ */
+export declare function clampListSelection(selected: number, length: number): number;
+/**
+ * One positional change — `Gio.ListModel::items-changed`'s own three parameters.
+ *
+ * `position` is where the model changed, `removed` how many items went, `added` how many
+ * arrived. WHAT arrived is deliberately absent, because that is GLib's contract too: a
+ * consumer re-reads the model over `[position, position + added)`. Carrying the items
+ * would make the signal a second copy of the model that can disagree with it.
+ */
+export interface AdwListItemsChanged {
+    /** The position at which the model changed. */
+    readonly position: number;
+    /** The number of items removed at {@link position}. */
+    readonly removed: number;
+    /** The number of items added at {@link position}. */
+    readonly added: number;
+}
+/**
+ * The ONE splice that turns `previous` into `next` — the `items-changed` a model
+ * replacement should emit, or `null` when the two are equal and GTK would emit nothing.
+ *
+ * It is the minimal single range: the shared prefix and the shared suffix are kept, and
+ * everything between them is the change. That is `g_list_store_splice`'s shape and its
+ * stated reason — one emission per change rather than one per item — and it is what lets
+ * a renderer append an item to a hundred-item list by adding ONE node.
+ *
+ * Items compare by BOTH halves: a descriptor whose label changed at an unchanged value is
+ * a different thing to draw, so it is inside the range. Comparing by `value` alone would
+ * leave a renamed row showing its old text, which is the exact failure `selection_item_changed`
+ * exists for upstream.
+ *
+ * NOT a diff algorithm. A model that moves one item from the front to the back reports the
+ * whole span, because `items-changed` has no vocabulary for a move — GTK's own list store
+ * reports `g_list_store_move` the same way.
+ */
+export declare function listItemsChanged(previous: AdwListModel | null | undefined, next: AdwListModel | null | undefined): AdwListItemsChanged | null;

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

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

package/lib/types/menu.d.ts

@@ -0,0 +1,366 @@
+/**
+ * The values `hidden-when` is documented to take.
+ *
+ * A union rather than `string` because each one has its OWN visibility rule in
+ * {@link resolveMenuItemState}; an unrecognised value is ignored by C on purpose ("this
+ * code may be running in context of a desktop shell … and should not spew criticals"),
+ * which {@link normalizeMenuModel} reproduces by dropping it.
+ */
+export type AdwMenuHiddenWhen = 'action-disabled' | 'action-missing' | 'macos-menubar';
+/** A section's `display-hint`, which asks for a row of buttons instead of a list. */
+export type AdwMenuDisplayHint = 'horizontal-buttons' | 'circular-buttons' | 'inline-buttons';
+/** A section's `text-direction`, read only when {@link AdwMenuDisplayHint} is horizontal. */
+export type AdwMenuTextDirection = 'ltr' | 'rtl' | 'none';
+/**
+ * One menu item — the attributes `GtkPopoverMenu` documents, plus `id`.
+ *
+ * `id` is OURS and has no meaning to GTK. It survives the round trip anyway, because a
+ * `GMenuModel`'s attribute space is open (`g_menu_item_set_attribute` takes any name and
+ * GTK ignores what it does not know), so carrying it is not a divergence — it is an
+ * unread attribute, exactly like an application's own. It exists because the two
+ * renderers' activation events already reported one, falling back to the label.
+ */
+export interface AdwMenuItem {
+    readonly kind: 'item';
+    /** The user-visible string. `''` for an item that has none — never `undefined`. */
+    readonly label: string;
+    /**
+     * The DETAILED action name — `app.save-as`, `app.view::list`, `win.zoom(2)`.
+     *
+     * One string rather than an action plus a target, because that is what
+     * `g_menu_item_set_detailed_action` takes and what `g_action_parse_detailed_name`
+     * can read back for every `GVariant` target type. {@link parseDetailedAction} splits
+     * it where a surface needs the halves.
+     */
+    readonly action?: string;
+    /** Symbolic icon name shown beside the label. */
+    readonly icon?: string;
+    /** Icon for the button form a `display-hint` section draws instead of a row. */
+    readonly verbIcon?: string;
+    /** Accelerator text, e.g. `<Control>s`. Display only — it binds nothing. */
+    readonly accel?: string;
+    /** When this item disappears rather than merely dimming. */
+    readonly hiddenWhen?: AdwMenuHiddenWhen;
+    /** Names an application widget the surface must host in place of a row. */
+    readonly custom?: string;
+    /** Whether {@link label} is Pango markup. */
+    readonly useMarkup?: boolean;
+    /** Stable identifier for activation reporting; defaults to {@link label}. */
+    readonly id?: string;
+}
+/**
+ * A `section` link: items drawn inline, separated from their neighbours.
+ *
+ * A section is NOT a container the user opens — it is a visual grouping, which is why a
+ * flat surface may inline it ({@link flattenMenu}) without losing an item.
+ */
+export interface AdwMenuSection {
+    readonly kind: 'section';
+    /** Optional heading above the group. */
+    readonly label?: string;
+    readonly displayHint?: AdwMenuDisplayHint;
+    readonly textDirection?: AdwMenuTextDirection;
+    readonly items: readonly AdwMenuNode[];
+}
+/**
+ * A `submenu` link: a nested menu the user opens.
+ *
+ * `submenuAction` is documented under ITEMS (`gtkpopovermenu.c:106-107`) rather than
+ * under submenus, and it is here anyway: it names the action that tracks whether the
+ * submenu is OPEN, so the only item it can sit on is the one carrying the link — which
+ * in this model IS this node. `gtkmenutrackeritem.c:822` and `:1049` read it, and both
+ * paths are submenu paths.
+ */
+export interface AdwMenuSubmenu {
+    readonly kind: 'submenu';
+    readonly label: string;
+    readonly icon?: string;
+    /** Action tracking whether this submenu is shown (`submenu-action`). */
+    readonly submenuAction?: string;
+    /**
+     * `gtk-macos-special` — macOS menu-bar meaning, ignored everywhere else
+     * (`gtkpopovermenu.c:130-131`, read at `gtkmenutrackeritem.c:761`).
+     *
+     * Carried and never acted on here: no renderer in this workspace exports a macOS
+     * menu bar. It is in the model so that a menu written for one survives the trip,
+     * which is the whole lossless claim.
+     */
+    readonly macosSpecial?: string;
+    readonly items: readonly AdwMenuNode[];
+}
+/** Any node of a normalised model. */
+export type AdwMenuNode = AdwMenuItem | AdwMenuSection | AdwMenuSubmenu;
+/**
+ * A normalised menu: the value a renderer walks and the GTK host converts.
+ *
+ * `readonly` throughout, because every renderer holds one across a render and a shared
+ * mutable tree is how two widgets showing the same menu would diverge.
+ */
+export type AdwMenuModel = readonly AdwMenuNode[];
+/** An item as authored — `kind` is implied by the absence of a link. */
+export interface AdwMenuItemInput {
+    label?: unknown;
+    action?: unknown;
+    icon?: unknown;
+    verbIcon?: unknown;
+    accel?: unknown;
+    hiddenWhen?: unknown;
+    custom?: unknown;
+    useMarkup?: unknown;
+    id?: unknown;
+}
+/** A section as authored — the `section` key IS the link. */
+export interface AdwMenuSectionInput {
+    section: readonly AdwMenuEntryInput[];
+    label?: unknown;
+    displayHint?: unknown;
+    textDirection?: unknown;
+}
+/** A submenu as authored — the `submenu` key IS the link. */
+export interface AdwMenuSubmenuInput {
+    submenu: readonly AdwMenuEntryInput[];
+    label?: unknown;
+    icon?: unknown;
+    submenuAction?: unknown;
+    macosSpecial?: unknown;
+}
+/**
+ * One authored entry.
+ *
+ * A BARE STRING is a label-only item, and that form is not a NativeScript leftover: it
+ * is the model's own shorthand, the same one {@link normalizeComboOptions} gives an
+ * option list, and it is now accepted on every surface rather than on one. What it
+ * cannot carry — an action, an icon, a section — is exactly what made
+ * `button.menu = ['Save as…']` unable to grow, so the shorthand widens INTO this union
+ * instead of standing beside it.
+ */
+export type AdwMenuEntryInput = string | AdwMenuItemInput | AdwMenuSectionInput | AdwMenuSubmenuInput;
+/** A menu as authored, before {@link normalizeMenuModel} has seen it. */
+export type AdwMenuInput = readonly AdwMenuEntryInput[];
+/**
+ * Authored entries → the normalised model every renderer walks.
+ *
+ * TOTAL BY CONSTRUCTION. The input reaches this function from author-written markup (a
+ * JSON attribute, an XML attribute, a JSX expression), and a typo must not take the
+ * widget down with it — the same rule the `menu` attribute parser it replaces already
+ * had. So an unusable entry is DROPPED and an unusable attribute is omitted; nothing
+ * here throws. The loud half is {@link assertMenuRenderable}, which runs against a
+ * SURFACE and can therefore say something true about what will not be drawn.
+ *
+ * A link wins over the attributes beside it: `{ label: 'More', submenu: [...] }` is a
+ * submenu with a label, never an item that happens to carry a list, because that is how
+ * `g_menu_item_get_link` reads the same object.
+ */
+export declare function normalizeMenuModel(input: AdwMenuInput | null | undefined): AdwMenuModel;
+/**
+ * A `menu` ATTRIBUTE — a JSON array — as a model.
+ *
+ * Total for the same reason {@link normalizeMenuModel} is, and it adds the one failure
+ * markup can produce that a JS value cannot: `JSON.parse` genuinely throws on a typo,
+ * and the widget must degrade to "no menu" rather than fail to upgrade.
+ */
+export declare function parseMenuModel(json: string | null | undefined): AdwMenuModel;
+/**
+ * Where a node sits: the index chain from the model's root.
+ *
+ * A `GMenuModel` addresses its items BY POSITION and a link is a model of its own, so a
+ * position inside a submenu is only meaningful together with the positions above it.
+ * Resolving a choice by LABEL instead silently dispatches the first of two identically
+ * named entries — the defect the split button's activation vectors already pin down, one
+ * level deeper now that a menu can nest.
+ */
+export type AdwMenuPath = readonly number[];
+/** The node at a path, or `null` when the path names none. */
+export declare function menuNodeAt(model: AdwMenuModel, path: AdwMenuPath): AdwMenuNode | null;
+/** The item at a path — `null` for a path that names a section, a submenu or nothing. */
+export declare function menuItemAt(model: AdwMenuModel, path: AdwMenuPath): AdwMenuItem | null;
+/** One row of a {@link flattenMenu} walk. */
+export interface AdwMenuFlatRow {
+    /** The node this row draws. Sections never appear — they become {@link separated}. */
+    readonly node: AdwMenuItem | AdwMenuSubmenu;
+    /**
+     * Where it lives, for {@link menuItemAt}.
+     *
+     * It is also the depth: `path.length` counts the links walked to reach the row.
+     * There is no separate `depth` field, because nothing would indent by it — GTK
+     * draws a section flush with its neighbours — and a field only its own vectors read
+     * is a claim nothing holds.
+     */
+    readonly path: AdwMenuPath;
+    /** Whether a separator belongs above this row — a section boundary. */
+    readonly separated: boolean;
+}
+/**
+ * ONE LEVEL of a model as the ordered rows a list draws.
+ *
+ * SECTIONS ARE INLINED, SUBMENUS ARE NOT, and that asymmetry is `GMenuModel`'s own: a
+ * section is a visual grouping that `GtkPopoverMenu` itself draws inline with a
+ * separator, so inlining it loses a rule and no item; a submenu is a menu the user
+ * OPENS, so inlining it would put its items where they were never offered. A submenu
+ * row therefore stays a row, and a surface shows its contents by flattening THAT node's
+ * `items` when the user asks — a second popover page on the web, a second sheet on
+ * NativeScript. {@link AdwMenuFlatRow.path} is what makes the second call addressable.
+ *
+ * `separated` marks the FIRST row after a boundary and is never set on the first row of
+ * all, because a separator above nothing is a line at the top of the menu.
+ */
+export declare function flattenMenu(model: AdwMenuModel, path?: AdwMenuPath): readonly AdwMenuFlatRow[];
+/** What a `GActionGroup` publishes about one action, in portable form. */
+export interface AdwMenuAction {
+    /** `g_action_group_get_action_enabled`. Absent counts as enabled. */
+    readonly enabled?: boolean;
+    /**
+     * `g_action_group_get_action_state`, as its CONTENT in text: `true`/`false` for a
+     * toggle, `list` for a radio whose targets are strings.
+     *
+     * NOT the `GVariant` TEXT form, which would quote the string —
+     * `GLib.Variant.new_string('list').print(false)` is `'list'`, with the quotes. A
+     * consumer bridging a real `GActionGroup` writes `state.get_string()[0]` for a
+     * string and `String(state.get_boolean())` for a boolean; reading `print(false)`
+     * instead is what makes every radio row render OFF, because the target it is
+     * compared against ({@link AdwDetailedAction.target}) is unquoted too.
+     */
+    readonly state?: string;
+}
+/**
+ * The actions a surface knows about — the portable stand-in for a `GActionGroup`.
+ *
+ * Keyed by the action's own name, prefix included (`app.save-as`), which is the key a
+ * detailed action name yields. An action ABSENT from the map is missing, not disabled,
+ * and the two differ: `hidden-when="action-missing"` hides one and shows the other.
+ *
+ * NO MAP AT ALL IS A THIRD THING, and the distinction is load-bearing rather than
+ * pedantic: `{}` is a group that knows no actions, so every item in it is insensitive;
+ * `undefined` is a surface with no action group to consult, so nothing is known and
+ * nothing is dimmed. MEASURED — collapsing the two made every actioned item in the
+ * browser renderer arrive `disabled`, because the common case is a menu whose actions
+ * the host dispatches itself and never declares.
+ */
+export type AdwMenuActions = Readonly<Record<string, AdwMenuAction>>;
+/** `GtkMenuTrackerItemRole`. */
+export type AdwMenuItemRole = 'normal' | 'check' | 'radio';
+/** What an item's action makes of it. */
+export interface AdwMenuItemState {
+    /** `GTK_STATE_FLAG_INSENSITIVE`'s inverse — the action's `enabled`. */
+    readonly sensitive: boolean;
+    /** Whether the check/radio decoration is drawn. */
+    readonly toggled: boolean;
+    readonly role: AdwMenuItemRole;
+    /** Whether the item is drawn at all — `hidden-when`, folded. */
+    readonly visible: boolean;
+}
+/** An action name and the target text beside it. */
+export interface AdwDetailedAction {
+    readonly name: string;
+    /**
+     * The target's CONTENT — `list` for `app.view::list` AND for `app.view('list')`,
+     * `2` for `win.zoom(2)`.
+     *
+     * Never the `GVariant` TEXT, which would quote a string: the two spellings of the
+     * same target must compare equal, or a radio written one way and an action state
+     * read the other way disagree. MEASURED: without the unquoting,
+     * `parseDetailedAction("app.v('list')")` answered `'list'` WITH quotes and every
+     * such radio row rendered OFF against a state of `list`.
+     */
+    readonly target?: string;
+}
+/**
+ * `app.view::list` → `{ name: 'app.view', target: 'list' }`.
+ *
+ * The two forms `g_action_parse_detailed_name` accepts, and no third: `::` for a string
+ * target and `(…)` for a `GVariant` text one. A quoted `(…)` target is UNQUOTED, so
+ * `app.v::list` and `app.v('list')` — the same detailed action to GLib — yield the same
+ * target here; without that they did not, and every radio written the second way read
+ * OFF.
+ *
+ * WHAT THIS DELIBERATELY DOES NOT DO is parse the `GVariant`. The target is the text
+ * between the delimiters with its quotes removed, so comparing it against an action's
+ * `state` is a STRING comparison. That is exact for the string and boolean targets a
+ * menu actually uses, and it does not canonicalise WHITESPACE: `win.zoom(2)` and
+ * `win.zoom( 2 )` name the same action to GLib and different targets here. A portable
+ * model with no `GVariant` implementation cannot close that, and pretending otherwise
+ * would be a wrong answer instead of a stated one.
+ *
+ * IT IS ALSO NOT A VALIDATOR. It never throws and answers something for every string,
+ * because it runs on the display side of a menu that has already been accepted. GIO is
+ * the authority on whether a detailed action name is legal, and `@gjsify/gtk-host`'s
+ * `buildGioMenu` asks it — see {@link AdwMenuItem.action}.
+ */
+export declare function parseDetailedAction(detailed: string | undefined): AdwDetailedAction | null;
+/**
+ * `sensitive`, `toggled`, `role` and `visible` for one item — `gtk_menu_tracker_item_*`
+ * as a pure fold.
+ *
+ * This is the whole answer to "where does a menu carry enabled and checked", and the
+ * answer is that it does not. C reads all three off the ACTION: `sensitive` is the
+ * action's `enabled` flag (c:332), `role` is RADIO when the item has a target and the
+ * action has a state (c:336-340), CHECK when the state is a boolean and there is no
+ * target (c:342-346), and `toggled` compares the two. An item with no `action` attribute
+ * at all is SENSITIVE — C sets it explicitly in the else branch
+ * (`gtkmenutrackeritem.c:594`) rather than leaving the field false, because a label with
+ * no action is not a disabled command.
+ *
+ * TWO PLACES THIS IS NOT C, both because a portable action map carries no `GVariantType`:
+ *
+ *   · `can_activate`'s TYPE check. C refuses to activate an item whose target type does
+ *     not match the action's parameter type, and that refusal feeds
+ *     `hidden-when="action-missing"`. Here "missing" means only that the action is
+ *     absent from {@link AdwMenuActions} — a present action with a mistyped target reads
+ *     as activatable where GTK would hide it.
+ *   · A boolean state is the TEXT `'true'`/`'false'`, since the state is text. A radio
+ *     whose targets are literally those two strings would therefore read as a check.
+ *     GTK tells them apart by `GVariant` type; nothing here can.
+ *
+ * `macos-menubar` hides an item only in the macOS menubar export (C guards it with
+ * `mac_os_mode`, c:534-535), which no renderer here is, so it stays visible.
+ */
+export declare function resolveMenuItemState(item: AdwMenuItem, actions?: AdwMenuActions): AdwMenuItemState;
+/**
+ * What a surface can draw.
+ *
+ * ONE CAPABILITY, because one is what actually differs in a way a reader could not
+ * otherwise see. All three surfaces nest (GTK slides a page, the browser swaps the
+ * popover's page, NativeScript opens a second sheet) and all three draw every
+ * attribute they have a place for, so a field for those would be `true` everywhere and
+ * a refusal arm nothing could ever reach — the shape this repository pays most for. A
+ * second field lands with the first surface that needs it.
+ */
+export interface AdwMenuSurface {
+    /** A name for the diagnostic — `adwaita-web`, `nativescript`. */
+    readonly name: string;
+    /** Can it host an application widget named by `custom`? Only GTK can. */
+    readonly custom: boolean;
+}
+/** The browser popover: it has no `add_child` for a `custom` item to name. */
+export declare const ADW_MENU_SURFACE_WEB: AdwMenuSurface;
+/** The NativeScript action sheet: its rows are STRINGS, so a `custom` widget has no home. */
+export declare const ADW_MENU_SURFACE_NATIVESCRIPT: AdwMenuSurface;
+/** One thing a surface will not draw, with where it is. */
+export interface AdwMenuRefusal {
+    readonly path: AdwMenuPath;
+    /** The attribute that cannot be honoured. */
+    readonly what: 'custom';
+    readonly message: string;
+}
+/**
+ * Every part of a model the surface cannot render — empty when it can render all of it.
+ *
+ * IT LISTS WHAT WOULD VANISH, NOT WHAT WOULD LOOK DIFFERENT. An icon a sheet cannot show
+ * is a decoration and the row is still there; a `custom` item is a PLACEHOLDER for an
+ * application widget, so a surface that ignores it draws a blank row where a control
+ * belongs, and the reader has no way to tell. That is the distinction the three-way
+ * split in this file's header draws, and it is why refusing everything unsupported
+ * would be useless: NativeScript renders no icon and no accelerator on any menu, so a
+ * refusal per decoration would fire on every well-formed menu and be switched off.
+ */
+export declare function menuRefusals(model: AdwMenuModel, surface: AdwMenuSurface, path?: AdwMenuPath): AdwMenuRefusal[];
+/**
+ * Throw if the surface cannot render the model.
+ *
+ * Called by a renderer when a menu is SET, so the throw names the assignment rather than
+ * arriving as a missing row three interactions later. The message carries every refusal,
+ * not the first: a menu written for GTK typically has all of its `custom` items at once,
+ * and reporting them one run at a time is how a port becomes a series of identical bug
+ * reports.
+ */
+export declare function assertMenuRenderable(model: AdwMenuModel, surface: AdwMenuSurface): void;

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

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