@gjsify/adwaita-nativescript 0.31.0 → 0.32.0

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

@@ -0,0 +1,74 @@
+import type { View } from '@nativescript/core';
+import { TabViewState } from '@gjsify/adwaita-core';
+import type { AdwTabPageState, TabViewHandlers, TabViewSelectionChange } from '@gjsify/adwaita-core';
+/** One page of an `AdwTabView`, as a renderer reads it. */
+export type AdwTabPage = AdwTabPageState<View>;
+/** The two `View.visibility` values a stacked page or a tab affordance ever takes. */
+export type NsVisibility = 'visible' | 'collapse';
+/** The model an `AdwTabView` delegates to, typed on the NS `View`. */
+export declare function createTabViewState(handlers?: TabViewHandlers<View>): TabViewState<View>;
+/**
+ * The `visibility` each page's content view must carry for the current
+ * selection, in page order. Exactly one entry is `'visible'` — none when nothing
+ * is selected, which is a real state here: closing the last tab EMPTIES the view
+ * (adw-tab-view.c:1912-1913), where the old port refused the close outright.
+ */
+export declare function tabPageVisibilities(state: TabViewState<View>): NsVisibility[];
+/** Push {@link tabPageVisibilities} onto the real content views. */
+export declare function applyTabViewVisibility(state: TabViewState<View>): void;
+/**
+ * The `visibility` each tab's close button must carry, in page order.
+ *
+ * `tabCloseVisible` is `(hovering && fullyVisible) || selected || dragging`, and
+ * never on a pinned tab (adw-tab.c:124, :645-650). Touch has no hover and this
+ * port has no tab drag-and-drop, so `hovering` and `dragging` are constantly
+ * false and the predicate REDUCES to "selected, and not pinned" — which is the
+ * old port's rule plus the pinned gate it was missing. Calling the shared
+ * predicate rather than writing `active` keeps that a derivation instead of a
+ * coincidence, and gives the pinned gate for free.
+ */
+export declare function tabCloseVisibilities(state: TabViewState<View>): NsVisibility[];
+/**
+ * The `visibility` of the whole tab bar — `tabsRevealed` (adw-tab-bar.c:142-164)
+ * projected onto NS. The old port had no autohide at all; the bar was added in
+ * the constructor and never hidden.
+ */
+export declare function tabBarVisibility(state: TabViewState<View>, autohide: boolean): NsVisibility;
+/**
+ * The text a tab's label shows.
+ *
+ * A pinned tab is a single-glyph chip in libadwaita — `adw_tab_constructed`
+ * hides its title outright (adw-tab.c:645-650) — so it renders no label at all
+ * here either. Everything else shows its title, which is already `''` rather
+ * than `undefined` for a page that declared none: the old port assigned
+ * `page.title` straight to `Label.text` with no coercion, so an `AdwViewPage`
+ * literal without a title rendered the string "undefined".
+ */
+export declare function tabLabelText(page: AdwTabPage): string;
+/**
+ * The tooltip text for a tab — `tabTooltip`, i.e. the page's own tooltip when it
+ * has one and its title otherwise (adw-tab.c:137-146).
+ *
+ * NS has no tooltip primitive, so this is exposed for a consumer (and for the
+ * accessibility label) rather than rendered. It is deliberately the TEXT form:
+ * a page-supplied tooltip is Pango markup in C, and NS has no markup sink to
+ * push it through.
+ */
+export declare function tabTooltipText(page: AdwTabPage): string;
+/** The data half of the `notify::selected-page` event (minus NS's `eventName`/`object`). */
+export interface TabViewNotifyPayload {
+    /** Id of the newly-selected page, `null` when the view is empty. */
+    selectedId: string | null;
+    /** Its index, `-1` when the view is empty. */
+    selectedIndex: number;
+    /** The previously-selected id, `null` when there was none. */
+    previousId: string | null;
+    /** `false` for a model-driven pick (auto-select, close successor), `true` otherwise. */
+    interactive: boolean;
+}
+/**
+ * Project a core change onto the event payload. Kept as a function rather than
+ * spreading the change directly so that if the core payload ever grows a live
+ * model object, it does not silently leak into an event a consumer holds on to.
+ */
+export declare function tabViewNotifyPayload(change: TabViewSelectionChange): TabViewNotifyPayload;

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

