@gjsify/adwaita-web 0.54.0 → 0.56.0

package/lib/types/elements/gtk-popover-bin.d.ts

@@ -0,0 +1,82 @@
+import type { AdwMenuActions, AdwMenuInput, AdwMenuModel } from '@gjsify/adwaita-core';
+import './gtk-popover-menu.js';
+import type { GtkPopoverMenu } from './gtk-popover-menu.js';
+export declare class GtkPopoverBin extends HTMLElement {
+    private _model;
+    private _popover;
+    private _actions;
+    private _initialized;
+    private _longPressTimer;
+    static get observedAttributes(): string[];
+    /** The menu model, normalised (ADR 0042). */
+    get menuModel(): AdwMenuModel;
+    /**
+     * The model the popover is built from — ONE slot with `popover`, because GTK's two
+     * setters clear each other (gtkpopoverbin.c:474-500, :543-551). A model REPLACES the
+     * popover; a popover DROPS the model, and both notify for both properties.
+     */
+    set menuModel(value: AdwMenuInput | AdwMenuModel);
+    /**
+     * The popover this bin presents, or `null`.
+     *
+     * NOT `popover`, which is `GtkPopoverBin`'s GObject name and also `HTMLElement`'s: the
+     * DOM's Popover API spells a string attribute `popover`, and shadowing it with a widget
+     * would make the element disagree with the platform it sits on. The `Element` suffix is
+     * what this package already uses where a GIR name is taken (`childElement` below, and
+     * `Adw.NavigationPage`'s own `navigationPage`).
+     */
+    get popoverElement(): GtkPopoverMenu | null;
+    set popoverElement(value: GtkPopoverMenu | null);
+    /** Whether a right click or a long press opens the popover. GTK's default is FALSE. */
+    get handleInput(): boolean;
+    set handleInput(value: boolean);
+    /** What the action group publishes about the actions the menu names (ADR 0042). */
+    get actions(): AdwMenuActions | null;
+    set actions(value: AdwMenuActions | null);
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name?: string): void;
+    /** The `menu.popup` action — present the popover. */
+    popup(): void;
+    /** Dismiss the popover. */
+    popdown(): void;
+    /** The widget whose `.has-open-popup` follows the popover, when the bin has one. */
+    get childElement(): HTMLElement | null;
+    private _wireGestures;
+    private _cancelLongPress;
+    private _onContextMenu;
+    /**
+     * `popup_at_position` WITH the pointer's coordinates, which is the branch that sets
+     * `pointing-to` to `(x, y)` (gtkpopoverbin.c:141-145). `<gtk-popover>` has no
+     * `pointing-to` to set — placement is the `position`/`align` pair, the same gap the
+     * element's own KNOWN_GAPS records — so the call is the plain `popup()` and what the
+     * reader sees is GTK's: the menu under the child.
+     */
+    private _popupAt;
+    /**
+     * The Menu key, which is the shortcut GTK installs next to the gestures
+     * (`gtk_shortcut_trigger_create_for_menu`, gtkpopoverbin.c:643-649). GTK builds the
+     * trigger in the platform's canonical form, which a keydown cannot carry, so the
+     * un-modified key beside Shift is the whole binding here.
+     */
+    private _onKeyDown;
+    private _buildPopover;
+    /**
+     * `set_popover` (gtkpopoverbin.c:543-587): hide and unparent the old one, parent the
+     * new one, and wire the map/unmap handlers that carry `.has-open-popup` on the child.
+     */
+    private _adoptPopover;
+    /**
+     * `g_object_notify_by_pspec` is called for `:popover` AND `:menu-model` by BOTH setters
+     * (gtkpopoverbin.c:502, :586-587), because the two are one slot. One event carrying
+     * both is the faithful reading, and the second notify GTK sends separately has no state
+     * of its own to report.
+     */
+    private _notifyModel;
+    /**
+     * The `menu-model` ATTRIBUTE through the core parser, refusing a `custom` item the way
+     * every menu-bearing surface here does: markup is parsed by the browser, so a throw from
+     * `connectedCallback` would reach nobody and the menu would be silently empty.
+     */
+    private _parseMenuAttr;
+}

