@gjsify/adwaita-nativescript 0.31.0 → 0.32.0

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

@@ -1,20 +1,134 @@
-import type { StackLayout } from '@nativescript/core';
-import { AdwViewSwitcherBase, type AdwViewPage } from './view-switcher-base.js';
-export declare class AdwTabView extends AdwViewSwitcherBase {
-    /** The per-tab close buttons, parallel to {@link AdwViewSwitcherBase._buttons}. */
-    private readonly _closeButtons;
+import { GridLayout, type EventData, type View } from '@nativescript/core';
+import type { AdwTabPageSpec, TabViewPagesChange } from '@gjsify/adwaita-core';
+import { type AdwTabPage, type TabViewNotifyPayload } from './tab-view-state.js';
+import type { AdwViewPage } from './view-switcher-base.js';
+export type { AdwTabPage };
+/** Event name emitted when the selected page changes. Mirrors `notify::selected-page`. */
+export declare const NOTIFY_SELECTED_PAGE = "notify::selected-page";
+/** Event name emitted for every page-list change (attach / detach / reorder / pin / update). */
+export declare const PAGES_CHANGED = "pages-changed";
+/** Event name emitted for every close ATTEMPT, before the verdict is applied. */
+export declare const CLOSE_PAGE = "close-page";
+/** Payload of {@link NOTIFY_SELECTED_PAGE}. */
+export interface NotifySelectedPageEventData extends EventData, TabViewNotifyPayload {
+}
+/** Payload of {@link PAGES_CHANGED} — the core's page-list change, verbatim. */
+export interface PagesChangedEventData extends EventData, TabViewPagesChange {
+}
+/** Payload of {@link CLOSE_PAGE}. */
+export interface ClosePageEventData extends EventData {
+    /** The page being asked about. */
+    id: string;
+    /** Its index while it is still in the view. */
+    index: number;
+}
+export declare class AdwTabView extends GridLayout {
+    private readonly _state;
+    private readonly _bar;
+    private readonly _contentArea;
+    /** Tab chips keyed by page id — the bar is edited in place, never rebuilt. */
+    private readonly _chips;
+    private _autohide;
+    private _defaultIcon;
+    private _generatedIds;
+    /**
+     * The `close-page` decision seam. Return `true` to confirm, `false` to deny,
+     * `'defer'` to hold the page until {@link closePageFinish} — which is how an
+     * app shows a "save before closing?" dialog. Unset takes libadwaita's own
+     * default, `!page.pinned` (adw-tab-view.c:1990-1991).
+     *
+     * A PROPERTY rather than an event return value because NS events cannot
+     * carry one; {@link CLOSE_PAGE} still fires for every attempt, so observing
+     * and deciding stay separable.
+     */
+    closeHandler: ((page: AdwTabPage) => boolean | 'defer') | null;
     constructor();
-    protected get barClass(): string;
-    protected get buttonClass(): string;
-    /** Append a small ✕ close button to each tab (shown only when active). */
-    protected _buildButtonExtras(button: StackLayout, _page: AdwViewPage, index: number): void;
-    /** Reveal the close button only on the active tab (touch analogue of hover). */
-    protected _applyButtonState(_button: StackLayout, index: number, active: boolean): void;
-    /** Remove a tab + its page (no-op when only one tab remains). */
-    private _closeTab;
-    /** Rebuild from scratch — drop the stale per-tab close-button refs first. */
+    /** All pages in order. */
+    get pages(): readonly AdwTabPage[];
+    /** 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 — never 0 for an empty view. */
+    get selectedIndex(): number;
+    /** The selected page index. Setting it IGNORES a non-integer or out-of-range value. */
+    get selected(): number;
+    set selected(value: number);
+    isClosing(id: string): boolean;
+    setSelectedPage(id: string | null): boolean;
+    selectNthPage(n: number): boolean;
+    selectPreviousPage(): boolean;
+    selectNextPage(): boolean;
+    selectFirstPage(): boolean;
+    selectLastPage(): boolean;
+    /** The next page, WRAPPING to the first (Ctrl+Tab). */
+    cycleNextPage(): boolean;
+    /** The previous page, WRAPPING to the last (Ctrl+Shift+Tab). */
+    cyclePreviousPage(): boolean;
+    /** Add a page opened FROM `parentId`, deriving its position (Adw.TabView.add_page). */
+    addPage(spec: AdwTabPageSpec<View>, parentId?: string | null): number;
+    insertPage(spec: AdwTabPageSpec<View>, position: number): number;
+    prependPage(spec: AdwTabPageSpec<View>): number;
+    appendPage(spec: AdwTabPageSpec<View>): number;
+    insertPinnedPage(spec: AdwTabPageSpec<View>, position: number): number;
+    prependPinnedPage(spec: AdwTabPageSpec<View>): number;
+    appendPinnedPage(spec: AdwTabPageSpec<View>): number;
+    /** Pin or unpin a page, re-ordering it in the same step. Returns its new position. */
+    setPagePinned(id: string, pinned: boolean): number;
+    /** Request a close. Fires {@link CLOSE_PAGE}, then applies {@link closeHandler}'s verdict. */
+    closePage(id: string): boolean;
+    closePageFinish(id: string, confirm: boolean): boolean;
+    closeOtherPages(id: string): void;
+    closePagesBefore(id: string): void;
+    closePagesAfter(id: string): void;
+    /** Remove a page unconditionally, running the successor rule first. */
+    detachPage(id: string): AdwTabPage | null;
+    reorderPage(id: string, position: number): boolean;
+    reorderBackward(id: string): boolean;
+    reorderForward(id: string): boolean;
+    reorderFirst(id: string): boolean;
+    reorderLast(id: string): boolean;
+    setPageTitle(id: string, title: string | null): boolean;
+    setPageIcon(id: string, icon: string | null): boolean;
+    setPageLoading(id: string, loading: boolean): boolean;
+    setPageNeedsAttention(id: string, needsAttention: boolean): boolean;
+    /** Every precondition the model refused, as C would have warned about it. */
+    get diagnostics(): readonly string[];
+    /**
+     * Whether the tab bar hides itself when it has nothing to show
+     * (`Adw.TabBar:autohide`, adw-tab-bar.c:142-164). Defaults to `false` rather
+     * than to the platform's `DEFAULT_TAB_AUTOHIDE`, so a bar that was always
+     * visible before this lift stays visible unless asked otherwise.
+     */
+    get autohide(): boolean;
+    set autohide(value: boolean);
+    /** `Adw.TabView:default-icon` — what a PINNED page with no icon of its own shows. */
+    get defaultIcon(): string | null;
+    set defaultIcon(value: string | null);
+    /**
+     * Replace every page from a plain `{ title, content, icon? }` list.
+     *
+     * Kept because that was this widget's only API before the lift, when it
+     * derived from `AdwViewSwitcherBase` and rebuilt the whole bar on every
+     * change. It now goes through the model — each entry becomes an appended page
+     * with a generated id — so the incremental bar, the close protocol and the
+     * selection rules apply to it too.
+     */
     setViews(pages: AdwViewPage[]): void;
-    /** The tab pages — an alias of the shared {@link AdwViewSwitcherBase.views}. */
+    /** The pages as a plain list — the shape {@link setViews} takes. */
+    get views(): AdwViewPage[];
+    set views(pages: AdwViewPage[]);
+    /** Alias of {@link views}, matching the widget's own vocabulary. */
     get tabs(): AdwViewPage[];
     set tabs(pages: AdwViewPage[]);
+    private _onPagesChange;
+    private _insertChip;
+    private _refreshChip;
+    /** Show only the selected page, mark its chip active, gate the close buttons. */
+    private _applySelection;
+    private _applyBarVisibility;
+    private _requestClose;
+    private _nextId;
 }

package/lib/types/widgets/adw-toolbar-view.d.ts

@@ -1,4 +1,5 @@
 import { GridLayout, StackLayout, View } from '@nativescript/core';
+import { type AdwToolbarStyle } from './chrome.js';
 export declare class AdwToolbarView extends GridLayout {
     /** The top-bar slot (row 0) — stack of header bars / toolbars. */
     protected readonly _topBox: StackLayout;
@@ -6,6 +7,7 @@ export declare class AdwToolbarView extends GridLayout {
     protected readonly _bottomBox: StackLayout;
     /** The currently-installed content view (row 1), if any. */
     private _content;
+    private _props;
     constructor();
     /** Append a widget (e.g. an {@link AdwHeaderBar}) to the top-bar slot. */
     addTopBar(view: View): void;
@@ -19,4 +21,41 @@ export declare class AdwToolbarView extends GridLayout {
     get topBar(): StackLayout;
     /** The bottom-bar slot container. */
     get bottomBar(): StackLayout;
+    /** `Adw.ToolbarView:top-bar-style` — `flat` (default), `raised` or `raised-border`. */
+    get topBarStyle(): AdwToolbarStyle;
+    set topBarStyle(value: AdwToolbarStyle);
+    /** `Adw.ToolbarView:bottom-bar-style` — `flat` (default), `raised` or `raised-border`. */
+    get bottomBarStyle(): AdwToolbarStyle;
+    set bottomBarStyle(value: AdwToolbarStyle);
+    /** `Adw.ToolbarView:extend-content-to-top-edge` — draw the top bar OVER the content. */
+    get extendContentToTopEdge(): boolean;
+    set extendContentToTopEdge(value: boolean);
+    /** `Adw.ToolbarView:extend-content-to-bottom-edge` — draw the bottom bar OVER the content. */
+    get extendContentToBottomEdge(): boolean;
+    set extendContentToBottomEdge(value: boolean);
+    /**
+     * Put each bar box in its own row, or — when the content extends under it —
+     * in the CONTENT row pinned to that edge, which is how an NS `GridLayout`
+     * spells "the content spans the full height and the bar overlays it".
+     */
+    private _applyBarPlacement;
+    /**
+     * Re-append the bar boxes so they sit ON TOP of the content.
+     *
+     * NativeScript paints siblings in add order, and an extended bar shares a
+     * grid cell with the content — which is added later, so without this the
+     * content would cover the very bar it is supposed to scroll under. A no-op
+     * while neither edge is extended, since the boxes then have their own rows.
+     */
+    private _restackBars;
+    /**
+     * Re-derive the four libadwaita style classes from the current state.
+     *
+     * Composed against the CURRENT class names rather than the base ones, so a
+     * class a consumer appended survives (the storybook appends
+     * `sb-sidebar-pane` to one of these). Each assignment is guarded on a real
+     * change: this runs from `layoutChanged`, and re-styling a view can schedule
+     * another layout pass.
+     */
+    private _syncClasses;
 }

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

@@ -1,46 +1,49 @@
 import { GridLayout, View, type EventData } from '@nativescript/core';
+import { type AdwViewStackPage, type ViewStackNotifyPayload } from './view-stack-state.js';
+export type { AdwViewStackPage };
 /** Event name emitted when the visible child changes. Mirrors GObject `notify::visible-child`. */
 export declare const NOTIFY_VISIBLE_CHILD = "notify::visible-child";
-/** Payload of the {@link NOTIFY_VISIBLE_CHILD} event. */
-export interface NotifyVisibleChildEventData extends EventData {
-    /** The newly-visible page's index. */
-    index: number;
-    /** The newly-visible page's name. */
-    name: string;
-    /** The newly-visible page's title. */
-    title: string;
-}
-/** One page registered with an {@link AdwViewStack}. */
-export interface AdwViewStackPage {
-    /** Stable identifier used by `visibleChildName` / switcher binding. */
-    name: string;
-    /** Human-facing title shown in a bound switcher button. */
-    title: string;
-    /** Optional Adwaita symbolic SVG shown in a bound switcher button. */
-    icon?: string;
-    /** The page content view, shown when this page is selected. */
-    content: View;
+/**
+ * Payload of the {@link NOTIFY_VISIBLE_CHILD} event. `index` is `-1` and
+ * `name`/`title` are `''` when nothing is selected — the state an empty stack, a
+ * fully-hidden stack and a removed visible page all land in.
+ */
+export interface NotifyVisibleChildEventData extends EventData, ViewStackNotifyPayload {
 }
 export declare class AdwViewStack extends GridLayout {
-    private readonly _pages;
-    private _visibleIndex;
+    private readonly _state;
     constructor();
     /**
-     * Register a page. The FIRST page added becomes visible automatically so the
-     * stack is never empty, matching `Adw.ViewStack`. Returns the page handle.
+     * Register a page. It becomes visible when nothing is selected yet — and,
+     * unlike before, that auto-pick NOTIFIES, so a bound switcher highlights the
+     * initial page without a manual `refresh()` (`add_page`,
+     * adw-view-stack.c:1149-1151 → the notify at :1038-1039). Returns the page handle.
      */
     add(content: View, name: string, title?: string, icon?: string): AdwViewStackPage;
     /** Convenience alias matching `Adw.ViewStack.add_titled`. */
     addTitled(content: View, name: string, title: string): AdwViewStackPage;
+    /**
+     * Remove the first page named `name` and detach its content view. 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).
+     */
+    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).
+     */
+    setPageVisible(name: string, visible: boolean): boolean;
     /** All registered pages, in add order (a bound switcher reads this). */
     get pages(): readonly AdwViewStackPage[];
-    /** The visible page index. Swaps the visible page + emits `notify::visible-child`. */
+    /** The visible page index, `-1` when nothing is selected. Swaps the visible page + emits. */
     get visibleChildIndex(): number;
     set visibleChildIndex(value: number);
-    /** The visible page name (`Adw.ViewStack.visible-child-name`). */
+    /** The visible page name (`Adw.ViewStack.visible-child-name`), `''` for none. */
     get visibleChildName(): string;
-    set visibleChildName(name: string);
+    set visibleChildName(name: string | null | undefined);
     /** The visible page content view, or `null`. */
     get visibleChild(): View | null;
-    private _apply;
 }

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

@@ -3,11 +3,10 @@ import { AdwViewStack } from './adw-view-stack.js';
 export declare class AdwViewSwitcherBar extends GridLayout {
     /** The horizontal (homogeneous) row of buttons. */
     private readonly _bar;
-    /** The tappable button containers, one per stack page, in page order. */
-    private readonly _buttons;
+    private _nodes;
     private _stack;
     private _stackListener;
-    private _revealed;
+    private readonly _barState;
     constructor();
     /** Bind to an {@link AdwViewStack}: build buttons from its pages + two-way sync. */
     setStack(stack: AdwViewStack | null): void;
@@ -15,15 +14,28 @@ export declare class AdwViewSwitcherBar extends GridLayout {
     get stack(): AdwViewStack | null;
     set stack(value: AdwViewStack | null);
     /**
-     * Whether the bar is shown (`Adw.ViewSwitcherBar.reveal`). An adaptive layout
-     * sets this `true` on narrow screens and `false` on wide ones (where a header-bar
-     * `AdwViewSwitcher` takes over).
+     * Whether the layout asked for the bar — `Adw.ViewSwitcherBar:reveal`. An
+     * adaptive layout sets it `true` on narrow screens and `false` on wide ones,
+     * where a header-bar `AdwViewSwitcher` takes over.
+     */
+    get reveal(): boolean;
+    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).
+     * Write {@link reveal} to make the request.
      */
     get revealed(): boolean;
-    set revealed(value: boolean);
-    /** Rebuild the button row from the bound stack's pages (call after late page adds). */
+    /**
+     * Rebuild the button row from the bound stack's pages — needed after pages
+     * were added without changing the stack's selection. libadwaita rebuilds on
+     * the pages model's `items-changed` (adw-view-switcher.c:258-263), which the
+     * NS stack has no counterpart for.
+     */
     refresh(): void;
+    private _bindStack;
+    private _unbindStack;
     private _rebuild;
-    /** Mark the button for the stack's visible page active (accent label via CSS). */
-    private _syncActive;
+    private _buildButton;
+    private _applyRevealed;
 }

package/lib/types/widgets/adw-window-title.d.ts

@@ -1,19 +1,23 @@
 import { Label, StackLayout } from '@nativescript/core';
+/** Event name emitted when {@link AdwWindowTitle.title} changes. */
+export declare const NOTIFY_TITLE = "notify::title";
+/** Event name emitted when {@link AdwWindowTitle.subtitle} changes. */
+export declare const NOTIFY_SUBTITLE = "notify::subtitle";
 export declare class AdwWindowTitle extends StackLayout {
     /** The bold title label. */
     protected readonly _titleLabel: Label;
-    /** The dim subtitle label (created lazily — only in the tree when set). */
+    /** The dim subtitle label. */
     protected readonly _subtitleLabel: Label;
-    private _hasSubtitle;
+    /** The headless title/subtitle pair + change detection (ADR 0004). */
+    private readonly _state;
     constructor();
-    /** The window title (bold, top line). */
+    /** The window title (bold, top line). Empty collapses its label. */
     get title(): string;
     set title(value: string);
-    /**
-     * The subtitle (dim second line). Setting a non-empty value adds the subtitle
-     * label; setting empty removes it — so an empty subtitle leaves no blank gap,
-     * matching `Adw.WindowTitle`.
-     */
+    /** The subtitle (dim second line). Empty collapses its label. */
     get subtitle(): string;
     set subtitle(value: string);
+    /** Push the derived text + visibility onto the two `Label`s. */
+    private _apply;
+    private _notify;
 }

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

@@ -3,15 +3,32 @@ export declare class AdwWrapBox extends WrapLayout {
     private _childSpacing;
     private _lineSpacing;
     constructor();
-    /** Append a child; applies the uniform child/line spacing as a margin. */
+    /** Append a child. */
     add(view: View): void;
     /** Remove a previously-added child. */
     remove(view: View): void;
-    private _applySpacing;
-    /** Horizontal gap between items in a line, in DIPs. */
+    /**
+     * Every path a child can enter by — `add()`, a direct `addChild()`, and XML
+     * inflation via `_addChildFromBuilder` — ends here, which is why the spacing
+     * is applied here and not in `add()`. It used to be applied in `add()` only,
+     * so a child declared in markup got no spacing at all; C routes GtkBuildable's
+     * `add_child` through the same append for the same reason.
+     */
+    addChild(view: View): void;
+    /** Horizontal gap between items in a line, in DIPs. Defaults to 0, as in C. */
     get childSpacing(): number;
     set childSpacing(value: number);
-    /** Vertical gap between wrapped lines, in DIPs. */
+    /** Vertical gap between wrapped lines, in DIPs. Defaults to 0, as in C. */
     get lineSpacing(): number;
     set lineSpacing(value: number);
+    /**
+     * Re-apply the spacing to every child already in the tree.
+     *
+     * The spacing used to be baked in at add time, so `box.childSpacing = 12`
+     * after the children were added did nothing; `adw_wrap_box_set_child_spacing`
+     * hands the new value to the layout manager, which re-runs the allocation for
+     * children that are already there.
+     */
+    private _applySpacingToChildren;
+    private _applySpacing;
 }

package/lib/types/widgets/avatar-color.d.ts

@@ -0,0 +1,14 @@
+import { avatarInitials } from '@gjsify/adwaita-core';
+export { avatarInitials };
+/** A flat avatar fill plus the light initials colour that goes on top of it. */
+export interface NsAvatarColor {
+    /** The gradient collapsed to a single `#rrggbb` background. */
+    fill: string;
+    /** The palette's light `fg`, for the initials label. */
+    fg: string;
+}
+/**
+ * The fill + initials colour `Adw.Avatar` would paint for `text`, flattened for
+ * the NativeScript CSS subset.
+ */
+export declare function avatarColor(text: string): NsAvatarColor;

package/lib/types/widgets/bottom-sheet-state.d.ts

@@ -0,0 +1,73 @@
+import type { EventData, View } from '@nativescript/core';
+import { BottomSheetPresentation } from '@gjsify/adwaita-core';
+import type { BottomSheetCloseOutcome, BottomSheetCloseSource } from '@gjsify/adwaita-core';
+/** Event name emitted when the sheet's open state changes. Mirrors GObject `notify::open`. */
+export declare const NOTIFY_OPEN = "notify::open";
+/**
+ * Event name emitted when a dismissal is refused. Mirrors the
+ * `AdwBottomSheet::close-attempt` signal (adw-bottom-sheet.c:1010-1026).
+ */
+export declare const CLOSE_ATTEMPT = "close-attempt";
+/**
+ * Event name emitted when the `sheet.close` action is used on an ALREADY-closed
+ * sheet, so the host can forward it to an enclosing sheet/dialog — the NS
+ * equivalent of `gtk_widget_activate_action (parent, "sheet.close")`
+ * (adw-bottom-sheet.c:382-385).
+ */
+export declare const SHEET_CLOSE = "sheet.close";
+/** Payload of the `notify::open` event. */
+export interface NotifyOpenEventData extends EventData {
+    /** Whether the sheet is now open. */
+    open: boolean;
+}
+/** The two `View.visibility` values the sheet panel ever takes. */
+export type NsSheetVisibility = 'visible' | 'collapse';
+/** The open/can-close model an `AdwBottomSheet` delegates to. */
+export declare function createBottomSheetPresentation(): BottomSheetPresentation;
+/**
+ * The `visibility` the sheet panel must carry for the current open state. NS has
+ * no transform transition in its CSS subset, so the reveal is instant — the
+ * spring animation and its intermediate `progress` are not modelled here.
+ */
+export declare function sheetVisibility(open: boolean): NsSheetVisibility;
+/** Push {@link sheetVisibility} onto the real panel view. */
+export declare function applySheetVisibility(panel: View, open: boolean): void;
+/**
+ * Which event a gate verdict makes the widget emit, or `null` when it emits
+ * nothing.
+ *
+ * `'close'` is absent on purpose: the state applies it, and the resulting
+ * `notify::open` IS the notification. `'ignored'` is the genuinely silent one —
+ * a locked sheet swallowing a swipe, or a tap on the decorative drag handle.
+ */
+export declare function bottomSheetCloseEvent(outcome: BottomSheetCloseOutcome): string | null;
+/** What a dismissal request produced: the verdict plus the event to emit, if any. */
+export interface BottomSheetCloseResult {
+    /** The gate's verdict, already applied to the state. */
+    outcome: BottomSheetCloseOutcome;
+    /** Event name for `notify()`, or `null` when the gate is silent. */
+    eventName: string | null;
+}
+/**
+ * The whole of `AdwBottomSheet.requestClose` except the `notify()` call.
+ *
+ * It lives HERE rather than inside the `extends GridLayout` module so the spec
+ * can drive the real path: a spec that re-assembled `state.requestClose()` and
+ * `bottomSheetCloseEvent()` itself would be transcribing the code under test and
+ * could not detect the drift it exists to catch.
+ */
+export declare function requestBottomSheetClose(state: BottomSheetPresentation, source: BottomSheetCloseSource): BottomSheetCloseResult;
+/**
+ * Add a marker class to a view's `className` exactly once.
+ *
+ * libadwaita never writes to the child's own style classes — the marker lives on
+ * the internal bin (`adw_bottom_sheet_set_content`, adw-bottom-sheet.c:1497-1510).
+ * This port does write it, and used to do so with a bare string concat, so
+ * `setContent(v)` twice left `'adw-bottom-sheet-content adw-bottom-sheet-content'`.
+ */
+export declare function addMarkerClass(className: string | null | undefined, marker: string): string;
+/**
+ * Drop a marker class again — a view replaced by another must not keep the
+ * marker of the slot it no longer occupies.
+ */
+export declare function removeMarkerClass(className: string | null | undefined, marker: string): string;

package/lib/types/widgets/button-content.d.ts

@@ -0,0 +1,43 @@
+import { BUTTON_CONTENT_STYLE_CLASS, buttonContentEllipsize, buttonContentLabelText, buttonContentLabelVisible } from '@gjsify/adwaita-core';
+import type { ButtonContentEllipsize } from '@gjsify/adwaita-core';
+export { BUTTON_CONTENT_STYLE_CLASS, buttonContentEllipsize, buttonContentLabelText, buttonContentLabelVisible };
+export type { ButtonContentEllipsize };
+/** The class the content carries while `can-shrink` is set, for the theme to key off. */
+export declare const BUTTON_CONTENT_CAN_SHRINK_CLASS = "can-shrink";
+/**
+ * The SVG the icon view is given: the app's, or the `image-missing` asset for an
+ * empty slot.
+ *
+ * That fallback is `gtk_image_set_from_icon_name (icon, "image-missing")`
+ * (adw-button-content.c:355-356), applied by `init` too while `icon_name` is
+ * still `""` (:284, :294). The widget NEVER hides the image — only the label
+ * (:300, :398) — so this port keeps the icon view parented at all times and
+ * swaps its source, which is the same shape as the C. The doc comments at :228
+ * and :343 claim the icon is hidden instead; the code disagrees with them and
+ * this follows the code (see the conformance vector's `rule`).
+ */
+export declare function buttonContentIconSvg(svg: string): string;
+/** Whether the icon shown is the empty-slot fallback rather than an app asset. */
+export declare function buttonContentIconIsFallback(svg: string): boolean;
+/**
+ * The parent button's `className` with `image-text-button` added — the root-time
+ * half of `adw_button_content_root` (:115).
+ *
+ * Adds rather than rewrites, so the `adw-button suggested-action pill` a caller
+ * composed survives; and it is idempotent, so a re-parent cannot double the
+ * token.
+ */
+export declare function buttonContentRootedParentClassName(current: string): string;
+/**
+ * The parent button's `className` with `image-text-button` removed — the unroot
+ * half (:126).
+ *
+ * The C removes it on unroot rather than leaving it behind, so a button that
+ * loses its content goes back to plain-button padding. A port that only ever
+ * added the class would leave the 9px on a button that is now text-only.
+ */
+export declare function buttonContentUnrootedParentClassName(current: string): string;
+/** The label view's `visibility` — NS's spelling of `gtk_widget_set_visible` (:398). */
+export declare function buttonContentLabelVisibility(label: string): 'visible' | 'collapse';
+/** The content's own `className` for a `can-shrink` value, other tokens untouched. */
+export declare function buttonContentClassName(current: string, canShrink: boolean): string;

package/lib/types/widgets/carousel-state.d.ts

@@ -0,0 +1,85 @@
+import type { Label } from '@nativescript/core';
+import { CarouselState } from '@gjsify/adwaita-core';
+import type { CarouselScrollRequest, CarouselStateChange } from '@gjsify/adwaita-core';
+/**
+ * Default page width (DIPs) used for offset math until the consumer sets
+ * `pageWidth`. libadwaita MEASURES its pages (adw-carousel.c:739-765); NS gives
+ * a widget no size before its first layout pass, so a plausible phone-width
+ * default keeps the offsets sane until the consumer supplies the real one.
+ */
+export declare const DEFAULT_CAROUSEL_PAGE_WIDTH = 320;
+/** Construction seams an `AdwCarousel` hands to its state machine. */
+export interface NsCarouselStateOptions {
+    /** Clock for the wheel lockout — injected so a spec can step past it. */
+    now?: () => number;
+    /** Invoked for every accepted scroll; the widget turns it into a `scrollToHorizontalOffset`. */
+    onScrollTo?: (request: CarouselScrollRequest) => void;
+}
+/**
+ * The state machine an `AdwCarousel` delegates to.
+ *
+ * `animateScroll` is FALSE: the `ScrollView` animates the pixels, but it reports
+ * nothing until it has, and on an untested platform it may report nothing at
+ * all. Keeping the model authoritative means a `scrollToPage` is correct the
+ * instant it is called, which is also what the port did before the lift —
+ * {@link CarouselScrollSync} is what keeps the two from fighting.
+ */
+export declare function createCarouselState(options?: NsCarouselStateOptions): CarouselState;
+/** A page width that can be divided by — anything else falls back to the default. */
+export declare function normalizeCarouselPageWidth(value: number): number;
+/** The horizontal scroll offset in DIPs for a position — `distance * position` (adw-carousel.c:797-801). */
+export declare function carouselScrollOffset(position: number, distance: number): number;
+/** The inverse: the position a `ScrollView` at `offset` is showing. */
+export declare function carouselPositionAtOffset(offset: number, distance: number): number;
+/**
+ * Keeps the model in step with a `ScrollView` that animates its own scrolls.
+ *
+ * Without this the two fight: the widget moves the model the moment
+ * `scrollToPage` is called, then the animation replays every intermediate offset
+ * back at it, so the dots would run backwards to where the scroll STARTED and
+ * crawl forward again, emitting a second `page-changed` on arrival.
+ *
+ * So a programmatic scroll declares its destination with {@link expect}, and
+ * every offset before that destination is ignored. A scroll nobody declared is a
+ * user swipe and drives the model directly — which is how a free flick gets a
+ * fractional position at all, something the port had no way to observe.
+ */
+export declare class CarouselScrollSync {
+    /** Position a programmatic scroll is animating towards, `null` while idle. */
+    private _expected;
+    /** Declare where a programmatic scroll is heading; its intermediate offsets are then ignored. */
+    expect(position: number): void;
+    /**
+     * Feed one `ScrollView` scroll event. Returns whether the model was updated
+     * — `false` while a programmatic scroll is still in flight.
+     */
+    apply(state: CarouselState, position: number, epsilon?: number): boolean;
+}
+/** The class string each dot `Label` must carry, in page order. */
+export declare function carouselDotClasses(state: CarouselState): string[];
+/**
+ * Push {@link carouselDotClasses} onto the real dot labels.
+ *
+ * The selected dot comes from `get_page_at_position` (adw-carousel.c:222-239),
+ * not from `Math.round`, so a carousel resting half-way between two pages marks
+ * the LOWER one — and, unlike the integer compare this replaces, it marks
+ * something at all while a swipe is in progress.
+ */
+export declare function applyCarouselDots(state: CarouselState, dots: readonly Label[]): void;
+/** The data half of the `notify::position` event (minus NS's `eventName`/`object`). */
+export interface CarouselNotifyPayload {
+    /** The clamped fractional scroll position. */
+    position: number;
+    /** The number of pages. */
+    nPages: number;
+    /** The page the position settles on, `-1` when the carousel is empty. */
+    page: number;
+    /** `true` for a user navigation (swipe, dot tap, keynav). */
+    interactive: boolean;
+}
+/**
+ * Project a core change onto the event payload. Kept as a function rather than
+ * spreading the change so the internal `reason` discriminator — which names a C
+ * notification site, not an NS event — never leaks into consumer code.
+ */
+export declare function carouselNotifyPayload(change: CarouselStateChange): CarouselNotifyPayload;