@@ -0,0 +1,35 @@
+import type { View } from '@nativescript/core';
+import { ViewStackState } from '@gjsify/adwaita-core';
+import type { AdwViewStackPageInfo, ViewStackStateChange } from '@gjsify/adwaita-core';
+/** One page registered with an `AdwViewStack`, as a bound switcher reads it. */
+export type AdwViewStackPage = AdwViewStackPageInfo<View>;
+/** The two `View.visibility` values a stacked page ever takes. */
+export type NsPageVisibility = 'visible' | 'collapse';
+/** The selection machine an `AdwViewStack` delegates to, typed on the NS `View`. */
+export declare function createViewStackState(): ViewStackState<View>;
+/**
+ * The `visibility` each page's content view must carry for the current
+ * selection, in page order. Exactly one entry is `'visible'` — none when nothing
+ * is selected, which is a real state here (an empty stack, every page hidden, or
+ * the visible page removed).
+ */
+export declare function pageVisibilities(state: ViewStackState<View>): NsPageVisibility[];
+/** Push {@link pageVisibilities} onto the real content views. */
+export declare function applyViewStackVisibility(state: ViewStackState<View>): void;
+/** The data half of the `notify::visible-child` event (minus NS's `eventName`/`object`). */
+export interface ViewStackNotifyPayload {
+    /** The newly-visible page's index, `-1` when nothing is selected. */
+    index: number;
+    /** The newly-visible page's name, `''` when nothing is selected. */
+    name: string;
+    /** The newly-visible page's title, `''` when nothing is selected. */
+    title: string;
+    /** `false` for an auto-pick (add / hide / show), `true` for an explicit select. */
+    interactive: boolean;
+}
+/**
+ * Project a core change onto the event payload. Kept as a function rather than
+ * spreading the change directly so the `page` descriptor — a live model object —
+ * never leaks into an event a consumer might hold on to.
+ */
+export declare function viewStackNotifyPayload(change: ViewStackStateChange<View>): ViewStackNotifyPayload;

package/lib/types/widgets/view-switcher-base.d.ts

@@ -1,21 +1,15 @@
-import { GridLayout, StackLayout, View, type EventData } from '@nativescript/core';
+import { GridLayout, StackLayout, type EventData } from '@nativescript/core';
+import type { AdwInlineViewSwitcherDisplayMode, AdwViewSwitcherPolicy, ViewSwitcherState } from '@gjsify/adwaita-core';
+import { type AdwViewPage, type ViewSwitcherKind, type ViewSwitcherNotifyPayload } from './view-switcher-model.js';
+export type { AdwViewPage };
 /** Event name emitted when the selected view changes. Mirrors GObject `notify::selected`. */
 export declare const NOTIFY_SELECTED = "notify::selected";