package/lib/types/elements/gtk-popover-menu-bar.d.ts

@@ -0,0 +1,66 @@
+import type { AdwMenuActions, AdwMenuInput, AdwMenuModel } from '@gjsify/adwaita-core';
+import './gtk-popover-menu.js';
+export declare class GtkPopoverMenuBar extends HTMLElement {
+    private _model;
+    private _actions;
+    private _items;
+    private _active;
+    private _initialized;
+    static get observedAttributes(): string[];
+    /** The menu model, normalised (ADR 0042). */
+    get menuModel(): AdwMenuModel;
+    set menuModel(value: AdwMenuInput);
+    /** What the action group publishes about the actions these menus name (ADR 0042). */
+    get actions(): AdwMenuActions | null;
+    set actions(value: AdwMenuActions | null);
+    /** The active item's button, or `null` — GTK's `active_item`, as a widget. */
+    get activeItem(): HTMLElement | null;
+    connectedCallback(): void;
+    attributeChangedCallback(name?: string): void;
+    /** `gtk_popover_menu_bar_select_first` — activate and OPEN the first item. */
+    selectFirst(): void;
+    /** What the bar's `menu.popup` action does, which is the same thing. */
+    popup(): void;
+    /**
+     * `set_active_item` (gtkpopovermenubar.c:126-163), variable names and all.
+     *
+     * `changed` and `was_popup` decide three DIFFERENT outcomes — close the old one, open
+     * the new one, or move focus onto it — and collapsing them is how a hover would come to
+     * open menus, which is the single behaviour that separates a menubar from a row of menu
+     * buttons.
+     */
+    private _setActive;
+    private _onKeyDown;
+    /**
+     * The sibling in `step`'s direction, WRAPPING at either end
+     * (gtkpopovermenubar.c:232-252): with no active item there is no sibling, so the first
+     * move goes to the first child for RIGHT and to the LAST for LEFT.
+     */
+    private _move;
+    private _rebuild;
+    /**
+     * Focus the first row a key can reach in a menu that has just opened.
+     *
+     * This is what `autohide` does in GTK: `gtk_popover_show` calls
+     * `gtk_widget_child_focus (widget, GTK_DIR_TAB_FORWARD)` when the property holds
+     * (gtkpopover.c:1188-1192), and a browser popup takes no focus until it is told to —
+     * which is why the item whose menu opened is what does it here.
+     */
+    private _focusFirstRow;
+    /**
+     * One `menubar > item > popover` (the node tree in gtkpopovermenubar.c:38-46).
+     *
+     * A toplevel node that is not a submenu is refused by `_parseMenuAttr` with GTK's own
+     * wording rather than drawn: `tracker_insert` builds nothing for it
+     * (gtkpopovermenubar.c:466), and a row that opens nothing is the same lie in another
+     * shape.
+     */
+    private _buildItem;
+    /**
+     * Activating a row inside one of the popovers closes THAT popover and hands focus back
+     * to its item, which is what `gtk_popover_menu_set_active_item` does when the active
+     * row is not the row that opened a submenu (gtkpopovermenu.c:257-259).
+     */
+    private _activate;
+    private _parseMenuAttr;
+}

package/lib/types/elements/gtk-popover-menu.d.ts

