@gjsify/adwaita-nativescript 0.31.0 → 0.33.0

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,97 @@
+import { normalizeWrapBoxSpacing, type AdwWrapBoxJustify, type AdwWrapBoxOrientation, type AdwWrapBoxPackDirection, type AdwWrapPolicy } from '@gjsify/adwaita-core';
+export { normalizeWrapBoxSpacing };
+/**
+ * `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;
+/**
+ * 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 a `FlexboxLayout` child its share of the gaps.
+ *
+ * NativeScript has no gap property on any layout — `Style` carries no
+ * `columnGap`/`rowGap` — 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;
+/** The `FlexboxLayout` knobs a wrap box's properties resolve to. */
+export interface WrapBoxFlexStyle {
+    /** `FlexboxLayout:flexDirection` — the main axis, reversed for `end-to-start`. */
+    flexDirection: 'row' | 'row-reverse' | 'column' | 'column-reverse';
+    /** `FlexboxLayout:flexWrap` — always wrapping; reversed by `wrap-reverse`. */
+    flexWrap: 'wrap' | 'wrap-reverse';
+    /** `FlexboxLayout:justifyContent` — where a COMPLETE line's leftover goes. */
+    justifyContent: 'flex-start' | 'center' | 'flex-end' | 'space-between';
+    /** `FlexboxLayout:alignContent` — `line-homogeneous` stretches the lines. */
+    alignContent: 'stretch' | 'flex-start';
+    /** `FlexboxLayout.setFlexGrow` for a child on a complete line. */
+    childFlexGrow: number;
+    /** `FlexboxLayout.setFlexShrink` for every child — `wrap-policy`. */
+    childFlexShrink: number;
+}
+/** The widget properties the two resolvers read. */
+export interface WrapBoxFlexInput {
+    orientation: AdwWrapBoxOrientation;
+    packDirection: AdwWrapBoxPackDirection;
+    wrapReverse: boolean;
+    justify: AdwWrapBoxJustify;
+    justifyLastLine: boolean;
+    align: number;
+    lineHomogeneous: boolean;
+    wrapPolicy: AdwWrapPolicy;
+}
+/**
+ * The CONTAINER half of the decision, resolved onto `FlexboxLayout`.
+ *
+ * The line DECISION is `resolveWrapBoxLine` in `@gjsify/adwaita-core`, held to
+ * `WRAP_BOX_LINE_VECTORS` — this function only maps its answer onto the knobs NS
+ * has, exactly as the browser element maps it onto CSS.
+ *
+ * Like a flex container, `FlexboxLayout` has ONE `justifyContent` for every
+ * line, so it can only carry the COMPLETE-line rule. NativeScript offers no
+ * `:only-child` selector and no generated content, so the final-line rule has no
+ * container-level expression at all; what it CAN reach is the single-child case,
+ * through {@link wrapBoxChildFlex}.
+ */
+export declare function wrapBoxFlexStyle(input: WrapBoxFlexInput): WrapBoxFlexStyle;
+/** What one child of the box gets set on it. */
+export interface WrapBoxChildFlex {
+    /** `FlexboxLayout.setFlexGrow` — whether this child absorbs the line's leftover. */
+    flexGrow: number;
+    /** `FlexboxLayout.setFlexShrink` — `wrap-policy`, the same for every child. */
+    flexShrink: number;
+}
+/**
+ * The PER-CHILD half of the decision, which the container knobs cannot carry.
+ *
+ * Two of libadwaita's rules are facts about a child rather than about the box,
+ * and a single `justifyContent` has nowhere to put either. A box with exactly
+ * ONE child has one line, that line is the LAST one, and its child is alone on
+ * it — so it is governed by `justify-last-line`, and `spread` STRETCHES it
+ * rather than spreading anything (`n_children > 1` guards the keep-at-minimum
+ * branch, adw-wrap-layout.c:338; adw-wrap-box.c:349-352 says so outright).
+ *
+ * `childCount` is the box's own child count, which is the most a renderer knows
+ * without a layout pass: 1 means the lone-child-on-the-final-line case exactly,
+ * anything more means at least one complete line.
+ */
+export declare function wrapBoxChildFlex(input: WrapBoxFlexInput, childCount: number): WrapBoxChildFlex;

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.33.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.33.0",
+        "@gjsify/adwaita-fonts": "^0.33.0",
+        "@gjsify/adwaita-icons": "^0.33.0",
+        "@gjsify/native-platform": "^0.33.0"
     },
     "peerDependencies": {
         "@nativescript/core": "*"
@@ -61,8 +61,8 @@
         }
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.31.0",
-        "@gjsify/unit": "^0.31.0",
+        "@gjsify/cli": "^0.33.0",
+        "@gjsify/unit": "^0.33.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },