@gjsify/adwaita-web 0.55.0 → 0.56.0

package/lib/types/adw-status-page.spec.d.ts

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

package/lib/types/attributes.d.ts

@@ -0,0 +1,19 @@
+import { VALUE_BASED_BOOLEAN_ATTRS } from '@gjsify/adwaita-core/tags';
+/** Re-export for consumers that need the list (e.g. `shared-tree-builder.ts`). */
+export { VALUE_BASED_BOOLEAN_ATTRS };
+/**
+ * Whether an attribute spells a boolean property, defaulting to `whenAbsent`.
+ *
+ * Absent is the property's default; present, the literal `"false"` is FALSE and anything
+ * else is TRUE.
+ */
+export declare function booleanAttribute(value: string | null, whenAbsent: boolean): boolean;
+/**
+ * Write a value-based boolean attribute (GTK property defaulting to TRUE).
+ *
+ * `true`  → sets `attr="true"` (present, not "false", reads as true)
+ * `false` → sets `attr="false"` (present, reads as false)
+ * This avoids `toggleAttribute` which removes the attribute for `false`,
+ * causing value-based readers to fall back to the default (true).
+ */
+export declare function writeBooleanAttribute(el: HTMLElement, attr: string, value: boolean): void;

package/lib/types/elements/adw-action-row.d.ts