@@ -0,0 +1,83 @@
+import type { AdwMenuActions, AdwMenuInput, AdwMenuModel } from '@gjsify/adwaita-core';
+import { GtkPopover } from './gtk-popover.js';
+export declare class GtkPopoverMenu extends GtkPopover {
+    private _model;
+    private _actions;
+    private _menuView;
+    /** Named apart from `GtkPopover`'s own: two `private` fields of one name are two fields. */
+    private _menuInitialized;
+    static get observedAttributes(): string[];
+    /** The menu, normalised (ADR 0042). */
+    get menuModel(): AdwMenuModel;
+    /**
+     * Set the menu from anything the portable model accepts, refusing a `custom` item
+     * HERE — at the assignment, where it is a call the caller can catch. An ATTRIBUTE is
+     * markup the browser parses, so the attribute path refuses the whole menu instead and
+     * says why on `console.error`, exactly as `<gtk-menu-button>` does.
+     *
+     * `AdwMenuModel` is in the union because a menu bar hands over a submenu's own `items`
+     * untouched, and `normalizeMenuModel` is documented to be IDEMPOTENT over an
+     * already-normalised node — that is what lets a renderer hand a model it is holding
+     * straight back. The one cast is where the core's parameter type (`AdwMenuInput`, whose
+     * entries are the AUTHORED shapes) is narrower than the behaviour it documents.
+     */
+    set menuModel(value: AdwMenuInput | AdwMenuModel);
+    /** What the action group publishes about the actions this menu names (ADR 0042). */
+    get actions(): AdwMenuActions | null;
+    set actions(value: AdwMenuActions | null);
+    /** The optional heading. GTK spells one as a labelled SECTION; this is the shorthand. */
+    get menuTitle(): string;
+    set menuTitle(value: string);
+    /**
+     * The name of the open page — `'main'` for the root, a submenu's label for a submenu.
+     *
+     * GTK's value is the stack child's NAME, which `GtkMenuTracker` gives a submenu page
+     * from the node it links; with no name given that is the submenu's label, so the label
+     * is what this element answers with. `gtk_popover_menu_open_submenu` (gtkpopovermenu.c
+     * :755-757) is the only way in, so setting it navigates rather than describing.
+     */
+    get visibleSubmenu(): string;
+    set visibleSubmenu(value: string);
+    connectedCallback(): void;
+    attributeChangedCallback(name?: string, previous?: string | null, value?: string | null): void;
+    /** `gtk_popover_menu_open_submenu` — switch to the named page. */
+    openSubmenu(name: string): void;
+    /**
+     * The ONE way the open page changes, from the property and from the attribute alike.
+     *
+     * The notify belongs HERE rather than beside the attribute write: a page can change
+     * without the attribute's text changing (`openSubmenu('More')` when it is already
+     * `More` after a dismissal, or an attribute set to the page already showing), and
+     * `GObject` notifies on the state, not on the spelling.
+     */
+    private _navigate;
+    /**
+     * Point the page stack at the named page and rebuild it. `false` when the name is not
+     * one of the stack's children, which is what `gtk_stack_set_visible_child_name` leaves
+     * alone — the current page keeps showing rather than the surface blanking.
+     */
+    private _showPage;
+    /**
+     * `gtk_popover_menu_close_submenus` — leave the open submenu, ONE level
+     * (gtkpopovermenu.c:223-233), which is what the back row does.
+     */
+    closeSubmenus(): void;
+    private _openPageLabel;
+    private _findSubmenu;
+    /**
+     * Write the open page back to the attribute, ONCE, and only when the spelling differs.
+     *
+     * Reading the attribute instead of the state is the whole loop guard: navigating sets
+     * this, the attribute change calls back into `_navigate`, and a comparison against the
+     * current value stops the second turn.
+     */
+    private _reflectSubmenu;
+    /**
+     * Activating an item closes the popover and returns focus to the anchor — the
+     * behaviour every menu-bearing surface here has, and the reason a menu cannot be left
+     * open by choosing from it.
+     */
+    private _activate;
+    private _renderMenu;
+    private _parseMenuAttr;
+}

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

@@ -2,8 +2,15 @@
 export type GtkPopoverPosition = 'bottom' | 'top' | 'start' | 'end';
 /** Which edge of the anchor the surface lines up with. */
 export type GtkPopoverAlign = 'start' | 'end';