-/** Payload of the `notify::selected` event. */
-export interface NotifyViewSelectedEventData extends EventData {
-    /** The newly-selected view index. */
-    selected: number;
-    /** The newly-selected view's title. */
-    title: string;
-}
-/** One page registered with a {@link AdwViewSwitcherBase}. */
-export interface AdwViewPage {
-    /** The switcher button label. */
-    title: string;
-    /** The page content view, shown when this page is selected. */
-    content: View;
-    /** Optional Adwaita symbolic SVG shown left of the label in the switcher button. */
-    icon?: string;
+/**
+ * Payload of the `notify::selected` event. `selected` is `-1` and `name`/`title`
+ * are `''` when nothing is selected — the state an empty switcher and a
+ * fully-hidden one both land in.
+ */
+export interface NotifyViewSelectedEventData extends EventData, ViewSwitcherNotifyPayload {
 }
 /**
  * Shared base: a switcher bar (row 0) + a content area (row 1), one page visible.
@@ -26,37 +20,72 @@ export declare abstract class AdwViewSwitcherBase extends GridLayout {
     protected readonly _bar: StackLayout;
     /** The content area where the selected page is shown. */
     protected readonly _contentArea: GridLayout;
+    /** The registered pages, in bar order. */
     protected readonly _pages: AdwViewPage[];
-    /** The tappable button containers (one per page), in bar order. */
-    protected readonly _buttons: StackLayout[];
-    protected _selected: number;
+    /** The headless selection + page model every derivation reads. */
+    protected readonly _state: ViewSwitcherState;
+    private _nodes;
     /** CSS class applied to the switcher bar — subclass-specific. */
     protected abstract get barClass(): string;
     /** CSS class applied to each switcher button — subclass-specific. */
     protected abstract get buttonClass(): string;
+    /**
+     * `AdwViewSwitcher:policy`, which decides the button orientation
+     * (adw-view-switcher.c:534-537). `'wide'` — icon beside label — because that
+     * is the layout all three NS switchers have always used; the icon-over-label
+     * narrow form lives in the separate `AdwViewSwitcherBar`. There is no policy
+     * PROPERTY on NS yet, so this is a constant a subclass can override rather
+     * than settable state.
+     */
+    protected get policy(): AdwViewSwitcherPolicy;
+    /**
+     * What the buttons show. `'both'` for the classic switcher, whose buttons
+     * "always have an icon and a label" (adw-view-switcher.c class docs);
+     * `AdwInlineViewSwitcher` overrides it with the real
+     * `AdwInlineViewSwitcherDisplayMode`.
+     */
+    protected get buttonDisplayMode(): AdwInlineViewSwitcherDisplayMode;
     constructor(rootClass: string);
     /** Initialise the bar class after the subclass fields are ready. */
     protected _initClasses(): void;
-    /** Register the view pages. Rebuilds the switcher bar + content stack. */
-    setViews(pages: AdwViewPage[]): void;
-    /** Show only the selected page; mark its button active. */
-    protected _applySelection(): void;
     /**
-     * Hook: append extra chrome to a freshly-built button (after icon + label).
-     * Default no-op. Subclasses (e.g. {@link AdwTabView}) override to add a close
-     * button. The button is the tappable `StackLayout` container.
+     * Register the view pages. Rebuilds the switcher bar + content stack.
+     *
+     * The SELECTED PAGE survives the rebuild whenever a page of the same name
+     * does — libadwaita's selection is a page pointer, not an index
+     * (adw-view-stack.c:660-672) — and falls back to the first VISIBLE page
+     * otherwise (:1149-1151).
      */
-    protected _buildButtonExtras(_button: StackLayout, _page: AdwViewPage, _index: number): void;
+    setViews(pages: AdwViewPage[]): void;
+    /** Build one button's NS nodes. Painted by {@link _applySelection}. */
+    private _buildButton;
     /**
-     * Hook: react to a button's active/inactive state on every selection change.
-     * Default no-op. Subclasses override to e.g. show the close button only on the
-     * active tab.
+     * Which visibility rule this switcher follows — see
+     * {@link switcherButtonVisible}, which holds the rule itself so a spec can
+     * reach it.
      */
-    protected _applyButtonState(_button: StackLayout, _index: number, _active: boolean): void;
+    protected get switcherKind(): ViewSwitcherKind;
+    /** Paint the derived models: show only the selected page, mark its button active. */
+    protected _applySelection(): void;
     /** The registered view pages. */
     get views(): AdwViewPage[];
     set views(pages: AdwViewPage[]);
-    /** The selected view index. Swaps the visible page + emits `notify::selected`. */
+    /**
+     * The selected view index, `-1` when nothing is selected. Swaps the visible
+     * page + emits `notify::selected`.
+     *
+     * Out-of-range, negative, fractional and hidden-page indices are all silent
+     * NO-OPS — refused, never clamped, exactly as
+     * `adw_view_stack_pages_select_item` refuses (adw-view-stack.c:682-684).
+     */
     get selected(): number;
     set selected(value: number);
+    /** Name of the selected page, `''` when nothing is selected. */
+    get selectedName(): string;
+    /**
+     * Show or hide a page by name. Returns whether the SELECTION moved: hiding
+     * the selected page falls back to the first still-visible one
+     * (`update_child_visible`, adw-view-stack.c:1061-1082).
+     */
+    setPageVisible(name: string, visible: boolean): boolean;
 }

package/lib/types/widgets/view-switcher-model.d.ts