@@ -3,6 +3,8 @@ export declare class AdwActionRow extends HTMLElement {
     private _subtitleEl;
     private _suffixEl;
     private _prefixEl;
+    /** The label column — kept for `tooltip-text`, which the browser reads off a PART. */
+    private _textEl;
     /** The headless labels + activatable-widget coupling (ADR 0004). */
     private readonly _state;
     /** Watches the activatable widget's `disabled`/`aria-disabled` — the live binding. */
@@ -46,4 +48,6 @@ export declare class AdwActionRow extends HTMLElement {
     /** Reflect the state's `activatable` back onto the attribute + class. */
     private _syncActivatable;
     private _render;
+    /** Apply CSS line-clamping based on title-lines/subtitle-lines attributes. */
+    private _applyLineClamping;
 }

package/lib/types/elements/adw-combo-row.d.ts

@@ -2,6 +2,8 @@ import type { AdwComboOption, AdwListModelInput } from '@gjsify/adwaita-core';
 export declare class AdwComboRow extends HTMLElement {
     private _select;
     private _valueEl;
+    /** The label column — kept for `tooltip-text`, which the browser reads off a PART. */
+    private _textEl;
     private _titleEl;
     private _subtitleEl;
     /** The headless options list + selectedIndex↔selectedValue state machine (ADR 0004). */
@@ -78,4 +80,6 @@ export declare class AdwComboRow extends HTMLElement {
      */
     private _syncChooser;
     private _renderText;
+    /** Apply CSS line-clamping based on title-lines/subtitle-lines attributes. */
+    private _applyLineClamping;
 }

package/lib/types/elements/adw-entry-row.d.ts

@@ -49,6 +49,12 @@ export declare class AdwEntryRow extends HTMLElement {
     get editing(): boolean;
     connectedCallback(): void;
     attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+    /**
+     * The parts `tooltip-text` lands on: the two slots and the editable area — NOT the
+     * apply button or the indicator, which carry tooltips of their own that the consumer
+     * reads for what they are.
+     */
+    private _tooltipParts;
     /**
      * Add a widget after the editable area — `adw_entry_row_add_suffix`, which APPENDS
      * into a box, so several suffixes coexist and the password row's own peek toggle

package/lib/types/elements/adw-expander-row.d.ts

@@ -32,4 +32,6 @@ export declare class AdwExpanderRow extends HTMLElement {
     connectedCallback(): void;
     attributeChangedCallback(name: string): void;
     private _render;
+    /** Apply CSS line-clamping based on title-lines/subtitle-lines attributes. */
+    private _applyLineClamping;
 }

package/lib/types/elements/adw-header-bar.d.ts

@@ -18,6 +18,12 @@ export declare class AdwHeaderBar extends HTMLElement {
      * bare `Adw.HeaderBar {}` in a `.blp` page shows "Mailboxes" with no title of its own.
      */
     private _page;
+    /**
+     * The window the bar sits in: `update_title`'s last stop before the application name
+     * (`gtk_window_get_title` of the root), so a bar with no title of its own, under no titled
+     * page, shows the window's.
+     */
+    private _window;
     private _pageObserver;
     static get observedAttributes(): string[];
     /** The start (left) section container — append buttons/widgets here. */

package/lib/types/elements/adw-overlay-split-view.d.ts

@@ -1,4 +1,7 @@
+import type { DispatchedSignals } from '../signals.js';
 export declare class AdwOverlaySplitView extends HTMLElement {
+    /** The GTK signals this element dispatches, which is what a `.blp` `bind` of `show-sidebar` follows. */
+    static readonly signals: DispatchedSignals;
     private _initialized;
     private _sidebarEl;
     private _contentEl;
@@ -16,6 +19,8 @@ export declare class AdwOverlaySplitView extends HTMLElement {
      * `show-sidebar` + `pin-sidebar` mean together, held to `OVERLAY_COLLAPSE_VECTORS`.
      */
     private _state;
+    /** The `show-sidebar` the last `notify::show-sidebar` (or the first read) settled on. */
+    private _notifiedShowSidebar;
     /** Re-entrancy guard for {@link _reflectShowSidebar}. */
     private _reflecting;
     /** The view's own width in CSS px — the size the sidebar fraction is OF. */
@@ -66,6 +71,14 @@ export declare class AdwOverlaySplitView extends HTMLElement {
      * loop rather than a render.
      */
     private _reflectShowSidebar;
+    /**
+     * `notify::show-sidebar`, raised on the EFFECTIVE value — the state's, after an auto-hide on
+     * collapse — and only when it changed, the way GObject notifies. Every path that moves it
+     * (the attribute, the property, a breakpoint, a gesture) ends in {@link _reflectShowSidebar},
+     * so this is the one place it is raised. The first read only records the baseline: a bind
+     * reads the current value itself.
+     */
+    private _notifyShowSidebar;
     private _syncBreakpoint;
     openSidebar(): void;
     hideSidebar(): void;

package/lib/types/elements/adw-sidebar.d.ts

@@ -3,9 +3,10 @@ import { type AdwSidebarItemSpec, type AdwSidebarSectionSpec, type SidebarItemFi
 export declare class AdwSidebarItem extends HTMLElement {
     static get observedAttributes(): string[];
     /**
-     * `AdwSidebarItem:enabled`, under the GIR name — the `disabled` attribute inverted. The
-     * property is what lets an authored `enabled: false` reach this item through the
+     * `AdwSidebarItem:enabled`, under the GIR name — the `disabled` attribute inverted.
+     * The property is what lets an authored `enabled: false` reach this item through the
      * shared-tree builder, which writes a `false` through the element's own property.
+     * Reads both the presence-based `disabled` and value-based `enabled` attributes.
      */
     get enabled(): boolean;
     set enabled(value: boolean);

package/lib/types/elements/adw-spin-row.d.ts

@@ -1,6 +1,10 @@
 import type { AdwAdjustment, AdwAdjustmentInput } from '@gjsify/adwaita-core';
 export declare class AdwSpinRow extends HTMLElement {
     private _input;
+    /** The label column — kept for `tooltip-text`, which the browser reads off a PART. */
+    private _textEl;
+    /** The −/input/+ box — the other half of the row's surface. */
+    private _controlEl;
     private _titleEl;
     private _subtitleEl;
     /** The headless adjustment: the range, the clamp and the two signals (ADR 0004, ADR 0047). */
@@ -21,6 +25,8 @@ export declare class AdwSpinRow extends HTMLElement {
     connectedCallback(): void;
     attributeChangedCallback(name: string, _old: string | null, val: string | null): void;
     private _renderText;
+    /** Apply CSS line-clamping based on title-lines/subtitle-lines attributes. */
+    private _applyLineClamping;
     /** A stepper press — the interactive path, so it emits `notify::value`. */
     private _adjust;
     private _emitChange;

package/lib/types/elements/adw-switch-row.d.ts

@@ -2,6 +2,8 @@ import './gtk-switch.js';
 export declare class AdwSwitchRow extends HTMLElement {
     private _switchEl;
     private _prefixEl;
+    /** The label column — kept for `tooltip-text`, which the browser reads off a PART. */
+    private _textEl;
     private _titleEl;
     private _subtitleEl;
     /** The headless active flag + its notify rule (ADR 0004). */
@@ -21,4 +23,6 @@ export declare class AdwSwitchRow extends HTMLElement {
      */
     private _apply;
     private _renderText;
+    /** Apply CSS line-clamping based on title-lines/subtitle-lines attributes. */
+    private _applyLineClamping;
 }

package/lib/types/elements/adw-toggle-group.d.ts

@@ -1,6 +1,7 @@
 /** A single toggle. Children of <adw-toggle-group>; consumed at connect time. */
 export declare class AdwToggle extends HTMLElement {
     static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
 }
 export declare class AdwToggleGroup extends HTMLElement {
     private _innerEl;
@@ -12,7 +13,21 @@ export declare class AdwToggleGroup extends HTMLElement {
     private _stateAttr;
     /** Each toggle's `name`, in order — what `active-name` resolves against. */
     private _names;
+    /** `AdwToggle:enabled` per rendered button, in order — `add_toggle` spends this at add time. */
+    private _enabled;
+    /** The authored <adw-toggle> elements, kept to observe live `enabled` changes. */
+    private _toggles;
     static get observedAttributes(): string[];
+    /**
+     * `GtkWidget:sensitive` — whether the whole group is insensitive.
+     *
+     * TRUE unless the attribute says `false`, because the property defaults to TRUE and a
+     * boolean attribute read by PRESENCE would leave every group on a page insensitive.
+     */
+    get sensitive(): boolean;
+    set sensitive(value: boolean);
+    /** Whether the toggle at `index` is enabled (`AdwToggle:enabled`) — false once disabled. */
+    isToggleEnabled(index: number): boolean;
     /** Zero-based index of the active toggle. */
     get active(): number;
     set active(value: number);
@@ -30,4 +45,6 @@ export declare class AdwToggleGroup extends HTMLElement {
     private _readActiveAttr;
     private _selectIndex;
     private _render;
+    /** Select the first enabled toggle, if there is one — the C's "no active" repair. */
+    private _activateFirstEnabled;
 }

package/lib/types/elements/gtk-scrolled-window.d.ts

@@ -1,4 +1,4 @@
-import { GtkViewport } from './gtk-viewport.js';
+import type { GtkViewport } from './gtk-viewport.js';
 /** `GtkPolicyType`'s four nicks; `automatic` is the pspec's default for both bars. */
 export type GtkPolicyType = 'always' | 'never' | 'automatic' | 'external';
 /** `GtkCornerType`'s four corners, `top-left` being the pspec's default. */
@@ -10,6 +10,8 @@ export type GtkDirectionType = 'forward' | 'backward';
 export declare class GtkScrolledWindow extends HTMLElement {
     private _viewport;
     private _bars;
+    /** The size clamps `_writeSize` last wrote, which are the only ones it may clear. */
+    private readonly _wroteSizes;
     private _shading;
     private _observer;
     private _hoverable;
@@ -73,7 +75,13 @@ export declare class GtkScrolledWindow extends HTMLElement {
     private get _useIndicators();
     /** Everything the pspec's own state decides: the classes, the bars, the sizes. */
     private _sync;
-    private _size;
+    /**
+     * One of the four clamps as inline style. An unwritten clamp clears only what THIS element
+     * wrote: `min-width` / `min-height` are also where a tree's `width-request` /
+     * `height-request` land (`GTK_WIDGET_SIZE_CSS`), and assigning '' unconditionally erased it.
+     * Where both are set the content clamp wins, which is the one the widget measures itself.
+     */
+    private _writeSize;
     /** The viewport's adjustment for one axis, which is where GTK reads the scrollbar's. */
     private _adjustment;
     /**

package/lib/types/elements/gtk-window.d.ts

@@ -14,8 +14,14 @@ export declare class GtkWindow extends HTMLElement {
     /** Watches the strip for an author's titlebar arriving after the build. */
     private _titlebarObserver;
     static get observedAttributes(): string[];
-    /** `Gtk.Window:title` — the window's title. */
-    get title(): string | null;
+    /**
+     * `Gtk.Window:title` — the window's title.
+     *
+     * The getter answers `''` for no title, not `null`: a `string | null` getter is not assignable to
+     * `HTMLElement.title`, and the emitted `.d.ts` then fails every consumer that does not set
+     * `skipLibCheck`. The setter still takes `null` to clear it, as GTK does.
+     */
+    get title(): string;
     set title(value: string | null);
     /** `Gtk.Window:decorated` — whether the frame and its titlebar strip are drawn at all. */
     get decorated(): boolean;

package/lib/types/index.d.ts

@@ -6,7 +6,7 @@ export type { AdwAccentSource } from './appearance.js';
 export { AdwScrollShading } from './scroll-shading.js';
 export type { AdwUndershootEdges } from './scroll-shading.js';
 export { buildSharedTree, mountSharedTree } from './shared-tree-builder.js';
-export type { MountedSharedTree, SizeSource } from './shared-tree-builder.js';
+export type { MountOptions, MountedSharedTree, SizeSource } from './shared-tree-builder.js';
 export { registerTemplateClass } from './template-classes.js';
 export { isIconAvailable, registerIcon } from './icon-registry.js';
 export * as Adw from './namespace/adw.js';

package/lib/types/row-line-clamp.d.ts

@@ -0,0 +1,20 @@
+export interface RowLineClampConfig {
+    titleEl: HTMLElement;
+    subtitleEl: HTMLElement;
+    textContainerEl: HTMLElement;
+    getTitleLines: () => number;
+    getSubtitleLines: () => number;
+}
+/**
+ * Apply or remove line clamping based on title-lines/subtitle-lines values.
+ * Uses CSS custom properties and class toggle (not inline styles).
+ */
+export declare function applyRowLineClamp(config: RowLineClampConfig): void;
+/**
+ * Parse a lines attribute value following AdwActionRow semantics:
+ * - Missing/null/empty → 0 (unlimited)
+ * - Invalid/non-numeric → 0 (unlimited)
+ * - n > 0 → n (clamp to n lines)
+ * - n <= 0 → 0 (unlimited; pspec range is 0..G_MAXINT)
+ */
+export declare function parseRowLinesAttribute(value: string | null): number;

package/lib/types/row-tooltip.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Apply `row`'s `tooltip-text` to `parts`, or clear it when the attribute is absent.
+ *
+ * `parts` are the row's OWN sections, never a slotted consumer widget — see the header.
+ * Each one is marked `data-row-tooltip`, which is the hook `scss/_row.scss` stretches so
+ * the tooltip covers the row rather than the label text inside it.
+ */
+export declare function applyRowTooltip(row: HTMLElement, parts: readonly Element[]): void;

package/lib/types/row-tooltip.spec.d.ts

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

package/lib/types/shared-tree-builder.d.ts

@@ -44,21 +44,22 @@ interface PendingBind {
  * A `SharedTreeNode`, realised as a DETACHED element tree: a tag, its authored properties as
  * attributes, its style classes as classes, its extensions (ADR 0072) as the markup the element
  * reads, its placement as `slot=`, its children, in that order — recursive and total,
- * no tag list, no per-block case. A boolean authored property is the ATTRIBUTE'S PRESENCE
- * (`toggleAttribute`), which is what every element in the corpus reads
- * (`hasAttribute('revealed')`, `hasAttribute('expanded')`); spelling `"true"` would set a
- * present attribute for `false` as well.
+ * no tag list, no per-block case.
  *
- * EXCEPT AN AUTHORED `false` ON A PROPERTY THE ELEMENT DECLARES. Absence cannot say `false`
- * where the GTK default is TRUE — `AdwNavigationPage:can-pop`, `GtkActionBar:revealed` —
- * because those elements read an absent attribute as that default, so `can-pop: false`
- * reached the page as `can-pop` unset and the page stayed poppable. The element's own
- * property setter knows its attribute convention, so an authored `false` is written
- * through it when the element (already upgraded: `createElement` of a defined tag
- * constructs it) declares one; everything else keeps the presence rule. "Declares" means a
- * member it can WRITE ({@link isWritable}): a getter-only accessor of the same name — the
- * split button's and the menu button's read-only `active` — would throw a bare `TypeError`
- * out of the assignment, so such a property falls back to the presence rule too.
+ * BOOLEAN ATTRIBUTES are written per (widget, property), not per attribute name. The same
+ * attribute name (e.g. `revealed`) can be VALUE-BASED for one widget (`gtk-action-bar`,
+ * default TRUE) and PRESENCE-BASED for another (`adw-banner`, default FALSE). The
+ * per-widget map in `@gjsify/adwaita-core/tags` ({@link isValueBasedBooleanAttr}) records this.
+ *
+ * - VALUE-BASED: `attr="false"` means false, absent means true (the GTK default).
+ *   The builder writes `attr="true"|"false"` directly via {@link writeBooleanAttribute}.
+ * - PRESENCE-BASED (style classes like `flat`, `round`, `compact`): `toggleAttribute`
+ *   writes the bare attribute for `true`, removes it for `false`.
+ *
+ * EXCEPT an authored `false` on a NON-value-based, WRITABLE property: the property is set
+ * directly (bypassing the attribute) because the element's setter will reflect it correctly.
+ * A getter-only property of the same name (e.g. `AdwSplitButton.active`) falls back to the
+ * presence rule since assignment would throw.
  *
  * THE SLOT IS WRITTEN AS THE ATTRIBUTE THIS RENDERER ALREADY ROUTES ON, not translated:
  * `src/slotted-children.ts` reads `slot=` off every light-DOM child and keeps the routing
@@ -72,21 +73,50 @@ interface PendingBind {
  * upgraded has declared no slots yet, so the refusal below belongs to the mount.
  */
 export declare function buildSharedTree(node: SharedTreeNode, record?: BuildRecord): HTMLElement;
+/**
+ * One authored property, written as the element reads it; a breakpoint setter takes the same door.
+ *
+ * BOOLEAN ATTRIBUTES are written per (widget, property), not per attribute name. The same
+ * attribute name (e.g. `revealed`) can be VALUE-BASED for one widget (`gtk-action-bar`,
+ * default TRUE) and PRESENCE-BASED for another (`adw-banner`, default FALSE). The
+ * per-widget map in `@gjsify/adwaita-core/tags` ({@link isValueBasedBooleanAttr}) records this.
+ *
+ * - VALUE-BASED: `attr="false"` means false, absent means true (the GTK default).
+ *   The builder writes `attr="true"|"false"` directly via {@link writeBooleanAttribute}.
+ * - PRESENCE-BASED (style classes like `flat`, `round`, `compact`): `toggleAttribute`
+ *   writes the bare attribute for `true`, removes it for `false`.
+ *
+ * EXCEPT an authored `false` on a NON-value-based, WRITABLE property: the property is set
+ * directly (bypassing the attribute) because the element's setter will reflect it correctly.
+ * A getter-only property of the same name (e.g. `AdwSplitButton.active`) falls back to the
+ * presence rule since assignment would throw. `hexpand` / `vexpand` keep an authored `false`
+ * as the attribute `"false"` and a later `true` rewrites it — `GTK_WIDGET_EXPAND` says why.
+ */
+export declare function writeProp(el: HTMLElement, prop: string, value: string | number | boolean): void;
 /** A tree {@link mountSharedTree} built and connected. */
 export interface MountedSharedTree {
     /** The authored root — connected, so every custom element under it has upgraded and run. */
     root: HTMLElement;
-    /** Disconnects and discards the mount point. */
+    /** Disconnects the tree, and discards the mount point when this call made one. */
     unmount: () => void;
 }
+/** What {@link mountSharedTree} takes beside the tree. */
+export interface MountOptions {
+    /** The object a handler NAME is looked up on (ADR 0093 § 3). */
+    scope?: Readonly<Record<string, unknown>>;
+    /** The size source a `breakpoints` node is driven from. */
+    observeSize?: SizeSource;
+    /**
+     * Where the root is appended — a showcase's own container, which then lays the window out.
+     * Without it the tree gets a fresh host `<div>` in `document.body`, discarded on `unmount`.
+     */
+    into?: HTMLElement;
+}
 /**
  * {@link buildSharedTree}, attached under a fresh host `<div>` in `document.body` so the tree
  * — and every custom element in it — is REAL rather than merely constructed. This is the
  * instantiation half a caller reading the corpus's elements normally wants; a bare
  * `buildSharedTree` is for a caller that already has somewhere of its own to attach it.
  */
-export declare function mountSharedTree(node: SharedTreeNode, options?: {
-    scope?: Readonly<Record<string, unknown>>;
-    observeSize?: SizeSource;
-}): MountedSharedTree;
+export declare function mountSharedTree(node: SharedTreeNode, options?: MountOptions): MountedSharedTree;
 export {};

package/lib/types/shared-tree-mount.spec.d.ts

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