-/** The ARIA role of the surface — it decides the row role consumers give their items. */
-export type GtkPopoverRole = 'menu' | 'listbox';
+/**
+ * The ARIA role of the surface — it decides the row role consumers give their items.
+ *
+ * `dialog` is the one role that is not a container of ROWS: it is for a surface holding
+ * content, so nothing derives an item role from it. Upstream splits the same way —
+ * `GtkPopoverMenu` declares itself a menu (`refs/gtk/gtk/gtkpopovermenu.c:676`), a bare
+ * `GtkPopover` declares nothing.
+ */
+export type GtkPopoverRole = 'menu' | 'listbox' | 'dialog';
 export declare class GtkPopover extends HTMLElement {
     private readonly _state;
     private _anchor;
@@ -15,6 +22,17 @@ export declare class GtkPopover extends HTMLElement {
     static get observedAttributes(): string[];
     get open(): boolean;
     set open(value: boolean);
+    /**
+     * Whether an outside click (or an Escape) dismisses the popover — GTK's grab.
+     *
+     * `autohide` defaults to TRUE in C (`priv->autohide = TRUE`, gtkpopover.c:1046) and
+     * that default is what every existing consumer in this package relies on, so it is
+     * the ABSENCE of the attribute rather than its presence, exactly as GTK spells it.
+     * Turning it off is entry completion's shape, which is the usecase the property
+     * documents: the entry keeps the caret and the list follows the typing.
+     */
+    get autohide(): boolean;
+    set autohide(value: boolean);
     /**
      * The element the surface is positioned against and hands focus back to. Defaults to
      * `parentElement`: the popover is normally the last child of the widget that owns it.
@@ -25,6 +43,7 @@ export declare class GtkPopover extends HTMLElement {
     set position(value: GtkPopoverPosition);
     get align(): GtkPopoverAlign;
     set align(value: GtkPopoverAlign);
+    /** The ARIA role of the surface; an unknown value reads as the `menu` default. */
     get popoverRole(): GtkPopoverRole;
     /**
      * The navigable rows, in DOM order.
@@ -50,7 +69,13 @@ export declare class GtkPopover extends HTMLElement {
     connectedCallback(): void;
     private _buildOnce;
     disconnectedCallback(): void;
-    attributeChangedCallback(name: string, _previous: string | null, value: string | null): void;
+    /**
+     * Every parameter is optional, and that is FOR `<gtk-popover-menu>`, which subclasses
+     * this element: an override may not demand a parameter the base signature does not pass,
+     * and the platform always passes all three — the `?` is a typescript-visible fact about
+     * the CALLER, not about what arrives.
+     */
+    attributeChangedCallback(name?: string, _previous?: string | null, value?: string | null): void;
     private _onStateChange;
     private _bindDocument;
     private _unbindDocument;

package/lib/types/elements/gtk-print-unix-dialog.d.ts

@@ -0,0 +1,167 @@
+import { type PageSetup } from '../page-setup.js';
+import { AdwDialog } from './adw-dialog.js';
+/** The `GtkPrintCapabilities` nicks, in enum order (the GIR's own spelling). */
+declare const CAPABILITY_NICKS: readonly ["collate", "copies", "generate-pdf", "generate-ps", "number-up", "number-up-layout", "page-set", "preview", "reverse", "scale"];
+/** One `GtkPrintCapabilities` nick. */
+export type PrintCapability = (typeof CAPABILITY_NICKS)[number];
+/** One row of the printer list — what `GtkPrinter` answers name / location / icon for. */
+export interface PrinterInfo {
+    readonly name: string;
+    readonly location?: string;
+    /** The `.ui`'s icon column, from the printer's own `icon-name`. */
+    readonly iconName?: string;
+    /** `gtk_printer_is_accepting_jobs` — what gates the Print button. */
+    readonly acceptsJobs?: boolean;
+    /** `gtk_printer_get_capabilities` — the second half of every sensitivity gate. */
+    readonly capabilities?: readonly PrintCapability[];
+    /** Whether the row passes `is_printer_active` (:1164-1186). */
+    readonly active?: boolean;
+}
+/** The `Gtk.PrintSettings` this dialog carries, in the keys its own UI sets. */
+export interface PrintSettingsData {
+    /** `format-for-printer` — the printer the settings belong to. */
+    readonly 'format-for-printer'?: string;
+    /** `copies` — a string, because `GtkPrintSettings` values are all strings. */
+    readonly copies?: string;
+    /** `collate` / `reverse` — `"0"` or `"1"`, as CUPS writes them. */
+    readonly collate?: string;
+    readonly reverse?: string;
+    /** `page-set` — `all` / `even` / `odd`, the index into `PAGE_SET_ITEMS`. */
+    readonly 'page-set'?: string;
+    /** `scale` — a percentage, as a string. */
+    readonly scale?: string;
+    /** `orientation` — `portrait` … `reverse-landscape`. */
+    readonly orientation?: string;
+    /** `print-at` — an ISO timestamp for the "At:" branch. */
+    readonly 'print-at'?: string;
+    /** `printer-setting-…` — the per-printer option groups of the Job tab. */
+    readonly [key: string]: string | undefined;
+}
+export declare class GtkPrintUnixDialog extends AdwDialog {
+    private _built;
+    private _printers;
+    private _selected;
+    private _settings;
+    private _pageSetup;
+    private _printerListEl;
+    private _switcherEl;
+    private _panelEl;
+    private _tabPages;
+    private _tab;
+    private _currentPage;
+    private _supportSelection;
+    private _hasSelection;
+    private _manual;
+    private _range;
+    private _printAt;
+    private _printButton;
+    private _previewButton;
+    private _conflictsEl;
+    private _capabilityControls;
+    private _collateCheck;
+    private _reverseCheck;
+    private _copiesInput;
+    private _paperDrop;
+    private _orientationDrop;
+    private _pageRangeInput;
+    private _selectionRadio;
+    private _currentPageRadio;
+    private _rangeRadios;
+    private _atInput;
+    static get observedAttributes(): string[];
+    /** `current-page`, in 0-based document pages; -1 disables "Current Page". */
+    get currentPage(): number;
+    set currentPage(value: number);
+    /** Whether the page-setup controls are EMBEDDED rather than in their own dialog. */
+    get embedPageSetup(): boolean;
+    set embedPageSetup(value: boolean);
+    /** Whether the application has a selection to print. */
+    get hasSelection(): boolean;
+    set hasSelection(value: boolean);
+    /** Whether the application supports printing a selection. */
+    get supportSelection(): boolean;
+    set supportSelection(value: boolean);
+    /** The capabilities the APPLICATION handles, as `GtkPrintCapabilities` nicks. */
+    get manualCapabilities(): PrintCapability[];
+    set manualCapabilities(value: readonly PrintCapability[]);
+    /** The chosen printer, or `null` — `gtk_print_unix_dialog_get_selected_printer`. */
+    get selectedPrinter(): PrinterInfo | null;
+    /** The page setup, as the plain `PageSetup` the value model defines. */
+    get pageSetup(): PageSetup;
+    set pageSetup(value: PageSetup);
+    /** The print settings, in the keys the dialog's own controls write. */
+    get printSettings(): PrintSettingsData;
+    set printSettings(value: PrintSettingsData);
+    /**
+     * Which of the four range buttons is active — the radio group the `.ui` calls the
+     * Range frame. GTK has no property for it either: the dialog READS whichever of the four
+     * `GtkCheckButton`s is active (`dialog_get_page_range`), and that is what this holds.
+     */
+    get range(): 'all' | 'current' | 'selection' | 'pages';
+    set range(value: 'all' | 'current' | 'selection' | 'pages');
+    /** The printers a print backend would have discovered. An INPUT here — see the header. */
+    get printers(): PrinterInfo[];
+    set printers(value: readonly PrinterInfo[]);
+    connectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    /**
+     * `manual-capabilities` takes the nick SET the GIR generates, `|`-separated —
+     * `manual-capabilities="page-set|copies|collate|reverse|scale|preview"`. Unknown
+     * nicks are dropped, which is what the GIR-validated setter does with them.
+     */
+    private _readManual;
+    protected decorateHeader(header: HTMLElement): void;
+    private _build;
+    /**
+     * Every page of the notebook, built once and hidden but for the visible one —
+     * which is what `GtkNotebook` holds: all seven pages exist whether shown or not,
+     * so the capability pass can reach every control from the first render.
+     */
+    private _renderPanel;
+    private _buildTab;
+    /** General: the printer list, then Range and Copies. */
+    private _buildGeneral;
+    /** `page_collate_preview`: four thumbnails whose NUMBERS show the ordering. */
+    private _buildCollatePreview;
+    /** Page Setup: Layout and Paper beside the sheet preview. */
+    private _buildPageSetup;
+    /**
+     * `page_layout_preview` (:2683) + `draw_page` (:2283): the sheet at 110px on its long
+     * edge, divided by the number-up grid with each cell numbered in the number-up order.
+     * The ruler the C draws around it is decoration outside the sheet and is not painted.
+     */
+    private _buildSheetPreview;
+    /** Job: Job Details, Print Document, Add Cover Page. */
+    private _buildJob;
+    /**
+     * One of the four option pages: the scrolled viewport + grid the C's
+     * `GtkPrinterOptionWidget`s are added to. There are none without a backend, so the grid
+     * is empty and says so rather than inventing options.
+     */
+    private _buildOptionsPage;
+    /** The option grid, one row per option group the backend would offer. */
+    private _optionsGrid;
+    /** The conflicts action bar — hidden until `mark_conflicts` finds one (:3050-3060). */
+    private _buildConflicts;
+    /** Preview / Cancel / Print, in the `.ui`'s order and with its own response ids. */
+    private _buildActions;
+    private _respond;
+    /**
+     * One `frame_templateN`: a BOLD heading over a grid, which is the shape every group in
+     * the `.ui` has — `box > box > grid` with the heading's `weight=bold`.
+     */
+    private _group;
+    private _labelledRow;
+    private _dropDown;
+    private _radio;
+    private _check;
+    private _frame;
+    /** `selected_printer_changed` (:1821-1915) — the list and what selecting does. */
+    private _printerChanged;
+    private _paperChanged;
+    /** Every capability the dialog currently has: the manual half OR the printer's. */
+    private _capabilities;
+    /** `update_dialog_from_capabilities` (:1563-1592), every line of it. */
+    private _renderPrint;
+}
+export {};

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

@@ -0,0 +1,55 @@
+/** Every `GtkRevealerTransitionType` nick, in GIR order. */
+declare const TRANSITION_TYPES: readonly ["none", "crossfade", "slide-right", "slide-left", "slide-up", "slide-down", "swing-right", "swing-left", "swing-up", "swing-down", "fade-slide-right", "fade-slide-left", "fade-slide-up", "fade-slide-down"];
+export type RevealerTransitionType = (typeof TRANSITION_TYPES)[number];
+export declare class GtkRevealer extends HTMLElement {
+    private _clipEl;
+    private _initialized;
+    /** `current_pos` — 0 hidden, 1 shown. */
+    private _position;
+    /** `target_pos` — where the running animation is headed. */
+    private _target;
+    private _frame;
+    private _startedAt;
+    /** The child's own size — `child_width` / `child_height` in the C. */
+    private _naturalWidth;
+    private _naturalHeight;
+    private _resize;
+    static get observedAttributes(): string[];
+    /** `Gtk.Revealer:reveal-child` — whether the child should be revealed. */
+    get revealChild(): boolean;
+    set revealChild(value: boolean);
+    /** `Gtk.Revealer:child-revealed` — read-only; the header says why it inverts. */
+    get childRevealed(): boolean;
+    /** `Gtk.Revealer:transition-type`. An unknown nick leaves `slide-down` in place. */
+    get transitionType(): RevealerTransitionType;
+    set transitionType(value: RevealerTransitionType);
+    /** `Gtk.Revealer:transition-duration`, in ms. An unparseable one is the default. */
+    get transitionDuration(): number;
+    set transitionDuration(value: number);
+    /** `Gtk.Revealer:child` — the light-DOM node the clip box adopted. */
+    get child(): Element | null;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+    /**
+     * Point the measurement at the CHILD, not at the clip box.
+     *
+     * The C asks the child for its requisition (gtkrevealer.c:140) and scales the result,
+     * so the child is the subject; observing the clip box instead would report the ALREADY
+     * SCALED box, and the scale would then be applied twice.
+     */
+    private _observeChild;
+    /** `gtk_revealer_start_animation` (gtkrevealer.c:275-322). `@returns` whether it moved. */
+    private _animate;
+    /** `gtk_revealer_animate_cb` (gtkrevealer.c:255-272). */
+    private _tick;
+    private _finish;
+    /** `effective_transition` (gtkrevealer.c:121-141). */
+    private get effectiveTransition();
+    /** `get_child_size_scale` (gtkrevealer.c:144-186) for one axis. */
+    private _scale;
+    /** `gtk_revealer_set_position` (gtkrevealer.c:212-251). */
+    private _setPosition;
+    private _render;
+}
+export {};

package/lib/types/elements/gtk-scale-button.d.ts

@@ -0,0 +1,59 @@
+import './gtk-popover.js';
+export declare class GtkScaleButton extends HTMLElement {
+    private readonly _state;
+    private _buttonEl;
+    private _glyph;
+    private _dockEl;
+    private _rangeEl;
+    private _minusEl;
+    private _plusEl;
+    private _icons;
+    private _initialized;
+    /** Set while a render writes the range, so its `input` echo is not fed back. */
+    private _syncing;
+    static get observedAttributes(): string[];
+    /** `Gtk.ScaleButton:value` — always inside the adjustment's range. */
+    get value(): number;
+    set value(value: number);
+    /** `Gtk.ScaleButton:active` — read-only upstream, so read-only here. */
+    get active(): boolean;
+    /** `Gtk.ScaleButton:icons` — the icon names the value picks from. */
+    get icons(): string[];
+    set icons(value: string[]);
+    /** `Gtk.ScaleButton:has-frame` — false by default, which is a flat button here. */
+    get hasFrame(): boolean;
+    set hasFrame(value: boolean);
+    /** `GtkOrientable:orientation` — vertical by default, the GTK shape of the button. */
+    get orientation(): 'horizontal' | 'vertical';
+    set orientation(value: 'horizontal' | 'vertical');
+    connectedCallback(): void;
+    attributeChangedCallback(name?: string): void;
+    /** `cb_scale_value_changed` (:1092-1114) — the icon, the steppers, then the signals. */
+    private _applyValue;
+    /** The range, from GTK's default with whatever `adjustment` authored over it. */
+    private _syncAdjustment;
+    private _render;
+    private _stepButton;
+    private _toggleDock;
+    /** `gtk_scale_popup` (:940-948) — press the button in, which pops the dock up. */
+    private _dock;
+    /** The dock closing on its own — an outside click or Escape. */
+    private _renderDock;
+    /** `button_click` (:1000-1013): one PAGE increment, and the end of the range stops it. */
+    private _step;
+    /** Space / Return / Enter pop up, Escape pops down — the bindings `class_init` adds. */
+    private _onKeyDown;
+}
+/**
+ * `gtk_scale_button_update_icon` (:1040-1098) — which of the icon names the value picks.
+ * Transcribed including the arithmetic, because "spread evenly" is only true of the
+ * interior: `lower` and `upper` always take the first two names.
+ */
+export declare function selectIcon(icons: string[], value: number, lower: number, upper: number): string;
+/**
+ * The `icons` attribute, as the portable array a list-model property takes elsewhere
+ * (ADR 0046). Total in every failure mode, because malformed JSON is an author slip that
+ * must not stop the element upgrading — and an empty list has an answer of its own,
+ * `image-missing` (:1046-1050).
+ */
+export declare function parseIcons(raw: string | null | undefined): string[];

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

@@ -0,0 +1,98 @@
+import type { AdwAdjustment, AdwAdjustmentInput, BoxOrientation } from '@gjsify/adwaita-core';
+/** `Gtk.PositionType` nicks, as `GtkScale:value-pos` spells them. */
+declare const VALUE_POSITIONS: readonly ["left", "right", "top", "bottom"];
+/** `GtkScale:value-pos` in the order libadwaita lays the value out: default `top`. */
+type ValuePosition = (typeof VALUE_POSITIONS)[number];
+/**
+ * `gtk_scale_format_value`'s default arm plus `weed_out_neg_zero` (gtkscale.c:1230-1245).
+ *
+ * Exported for the widget's own spec; `<gtk-spin-button>` carries the SAME `g_strdup_printf
+ * ("%0.*f")` in its own C (`gtk_spin_button_format_for_value`, gtkspinbutton.c:1319-1326) with
+ * a different `digits` default, and reuses this rather than growing a second copy of it.
+ */
+export declare function formatScaleValue(value: number, digits: number): string;
+export declare class GtkScale extends HTMLElement {
+    /** The headless `Gtk.Adjustment`: the range, the clamp and the two signals (ADR 0004, ADR 0047). */
+    private readonly _range;
+    private _trough;
+    private _highlight;
+    private _fill;
+    private _slider;
+    private _value;
+    private _initialized;
+    private _pointerId;
+    static get observedAttributes(): string[];
+    /** `GtkOrientable:orientation` — `horizontal` (the default) or `vertical`. */
+    get orientation(): BoxOrientation;
+    set orientation(value: BoxOrientation);
+    /** The numeric range — `Gtk.Range:adjustment`, as the portable value. Writes MERGE. */
+    get adjustment(): AdwAdjustment;
+    set adjustment(value: AdwAdjustmentInput | string);
+    /** `Gtk.Range:value` — always inside `adjustmentRange`. */
+    get value(): number;
+    set value(v: number);
+    /** `Gtk.Range:inverted`. */
+    get inverted(): boolean;
+    set inverted(value: boolean);
+    /** `GtkScale:draw-value` — whether the value is shown beside the slider. */
+    get drawValue(): boolean;
+    set drawValue(value: boolean);
+    /** `GtkScale:value-pos` — `left`, `right`, `top` (the default) or `bottom`. */
+    get valuePos(): ValuePosition;
+    set valuePos(value: ValuePosition);
+    /** `GtkScale:has-origin` — the default, so the highlight exists unless it is cleared. */
+    get hasOrigin(): boolean;
+    set hasOrigin(value: boolean);
+    /** `GtkScale:digits` — decimal places in the value text. */
+    get digits(): number;
+    set digits(value: number);
+    /** `Gtk.Range:fill-level` — the buffer level a media player would draw. */
+    get fillLevel(): number;
+    set fillLevel(value: number);
+    /** `Gtk.Range:show-fill-level` — no property by default, as `gtk_range_init` leaves it. */
+    get showFillLevel(): boolean;
+    set showFillLevel(value: boolean);
+    /** `Gtk.Range:restrict-to-fill-level`. */
+    get restrictToFillLevel(): boolean;
+    set restrictToFillLevel(value: boolean);
+    /** The knob, for a consumer that needs to measure it (`coord_to_value` needs its length). */
+    get slider(): HTMLElement;
+    connectedCallback(): void;
+    attributeChangedCallback(name: string): void;
+    /**
+     * `gtk_range_real_change_value`'s write, with the range's own clamp inside `SpinState`.
+     *
+     * `restrict-to-fill-level` and `round-digits` are `GtkRange`'s own two lines before the
+     * CLAMP (gtkrange.c:2873-2891), so they belong here rather than in the element's setter.
+     * `interactive` is what separates a drag from a programmatic write in `SpinState`.
+     */
+    private _setValue;
+    /**
+     * `coord_to_value` (gtkrange.c:1838-1878), which is `GtkScale`'s whole pointer mapping.
+     *
+     * A SCALE sets `slider_size_fixed`, so the fraction is `coord / trough_length` and the
+     * slider's own length does not shorten the track — the knob's CENTRE is the value. An
+     * equal-length degenerate trough answers 1.0, as C does.
+     */
+    private _valueAtCoord;
+    /**
+     * `should_invert` (gtkrange.c:1806-1818) for a scale, which is always `flippable`
+     * (`gtk_scale_init`, gtkscale.c:838).
+     *
+     * A horizontal scale in a RIGHT-TO-LEFT document is the case the `flippable` flag
+     * exists for: `inverted` false already reads backwards there, so the two cancel and
+     * the fraction is used as it comes.
+     */
+    private _shouldInvert;
+    private _onPointerDown;
+    private _onPointerMove;
+    private _onPointerUp;
+    /**
+     * The keys `GtkScale` binds (gtkscale.c:745-800), and none of them is orientation-bound:
+     * the C says so in its own comment, because a blind user should not have to know which
+     * way the slider runs.
+     */
+    private _onKeyDown;
+    private _render;
+}
+export {};