@gjsify/adwaita-nativescript 0.36.0 → 0.37.0

package/lib/types/widgets/navigation-stack.d.ts

@@ -61,11 +61,8 @@ export declare class NsNavigationStack {
     private readonly _onDiagnostic;
     private _pending;
     constructor(host: NsNavigationHost, options?: NsNavigationStackOptions);
-    /** The currently-visible page view, or `null`. */
     get visiblePage(): View | null;
-    /** The currently-visible page tag, or `null`. */
     get visiblePageTag(): string | null;
-    /** The current navigation stack depth. */
     get depth(): number;
     /** The navigation stack, bottom-first. */
     get stack(): readonly View[];
@@ -79,7 +76,6 @@ export declare class NsNavigationStack {
     get animateTransitions(): boolean;
     /** `Adw.NavigationView:pop-on-escape` — consulted by {@link popFromEscape}. */
     get popOnEscape(): boolean;
-    /** Whether `view` is known to this navigation view. */
     isRegistered(view: View): boolean;
     /** `view`'s tag, or `null`. */
     tagOf(view: View): string | null;
@@ -87,7 +83,6 @@ export declare class NsNavigationStack {
     titleOf(view: View): string;
     /** Whether `view` may be popped by a shortcut or a back button. */
     canPopOf(view: View): boolean;
-    /** The page with this tag, or `null`. */
     findPage(tag: string): View | null;
     /** The page popping `view` would reveal, or `null`. */
     getPreviousPage(view: View): View | null;
@@ -104,21 +99,17 @@ export declare class NsNavigationStack {
     remove(view: View): boolean;
     /** Push a page (a previously-registered tag, or a fresh view) onto the stack. */
     push(viewOrTag: View | string, options?: AdwNavigationPageProps): boolean;
-    /** Push the page carrying `tag`. */
     pushByTag(tag: string): boolean;
     /** Pop the top page. `can-pop` does NOT gate this — it gates the shortcuts. */
     pop(): boolean;
     /** Pop until `view` is visible, in ONE transition. */
     popToPage(view: View): boolean;
-    /** Pop until the page carrying `tag` is visible. */
     popToTag(tag: string): boolean;
     /**
-     * Replace the whole stack. String entries are resolved BEFORE anything is
-     * mutated, so replacing the stack with the tag of a dynamically-pushed page
-     * keeps that page (replace_with_tags:3136-3147).
+     * Replace the whole stack. String entries are resolved BEFORE anything is mutated,
+     * so replacing the stack with the tag of a dynamically-pushed page keeps that page.
      */
     replace(entries: ReadonlyArray<View | string | null>, props?: (view: View) => AdwNavigationPageProps | undefined): void;
-    /** Replace the stack with the pages carrying `tags`. */
     replaceWithTags(tags: readonly string[]): void;
     /** Set a page's tag. Rejected when another page already owns it. */
     setTag(view: View, tag: string | null): boolean;
@@ -126,9 +117,7 @@ export declare class NsNavigationStack {
     setTitle(view: View, title: string): boolean;
     /** Set a page's `can-pop`: gates the shortcuts and a back button, not `pop()`. */
     setCanPop(view: View, canPop: boolean): boolean;
-    /** Set `animate-transitions`. */
     setAnimateTransitions(value: boolean): boolean;
-    /** Set `pop-on-escape`. */
     setPopOnEscape(value: boolean): boolean;
     /** The `can-pop`-aware pop behind a hardware back button or Alt+Left. */
     popFromShortcut(): NavigationShortcutResult;

package/lib/types/widgets/preferences-group-state.d.ts

@@ -11,9 +11,7 @@ export declare const PREFERENCES_GROUP_HEADER_CLASS = "adw-preferences-group-hea
 export declare const PREFERENCES_GROUP_SINGLE_LINE_CLASS = "single-line";
 /** What a group knows about itself when it re-derives its visuals. */
 export interface NsPreferencesGroupInput {
-    /** `AdwPreferencesGroup:title`. */
     title?: string | null;
-    /** `AdwPreferencesGroup:description`. */
     description?: string | null;
     /** Whether a `header-suffix` view is set. */
     hasHeaderSuffix?: boolean;
@@ -22,9 +20,7 @@ export interface NsPreferencesGroupInput {
 }
 /** The NativeScript form of {@link PreferencesGroupHeaderState}. */
 export interface NsPreferencesGroupVisuals {
-    /** `visibility` for the title label. */
     titleVisibility: NsVisibility;
-    /** `visibility` for the description label. */
     descriptionVisibility: NsVisibility;
     /** `visibility` for the whole header box. */
     headerVisibility: NsVisibility;
@@ -36,17 +32,15 @@ export interface NsPreferencesGroupVisuals {
 /**
  * The five derived states for a group.
  *
- * `useMarkup: false` is deliberate and is the same choice the browser renderer
- * makes: an NS `Label` shows the string verbatim (it has no Pango markup), so
- * visibility must be judged on the string that is actually painted. Rendering
- * markup is a separate, still-open gap; closing it flips this one flag.
+ * `useMarkup: false` is deliberate and matches the browser renderer: an NS `Label`
+ * shows the string verbatim (no Pango markup), so visibility must be judged on the
+ * string that is actually painted. Rendering markup is a still-open gap; closing it
+ * flips this one flag.
  */
 export declare function preferencesGroupHeaderState(input: NsPreferencesGroupInput): PreferencesGroupHeaderState;
 /**
- * `visibility` / `className` a group must apply for the given inputs.
- *
- * `'collapse'` rather than `'hidden'`: a hidden NS view still occupies its
- * space, which would leave the header's padding behind on a group that has no
- * header — the very thing `update_header_visibility` exists to avoid.
+ * `visibility` / `className` a group must apply for the given inputs. `'collapse'`
+ * rather than `'hidden'`: a hidden NS view still occupies its space, which would leave
+ * the header's padding behind on a group that has no header.
  */
 export declare function preferencesGroupVisuals(input: NsPreferencesGroupInput): NsPreferencesGroupVisuals;

package/lib/types/widgets/preferences-search.d.ts

@@ -2,11 +2,11 @@ import type { PreferencesSearchPage, PreferencesSearchResult, SearchPreferencesO
 /**
  * What the search reads off a row widget.
  *
- * `isActionRow` is a declared property rather than an `instanceof` test,
- * because the NativeScript hierarchy does NOT match the GObject one:
- * `AdwEntryRow extends AdwActionRow` here so it can reuse the row chrome, while
- * in C it derives from `AdwPreferencesRow` (adw-entry-row.c:90) and its text is
- * therefore deliberately NOT searchable. The row classes carry the C answer.
+ * `isActionRow` is a declared property rather than an `instanceof` test, because the
+ * NativeScript hierarchy does NOT match the GObject one: `AdwEntryRow extends
+ * AdwActionRow` here to reuse the row chrome, while in C it derives from
+ * `AdwPreferencesRow` and its text is therefore deliberately NOT searchable. The row
+ * classes carry the C answer.
  */
 export interface NsSearchableRow {
     /** `AdwPreferencesRow:title`. */

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

@@ -6,22 +6,16 @@ export type { AdwRowLabels, ButtonRowRenderState };
 /** The two `View.visibility` values an Adwaita row ever assigns. */
 export type NsVisibility = 'visible' | 'collapse';
 /**
- * `visibility` for a shown/hidden view.
- *
- * `'collapse'` rather than `'hidden'`: a hidden NS view still occupies its
- * space, so an empty subtitle would leave its whole line behind — which is the
- * one thing the binding exists to prevent.
+ * `visibility` for a shown/hidden view. `'collapse'` rather than `'hidden'`: a hidden
+ * NS view still occupies its space, so an empty subtitle would leave its whole line
+ * behind — the one thing the binding exists to prevent.
  */
 export declare function nsVisibility(shown: boolean): NsVisibility;
 /** The NativeScript form of a title/subtitle label pair. */
 export interface NsRowLabelVisuals {
-    /** Text for the title `Label`. */
     title: string;
-    /** `visibility` for the title `Label`. */
     titleVisibility: NsVisibility;
-    /** Text for the subtitle `Label`. */
     subtitle: string;
-    /** `visibility` for the subtitle `Label`. */
     subtitleVisibility: NsVisibility;
 }
 /** What a row must apply to its two labels for the given title/subtitle. */
@@ -30,42 +24,32 @@ export declare function rowLabelVisuals(input: AdwRowLabelInput): NsRowLabelVisu
 export declare function toLabelVisuals(labels: AdwRowLabels): NsRowLabelVisuals;
 /** The NativeScript form of an `Adw.ButtonRow`'s two icons. */
 export interface NsButtonRowIconVisuals {
-    /** Payload for the leading icon. */
     startIcon: string;
-    /** `visibility` for the leading icon. */
     startIconVisibility: NsVisibility;
-    /** Payload for the trailing icon. */
     endIcon: string;
-    /** `visibility` for the trailing icon. */
     endIconVisibility: NsVisibility;
 }
 /**
  * What a button row must apply to its two icons.
  *
- * The TITLE half of `ButtonRowRenderState` is deliberately not mapped here: the
- * NativeScript button row reuses the action row's title `Label` and therefore
- * its title state, so routing the title through a second state object would give
- * one label two sources of truth — the exact shape this package exists to
- * remove. {@link rowLabelVisuals} paints it.
+ * The TITLE half of `ButtonRowRenderState` is deliberately not mapped here: the NS
+ * button row reuses the action row's title `Label` and its title state, so routing the
+ * title through a second state object would give one label two sources of truth.
+ * {@link rowLabelVisuals} paints it.
  *
- * NOTE ON THE ICON PAYLOAD: GTK stores an icon NAME and resolves it through the
- * icon theme; this port stores the symbolic SVG source itself, because `AdwIcon`
- * renders SVG rather than looking a name up. `ButtonRowState` is indifferent —
- * the rule it applies is `string_is_not_empty`, which reads the first byte and
- * does not care what the string means.
+ * The icon payload is the symbolic SVG SOURCE, not GTK's icon name, because `AdwIcon`
+ * renders SVG rather than resolving a name. `ButtonRowState` is indifferent: its rule
+ * is `string_is_not_empty`, which reads the first byte.
  */
 export declare function buttonRowIconVisuals(state: ButtonRowRenderState): NsButtonRowIconVisuals;
 /**
- * Whether a view is "sensitive" in the sense the `activatable-widget` binding
- * reads (`GtkWidget:sensitive` → `GtkListBoxRow:activatable`,
- * adw-action-row.c:729-732).
+ * Whether a view is "sensitive" in the sense the `activatable-widget` binding reads
+ * (`GtkWidget:sensitive` → `GtkListBoxRow:activatable`).
  *
- * NativeScript has no `sensitive`; `isUserInteractionEnabled` is the nearest
- * flag it surfaces (its own docs map it to `gtk_widget_set_can_target`). The two
- * are not identical in GTK — an insensitive widget is also greyed out, a
- * can't-target one is not — but `isUserInteractionEnabled` is the only property
- * a NativeScript view has for "the user cannot operate this", so it is what the
- * binding reads here. A view that has never been touched reports `true`, which
- * is also GTK's default.
+ * NativeScript has no `sensitive`; `isUserInteractionEnabled` is the nearest flag it
+ * surfaces (its own docs map it to `gtk_widget_set_can_target`). The two differ in GTK
+ * — an insensitive widget is also greyed out, a can't-target one is not — but it is the
+ * only property NS has for "the user cannot operate this". An untouched view reports
+ * `true`, which is also GTK's default.
  */
 export declare function isViewSensitive(view: Pick<View, 'isUserInteractionEnabled'> | null | undefined): boolean;

package/lib/types/widgets/sidebar-model.d.ts

@@ -4,15 +4,13 @@ export { SidebarState };
 export type { AdwSidebarItemSpec, AdwSidebarSectionSpec, SidebarItemFilter };
 /**
  * The section list a flat `AdwSidebar.setItems(labels)` call means: one untitled
- * section, which renders no header at all (a first + untitled section's header is
- * bound to a non-empty title, adw-sidebar.c:1521-1527).
+ * section, which renders no header at all (a section header's `visible` is bound to a
+ * non-empty title).
  */
 export declare function sidebarSectionsFromLabels(labels: readonly string[]): AdwSidebarSectionSpec[];
 /**
- * The class string one navigation row carries.
- *
- * `selectionVisible` is false in page mode, where libadwaita tracks the
- * selection but never paints it (adw-sidebar.c:2948-2951) — its rows are plain
- * boxed-list `AdwActionRow`s with no selected state.
+ * The class string one navigation row carries. `selectionVisible` is false in page
+ * mode, where libadwaita tracks the selection but never paints it — those rows are
+ * plain boxed-list `AdwActionRow`s with no selected state.
  */
 export declare function sidebarRowClassName(selected: boolean, selectionVisible: boolean): string;

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

@@ -3,53 +3,36 @@ export type { AdwMenuEntry, SplitButtonDirection };
 /** Text of the sheet's dismiss button. */
 export declare const MENU_CANCEL_LABEL = "Cancel";
 /**
- * The libadwaita arrow glyph names mapped to real Adwaita symbolic SVGs.
- *
- * Keyed by {@link AdwArrowIcon} and therefore TOTAL: which glyph a direction gets
- * is decided in core, and a glyph this table has no SVG for is a compile error
- * rather than a fallback arrow.
+ * The libadwaita arrow glyph names mapped to real Adwaita symbolic SVGs. Keyed by
+ * {@link AdwArrowIcon} and therefore TOTAL: which glyph a direction gets is decided in
+ * core, and a glyph with no SVG here is a compile error rather than a fallback arrow.
  */
 export declare const ARROW_SVGS: Readonly<Record<AdwArrowIcon, string>>;
 /**
- * Normalise a menu assigned from XML or app code into entries.
- *
- * A bare `string[]` is accepted because that is what `AdwSplitButton.menu` used
- * to be and what the storybook still passes; it widens to the shared
- * {@link AdwMenuEntry} without breaking a caller.
+ * Normalise a menu assigned from XML or app code into entries. A bare `string[]` is
+ * accepted (the storybook passes one) and widens to the shared {@link AdwMenuEntry}.
  */
 export declare function toMenuEntries(value: readonly (string | AdwMenuEntry)[] | null | undefined): AdwMenuEntry[];
 /**
- * The strings handed to `Dialogs.action()`, one per entry and each unique.
- *
- * A label that collides with another entry — or with the dismiss button — gets
- * zero-width spaces appended until it is distinct. Nothing changes on screen;
- * what changes is that {@link resolveMenuChoice} can now tell the entries apart.
+ * The strings handed to `Dialogs.action()`, one per entry and each unique: a label
+ * that collides with another entry — or with the dismiss button — gets zero-width
+ * spaces appended until it is distinct, so {@link resolveMenuChoice} can tell them
+ * apart.
  */
 export declare function menuSheetActions(entries: readonly AdwMenuEntry[], cancelLabel?: string): string[];
 /**
- * The position the user chose, or `-1` when the sheet was dismissed.
- *
- * Feed it the SAME array {@link menuSheetActions} produced: the strings are
- * unique there, so the lookup is a position and not a guess.
+ * The position the user chose, or `-1` when the sheet was dismissed. Feed it the SAME
+ * array {@link menuSheetActions} produced, or the lookup is a guess.
  */
 export declare function resolveMenuChoice(sheetActions: readonly string[], chosen: string | null | undefined): number;
-/**
- * The arrow SVG for a direction, keyed off the SPLIT BUTTON's glyph map — so
- * `none` is the down caret (_buttons.scss:621-623), not the hamburger this widget
- * used to render for it.
- */
+/** The arrow SVG for a direction; the split button's `none` is the down caret, not a hamburger. */
 export declare function splitButtonArrowSvg(direction: SplitButtonDirection): string;
 /**
- * Apply `AdwSplitButton.actionIcon = svg` to the content machine.
- *
- * The SVG string IS the icon identity on NativeScript (no icon theme is
- * resolved), so it goes in where GTK puts the icon NAME. Clearing it is the
- * mapping worth having in one place: C offers no "unset the icon", only the
- * side effect of filling another slot (adw-split-button.c:749-771), so an empty
- * SVG clears the content and lets the label half take over again — which is what
- * every caller assigning `actionIcon` from a nullable lookup expects.
+ * Apply `AdwSplitButton.actionIcon = svg` to the content machine. The SVG string IS
+ * the icon identity on NativeScript, so it goes where GTK puts the icon NAME.
  *
- * Lives here rather than in the widget so it is unit-testable off-device: the
- * widget module `extends GridLayout` and cannot be imported on GJS/Node.
+ * C offers no "unset the icon", only the side effect of filling another slot, so an
+ * empty SVG clears the content and lets the label half take over again — what a
+ * caller assigning `actionIcon` from a nullable lookup expects.
  */
 export declare function setActionIcon(state: SplitButtonState, svg: string | null | undefined): void;

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

@@ -6,7 +6,6 @@ import type { AdwTextDirection } from '@gjsify/adwaita-core';
 export declare const NOTIFY_SHOW_SIDEBAR = "notify::show-sidebar";
 /** Payload of the `notify::show-sidebar` event. */
 export interface NotifyShowSidebarEventData extends EventData {
-    /** Whether the sidebar is currently shown. */
     showSidebar: boolean;
     /** Whether the view is in its collapsed (narrow) mode. */
     collapsed: boolean;
@@ -30,22 +29,20 @@ export declare abstract class AdwSplitViewBase<TState extends NsSplitViewState =
     /** The headless state machine this widget renders (`split-view-state.ts`). */
     _state: TState);
     /**
-     * (Re)declare the two columns so the sidebar's column is fixed-width ('auto')
-     * and the content's is expanding ('star'), ordered by {@link sidebarPosition}:
-     * `start` → [sidebar auto, content star]; `end` → [content star, sidebar auto].
-     * Without this an `end` sidebar would land in the expanding column and float
-     * away from the right edge (leaving a gap), with the content squeezed.
+     * (Re)declare the two columns so the sidebar's is fixed-width (`'auto'`, sized to
+     * the pane) and the content's expands (`'star'`), ordered by the side the sidebar
+     * is DRAWN on. Without this an `end` sidebar lands in the expanding column and
+     * floats away from the edge, with the content squeezed.
      *
      * `splitViewColumns()` is the other half of the same rule — which column each
-     * PANE is written into. The two must agree, or an `end` sidebar ends up in the
-     * expanding column with the content squeezed into the fixed one.
+     * PANE is written into — and both must agree.
      */
     protected _syncColumns(): void;
     /**
      * Publish which visual side the pane is on, so the theme can put the divider
-     * there — the CSS counterpart to `_sidebars.scss`'s `:dir()` x `.end`
-     * product. A fixed `border-right` drew it on the wrong edge for an `end`
-     * sidebar and for every RTL layout.
+     * there — the CSS counterpart to `_sidebars.scss`'s `:dir()` × `.end` product. A
+     * fixed `border-right` draws it on the wrong edge for an `end` sidebar and for
+     * every RTL layout.
      */
     protected _syncSidebarSide(view?: View | null): void;
     /**
@@ -61,17 +58,15 @@ export declare abstract class AdwSplitViewBase<TState extends NsSplitViewState =
     protected _emitShowSidebar(event: NsShowSidebarNotification): void;
     /** Subclass-specific layout application for the current collapsed/show state. */
     protected abstract _applyLayout(): void;
-    /** Apply a user-initiated show/hide toggle. The default is an instant re-layout;
-     *  the subclasses override this to slide the panes (and, for the overlay, fade a
-     *  scrim) when collapsed. Kept separate from {@link _applyLayout} so structural
-     *  re-layouts (setSidebar/collapsed/position changes) stay instant — only an
-     *  on-screen `showSidebar` toggle animates. */
+    /** Apply a user-initiated show/hide toggle. Separate from {@link _applyLayout} so
+     *  structural re-layouts stay instant — only an on-screen `showSidebar` toggle
+     *  animates; the subclasses override this to slide the panes. */
     protected _transitionSidebar(): void;
     /** In-flight animations, cancelled when a new transition supersedes them. */
     protected _pending: Cancelable[];
     /** Whether to run a real animation now: native `animate()` present AND on-screen.
-     *  Off-device (the mock view tree in specs) or pre-load it returns false, so the
-     *  caller falls back to an instant `visibility` swap. */
+     *  False off-device or pre-load, so the caller falls back to an instant
+     *  `visibility` swap. */
     protected _shouldAnimate(): boolean;
     /** Register an animation so a later transition can cancel it; returns a plain promise. */
     protected _track(anim: Promise<void> & Cancelable): Promise<void>;
@@ -100,9 +95,9 @@ export declare abstract class AdwSplitViewBase<TState extends NsSplitViewState =
     get showSidebar(): boolean;
     set showSidebar(value: boolean);
     /**
-     * The sidebar pane width in DIPs, DERIVED from the container size unless a
-     * caller assigned one. `Adw.OverlaySplitView` has no stored width — see
-     * `split-view-width.ts` for why the old fixed 240 could not be right.
+     * The sidebar pane width in DIPs, DERIVED from the container size unless a caller
+     * assigned one — `Adw.OverlaySplitView` stores no width; see
+     * `split-view-width.ts` for the rule.
      */
     get sidebarWidth(): number;
     set sidebarWidth(value: number);
@@ -123,9 +118,7 @@ export declare abstract class AdwSplitViewBase<TState extends NsSplitViewState =
      * the closest thing to the window size Adwaita evaluates against.
      */
     protected _applySidebarWidth(): void;
-    /** Which side the sidebar sits on — `'start'` (leading / left) or `'end'`
-     *  (trailing / right). Mirrors `Adw.OverlaySplitView`'s `sidebar-position`
-     *  (the storybook controls overlay uses `'end'`). */
+    /** `Adw.OverlaySplitView:sidebar-position` — `'start'` (leading) or `'end'`. */
     get sidebarPosition(): AdwPackType;
     set sidebarPosition(value: AdwPackType);
     /** The sidebar pane, or `null`. */