@@ -0,0 +1,114 @@
+import type { View } from '@nativescript/core';
+import { ViewSwitcherBarState, ViewSwitcherState } from '@gjsify/adwaita-core';
+import type { AdwViewSwitcherPageInit, ViewSwitcherStateChange } from '@gjsify/adwaita-core';
+/**
+ * One page registered with a view switcher.
+ *
+ * Mirrors `AdwViewStackPage`'s properties with their C defaults. `title` and
+ * `icon` are NULLABLE on purpose: a page with neither renders no button at all
+ * (adw-view-switcher.c:178), and once an absent title has been flattened to `''`
+ * that rule is no longer expressible — which is why the old shape, with a
+ * required `title: string`, could not implement it.
+ *
+ * `icon` is an Adwaita symbolic SVG DOCUMENT here, not a GTK icon name: `AdwIcon`
+ * rasterises the path data natively. The core treats the field as an opaque
+ * handle and only ever interprets "absent or empty"; {@link nsIconSvg} resolves
+ * the fallback sentinel it hands back.
+ */
+export interface AdwViewPage {
+    /**
+     * The switcher button label. ABSENT means the page has none — which is C's
+     * NULL, and the state the button-visibility rule turns on. Spelled as an
+     * optional `string` rather than `string | null` so the existing consumers
+     * that pass a plain `string` keep type-checking unchanged.
+     */
+    title?: string;
+    /** The page content view, shown when this page is selected. */
+    content: View;
+    /** Adwaita symbolic SVG shown on the switcher button; absent means none. */
+    icon?: string;
+    /** Stable id used by `visible-child-name`; defaults to the page's position. */
+    name?: string;
+    /** `AdwViewStackPage:visible` — default `true`. */
+    visible?: boolean;
+    /** `AdwViewStackPage:use-underline` — an `_` in the title marks a mnemonic. */
+    useUnderline?: boolean;
+    /** `AdwViewStackPage:badge-number` — default `0`. */
+    badgeNumber?: number;
+    /** `AdwViewStackPage:needs-attention` — default `false`. */
+    needsAttention?: boolean;
+}
+/** The two `View.visibility` values a stacked page ever takes. */
+export type NsPageVisibility = 'visible' | 'collapse';
+/** The selection + page model a switcher delegates to. */
+export declare function createViewSwitcherState(): ViewSwitcherState;
+/** The reveal state machine an `AdwViewSwitcherBar` delegates to. */
+export declare function createViewSwitcherBarState(): ViewSwitcherBarState;
+/**
+ * Project one NS page onto the core's page init.
+ *
+ * A page without an explicit `name` gets its POSITION as the name — the NS API
+ * has always been positional (`setViews` takes an array), and a stable id is
+ * what the name-preserving rebuild needs to keep the selected page selected.
+ */
+export declare function viewSwitcherPageSpec(page: AdwViewPage, index: number): AdwViewSwitcherPageInit;
+/** {@link viewSwitcherPageSpec} over a whole page list. */
+export declare function viewSwitcherPageSpecs(pages: readonly AdwViewPage[]): AdwViewSwitcherPageInit[];
+/**
+ * Resolve the core's icon slot to something `AdwIcon` can rasterise.
+ *
+ * The core substitutes the NAME `image-missing` for an absent icon
+ * (adw-view-switcher-button.c:405). On the browser side that name becomes a CSS
+ * mask class; here it has to become the actual symbolic document, so the
+ * sentinel is swapped for the vendored `image-missing-symbolic` SVG. Anything
+ * else is already an SVG and passes through.
+ */
+export declare function nsIconSvg(iconName: string): string;
+/**
+ * The `visibility` each page's content view must carry for the current
+ * selection, in page order. Exactly one entry is `'visible'` — none when nothing
+ * is selected, which is a real state here (an empty switcher, or every page
+ * hidden).
+ */
+export declare function pageVisibilities(pages: readonly AdwViewPage[], selected: number): NsPageVisibility[];
+/** Push {@link pageVisibilities} onto the real content views. */
+export declare function applyViewSwitcherVisibility(pages: readonly AdwViewPage[], selected: number): void;
+/** Which switcher is asking — the two apply different visibility rules. */
+export type ViewSwitcherKind = 'switcher' | 'inline';
+/**
+ * Whether a page gets a button/toggle at all.
+ *
+ * The two switchers genuinely differ, and the difference is easy to miss because
+ * only one of them is documented where you would look:
+ *
+ * - `AdwViewSwitcher` needs a title or an icon ON TOP OF `visible` —
+ *   `gtk_widget_set_visible (button, visible && (title != NULL || icon_name !=
+ *   NULL))` (adw-view-switcher.c:178).
+ * - `AdwInlineViewSwitcher` does not. `populate_group` gates on `visible` alone
+ *   (adw-inline-view-switcher.c:370-378), so a page with neither still gets an
+ *   empty toggle.
+ *
+ * The inline widget inherited the stricter rule and silently dropped toggles
+ * libadwaita draws. `@gjsify/adwaita-core` had spelled this out in
+ * `buildInlineToggles`' doc and pinned it in `INLINE_TOGGLE_VECTORS` the whole
+ * time — the rule just lived in a class that `extends GridLayout`, which no
+ * spec can import, so nothing could reach it to check. That is why it is here
+ * and not there.
+ */
+export declare function switcherButtonVisible(kind: ViewSwitcherKind, modelVisible: boolean, pageVisible: boolean): boolean;
+/** The data half of the `notify::selected` event (minus NS's `eventName`/`object`). */
+export interface ViewSwitcherNotifyPayload {
+    /** The newly-selected page index, `-1` when nothing is selected. */
+    selected: number;
+    /** Its name, `''` when nothing is selected. */
+    name: string;
+    /** Its painted label, `''` when nothing is selected. */
+    title: string;
+    /** `false` for an auto-pick (a rebuild, a visibility flip), `true` for a tap. */
+    interactive: boolean;
+}
+/**
+ * Project a core change onto the event payload. A function rather than a spread
+ * so no live model object escapes into an event a consumer might hold on to.
+ */
+export declare function viewSwitcherNotifyPayload(change: ViewSwitcherStateChange): ViewSwitcherNotifyPayload;

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

@@ -0,0 +1,43 @@
+/**
+ * `Adw.WrapBox:child-spacing` / `:line-spacing` default, in DIPs.
+ *
+ * Both are `g_param_spec_int (…, 0, G_MAXINT, 0, …)` — adw-wrap-box.c:285-287
+ * and :393-395. The port used to default both to 6, so identical markup was
+ * looser on a phone than in the browser and an EMPTY wrap box was already 12
+ * DIPs tall.
+ */
+export declare const DEFAULT_WRAP_BOX_SPACING = 0;
+/**
+ * Normalise one spacing property, the way `adw_wrap_box_set_child_spacing` does.
+ *
+ * C clamps a negative value to 0 before anything else happens
+ * (adw-wrap-box.c:587-588, :927-928); the property's declared minimum is 0, so
+ * without the clamp GObject would reject it outright. The non-numeric cases have
+ * no C counterpart — the property is an `int` — and resolve to the default, so a
+ * `NaN` can never reach a native layout pass.
+ */
+export declare function normalizeWrapBoxSpacing(value: unknown): number;
+/**
+ * Whether writing `next` over `current` is a change the widget must act on.
+ *
+ * The comparison happens AFTER the clamp (adw-wrap-box.c:592-593, :930-931), so
+ * a negative value written over a spacing of 0 is an early return: it neither
+ * reaches the layout nor notifies. On this port the same predicate decides
+ * whether every child's margin is rewritten.
+ */
+export declare function wrapBoxSpacingChanges(current: number, next: unknown): boolean;
+/**
+ * The uniform margin that gives an NS `WrapLayout` child its share of the gaps.
+ *
+ * `WrapLayout` has no gap property, so the inter-item spacing has to come out of
+ * the children: half of it on each facing edge adds up to the whole gap between
+ * any two neighbours. The margin string is NS's `top right bottom left`
+ * shorthand.
+ *
+ * This is the one place the port is knowingly looser than libadwaita: the halves
+ * on the OUTER edges are an inset `Adw.WrapBox` does not have. It is invisible
+ * at the default spacing of 0 and bounded by half a gap otherwise, where the
+ * alternative — negative margins on the container — is not something the NS CSS
+ * subset can be trusted with.
+ */
+export declare function wrapBoxChildMargin(childSpacing: number, lineSpacing: number): string;

package/lib/types/wrap-box.spec.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-nativescript",
-    "version": "0.31.0",
+    "version": "0.32.0",
     "description": "Native Adwaita widgets for the NativeScript runtime — real NativeScript components (StackLayout/GridLayout/Switch/Label) styled like Libadwaita, not a webview",
     "type": "module",
     "module": "lib/esm/index.js",
@@ -47,10 +47,10 @@
         "design-system"
     ],
     "dependencies": {
-        "@gjsify/adwaita-core": "^0.31.0",
-        "@gjsify/adwaita-fonts": "^0.31.0",
-        "@gjsify/adwaita-icons": "^0.31.0",
-        "@gjsify/native-platform": "^0.31.0"
+        "@gjsify/adwaita-core": "^0.32.0",
+        "@gjsify/adwaita-fonts": "^0.32.0",
+        "@gjsify/adwaita-icons": "^0.32.0",
+        "@gjsify/native-platform": "^0.32.0"
     },
     "peerDependencies": {
         "@nativescript/core": "*"
@@ -61,8 +61,8 @@
         }
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.31.0",
-        "@gjsify/unit": "^0.31.0",
+        "@gjsify/cli": "^0.32.0",
+        "@gjsify/unit": "^0.32.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },