@gjsify/adwaita-web 0.47.0 → 0.48.0

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

@@ -1,3 +1,4 @@
+import type { AdwComboOption, AdwListModelInput } from '@gjsify/adwaita-core';
 export declare class AdwComboRow extends HTMLElement {
     private _select;
     private _valueEl;
@@ -7,10 +8,65 @@ export declare class AdwComboRow extends HTMLElement {
     private readonly _state;
     private _initialized;
     static get observedAttributes(): string[];
+    /** The list model (`Adw.ComboRow:model`). Setting it splices the <select> and clamps the selection. */
+    get model(): AdwComboOption[];
+    set model(value: AdwListModelInput);
+    /**
+     * The selected index (Adw.ComboRow:selected). PERMISSIVE: an index past the end is
+     * accepted and reads back with an empty {@link selectedValue}, mirroring the `guint`
+     * property that takes any position — where `<gtk-drop-down>` rejects the same set, as
+     * its own docs promise. `ComboState.hasIndex` owns the bounds and records why the
+     * POLICY is each renderer's; `COMBO_SELECTION_VECTORS` drives both answers.
+     */
     get selected(): number;
     set selected(value: number);
+    /**
+     * The selected option's `value`, or '' when nothing is selected (Adw.ComboRow:selected-item).
+     *
+     * Assigning routes through `selected`, i.e. through the attribute, so a set BY VALUE
+     * and a set BY INDEX leave the element in the same observable state — including the
+     * reflected `selected=` a consumer or a stylesheet may be reading. An unknown value is
+     * a no-op, as on `<gtk-drop-down>`.
+     */
+    get selectedValue(): string;
+    set selectedValue(value: string);
+    /**
+     * The selected option descriptor, or `null` (Adw.ComboRow:selected-item).
+     *
+     * Read-only, as the GObject property is. `null` and not a blank descriptor: the
+     * sentinel and an index past the end both address no option, and inventing an empty
+     * one would make "nothing is selected" indistinguishable from an option with no text.
+     */
+    get selectedItem(): AdwComboOption | null;
     connectedCallback(): void;
     attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+    /**
+     * Build one `<option>` for a model item.
+     *
+     * ITS `value` IS THE MODEL'S value, not the position. The position used to be written
+     * there with a comment defending it, and nothing in this package or its consumers ever
+     * read it back — while it made every insertion renumber the whole tail, which is the
+     * one thing a splice exists to avoid. The element still addresses its model by
+     * POSITION (`selectedIndex`); what the attribute now carries is the descriptor's own
+     * value, which is also what a form submission would have wanted.
+     */
+    private _createOption;
+    /**
+     * Apply one `items-changed` to the `<option>` list — remove `removed` nodes at
+     * `position`, insert `added` fresh ones there, touch nothing else.
+     *
+     * A no-op before `connectedCallback` has built the DOM, which is what lets `model` be
+     * assigned to a detached element: the state keeps the model and the connect path
+     * renders it whole.
+     */
+    private _applyItemsChanged;
+    /**
+     * Build the whole `<option>` list — the CONNECT path only, where there is no previous
+     * list to splice against.
+     *
+     * Every later assignment goes through {@link _applyItemsChanged}.
+     */
+    private _renderOptions;
     /**
      * `model_changed`: one option or none is not a choice, so the arrow goes and the row
      * stops being activatable.

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

@@ -1,13 +1,23 @@
+import type { AdwAdjustment, AdwAdjustmentInput } from '@gjsify/adwaita-core';
 export declare class AdwSpinRow extends HTMLElement {
     private _input;
     private _titleEl;
     private _subtitleEl;
-    /** The headless value/min/max/step adjustment with clamping (ADR 0004). */
+    /** The headless adjustment: the range, the clamp and the two signals (ADR 0004, ADR 0047). */
     private readonly _state;
     private _initialized;
     static get observedAttributes(): string[];
     get value(): number;
     set value(v: number);
+    /**
+     * The numeric range — `Adw.SpinRow:adjustment`, as the portable value.
+     *
+     * Reads back whole; writes MERGE, so `el.adjustment = { upper: 20 }` moves one bound
+     * and leaves the value where it is. A string is read as the JSON the attribute carries,
+     * so the property and the attribute mean the same thing.
+     */
+    get adjustment(): AdwAdjustment;
+    set adjustment(v: AdwAdjustmentInput | string);
     connectedCallback(): void;
     attributeChangedCallback(name: string, _old: string | null, val: string | null): void;
     private _renderText;

package/lib/types/elements/adw-split-button.d.ts

@@ -1,4 +1,4 @@
-import type { AdwMenuEntry, SplitButtonDirection } from '@gjsify/adwaita-core';
+import type { AdwMenuActions, AdwMenuInput, AdwMenuModel, SplitButtonDirection } from '@gjsify/adwaita-core';
 import './gtk-popover.js';
 export declare class AdwSplitButton extends HTMLElement {
     private readonly _state;
@@ -6,6 +6,8 @@ export declare class AdwSplitButton extends HTMLElement {
     private _dropdownEl;
     private _arrowEl;
     private _menuEl;
+    private _menuView;
+    private _actions;
     /** Inline text content, captured before we take over the subtree. */
     private _inlineLabel;
     /** Last `open` value reflected as `notify::active`, so the event fires once per flip. */
@@ -21,8 +23,46 @@ export declare class AdwSplitButton extends HTMLElement {
     /** The symbolic icon name, or `null` when the action half shows a label or nothing. */
     get iconName(): string | null;
     set iconName(value: string);
-    get menuItems(): readonly AdwMenuEntry[];
-    set menuItems(value: readonly AdwMenuEntry[]);
+    /** The menu, normalised (ADR 0042). Empty when the dropdown has none. */
+    get menuModel(): AdwMenuModel;
+    /**
+     * Set the menu from anything the portable model accepts — a bare `string[]`, item
+     * descriptors, sections, submenus.
+     *
+     * The REFUSAL is here rather than at render time: a `custom` item names an
+     * application widget this surface cannot host, and discovering that as a blank row
+     * three interactions later is what {@link assertMenuRenderable} exists to prevent.
+     */
+    set menuModel(value: AdwMenuInput);
+    /**
+     * Normalise, REFUSE, store — the one door every menu comes through.
+     *
+     * The property setter is not the only way a menu arrives: an attribute is, and the
+     * first cut refused only the setter, so a `custom` item written in markup drew
+     * exactly the row `assertMenuRenderable` exists to prevent — one that reads like a
+     * command and does nothing.
+     *
+     * THE TWO DOORS REFUSE DIFFERENTLY, and the difference is which side can hear it.
+     * A property assignment is a CALL, so it throws and the caller can catch. An
+     * attribute is MARKUP, parsed by the browser: a throw from `connectedCallback` is
+     * not delivered to whoever appended the element, it is reported as an uncaught
+     * page error — measured, it broke `adwaita-upgrade-order.spec.ts`, which counts
+     * exactly those. Nobody can handle it and everybody else pays for it. So the
+     * attribute path REFUSES THE MENU (no menu, and a menu-less dropdown is
+     * insensitive, which is visible) and says why on `console.error`.
+     *
+     * A REFUSAL AND A TYPO ARE STILL DIFFERENT THINGS. `parseMenuModel` is total
+     * because malformed JSON is an author slip and must not stop the element
+     * upgrading; `custom` is well-formed, deliberate, and unhonourable here.
+     */
+    private _acceptMenu;
+    /**
+     * What the action group publishes about the actions this menu names — the portable
+     * stand-in for a `GActionGroup`, and the ONLY place a menu's enabled/checked state
+     * can come from (ADR 0042). Setting it re-renders the rows.
+     */
+    get actions(): AdwMenuActions | null;
+    set actions(value: AdwMenuActions | null);
     /** The dropdown tooltip as set — `''` while unset. */
     get dropdownTooltip(): string;
     set dropdownTooltip(value: string);

package/lib/types/elements/gtk-drop-down.d.ts

@@ -1,5 +1,5 @@
 import './gtk-popover.js';
-import type { AdwComboOption, AdwComboOptionInput } from '@gjsify/adwaita-core';
+import type { AdwComboOption, AdwListModelInput } from '@gjsify/adwaita-core';
 /**
  * A dropdown option — `value` is the stable id, `label` the shown text. An alias of
  * core's {@link AdwComboOption}, since the drop-down and the combo row are the same
@@ -19,11 +19,9 @@ export declare class GtkDropDown extends HTMLElement {
     private _typeAheadBuffer;
     private _typeAheadTimer;
     static get observedAttributes(): string[];
-    /** The options list. Setting it rebuilds the popover and clamps the selection. */
-    get options(): GtkDropDownOption[];
-    set options(value: ReadonlyArray<AdwComboOptionInput>);
-    get items(): GtkDropDownOption[];
-    set items(value: ReadonlyArray<AdwComboOptionInput>);
+    /** The list model (`Gtk.DropDown:model`). Setting it splices the popover and clamps the selection. */
+    get model(): GtkDropDownOption[];
+    set model(value: AdwListModelInput);
     /** The selected index. Out-of-range values are ignored (Gtk.DropDown:selected). */
     get selected(): number;
     set selected(value: number);
@@ -36,7 +34,6 @@ export declare class GtkDropDown extends HTMLElement {
     get active(): boolean;
     connectedCallback(): void;
     attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
-    private _parseOptionsAttr;
     private _selectIndex;
     private _onPopoverToggled;
     private _onButtonKeyDown;
@@ -49,4 +46,22 @@ export declare class GtkDropDown extends HTMLElement {
     private _updateLabel;
     private _updateSelectedStates;
     private _renderPopover;
+    /**
+     * One row button.
+     *
+     * The click handler reads the row's CURRENT position out of `_itemButtons` instead of
+     * closing over the index it was built at. Under a full rebuild the two were always
+     * equal, which is why the closure survived; under a splice they are not, and a row
+     * that shifted by one would have selected its neighbour.
+     */
+    private _createItem;
+    /**
+     * Apply one `items-changed` to the row list — remove `removed` buttons at `position`,
+     * insert `added` fresh ones there, leave every other row (and its focus) standing.
+     *
+     * It owns everything a model replacement has to refresh, so the property door and the
+     * attribute door share one update path: the button label, the per-row selected state,
+     * and popping the popover down when the model empties under it.
+     */
+    private _applyItemsChanged;
 }

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

@@ -1,36 +1,53 @@
-import type { AdwMenuEntry, SplitButtonDirection } from '@gjsify/adwaita-core';
+import type { AdwMenuActions, AdwMenuInput, AdwMenuModel, SplitButtonDirection } from '@gjsify/adwaita-core';
 import './gtk-popover.js';
-/**
- * A menu entry — `@gjsify/adwaita-core`'s {@link AdwMenuEntry} under the name both
- * renderers export it as.
- *
- * IT KEEPS THE `Adw` PREFIX WHILE THE ELEMENT ABOVE IT DOES NOT, and the reason is not
- * "the name it has always used" — ADR 0034 clause 1 just moved every name in this file
- * that had one. It is that this is not a WIDGET name: clause 1 is about the tag, and
- * this is the descriptor a consumer writes menu entries with. `@gjsify/adwaita-
- * nativescript` exports `AdwMenuItem` for the same type, and that port deliberately
- * keeps `Adw` throughout, so renaming this half would give one object two spellings —
- * which is the thing the ADR is removing, not applying. (`GtkDropDownOption` next door
- * DID move: its NativeScript twin exports no such name, so there was nothing to split.)
- *
- * It used to be a SECOND declaration of the same shape, and the NativeScript menu
- * button declared a THIRD that was missing `icon` entirely. One type, so a consumer
- * writing menu entries writes the same object for either renderer.
- */
-export type AdwMenuItem = AdwMenuEntry;
 export declare class GtkMenuButton extends HTMLElement {
     private _buttonEl;
     private _popoverEl;
-    private _items;
+    private _model;
+    private _actions;
     private _menuTitle;
     private _initialized;
-    private _itemButtons;
+    private _menuView;
     static get observedAttributes(): string[];
     /** Whether the popover menu is currently open. */
     get active(): boolean;
-    /** The menu entries. Setting rebuilds the popover. */
-    get menuItems(): AdwMenuItem[];
-    set menuItems(value: AdwMenuItem[]);
+    /** The menu, normalised (ADR 0042). Setting rebuilds the popover. */
+    get menuModel(): AdwMenuModel;
+    /**
+     * Set the menu from anything the portable model accepts. Refused HERE, at the
+     * assignment, for a `custom` item this surface cannot host — see the split button's
+     * note on the same setter.
+     */
+    set menuModel(value: AdwMenuInput);
+    /**
+     * Normalise, REFUSE, store — the one door every menu comes through.
+     *
+     * The property setter is not the only way a menu arrives: an attribute is, and the
+     * first cut refused only the setter, so a `custom` item written in markup drew
+     * exactly the row `assertMenuRenderable` exists to prevent — one that reads like a
+     * command and does nothing.
+     *
+     * THE TWO DOORS REFUSE DIFFERENTLY, and the difference is which side can hear it.
+     * A property assignment is a CALL, so it throws and the caller can catch. An
+     * attribute is MARKUP, parsed by the browser: a throw from `connectedCallback` is
+     * not delivered to whoever appended the element, it is reported as an uncaught
+     * page error — measured, it broke `adwaita-upgrade-order.spec.ts`, which counts
+     * exactly those. Nobody can handle it and everybody else pays for it. So the
+     * attribute path REFUSES THE MENU (no menu, and a menu-less dropdown is
+     * insensitive, which is visible) and says why on `console.error`.
+     *
+     * A REFUSAL AND A TYPO ARE STILL DIFFERENT THINGS. `parseMenuModel` is total
+     * because malformed JSON is an author slip and must not stop the element
+     * upgrading; `custom` is well-formed, deliberate, and unhonourable here.
+     */
+    private _acceptMenu;
+    /**
+     * What the action group publishes about the actions this menu names — the portable
+     * stand-in for a `GActionGroup`, and the only source of a menu's enabled/checked
+     * state (ADR 0042).
+     */
+    get actions(): AdwMenuActions | null;
+    set actions(value: AdwMenuActions | null);
     /** The optional popover heading. */
     get menuTitle(): string;
     set menuTitle(value: string);
@@ -40,12 +57,12 @@ export declare class GtkMenuButton extends HTMLElement {
     connectedCallback(): void;
     attributeChangedCallback(name: string): void;
     /**
-     * The `menu` attribute, through the core parser the split button already used.
+     * The `menu-model` attribute, through the core parser both elements share.
      *
      * The copy this replaces was weaker in a way markup can reach: it kept `id` and
      * `icon` WHATEVER their runtime type, so `{"label":"Open","id":7}` produced an
      * entry whose `id` is a number in a field typed `string` — and `id` is what the
-     * activation event reports. The core parser keeps only string-typed extras.
+     * activation event reports. The core parser keeps only string-typed attributes.
      */
     private _parseMenuAttr;
     private _onPopoverToggled;

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

@@ -26,7 +26,20 @@ export declare class GtkPopover extends HTMLElement {
     get align(): GtkPopoverAlign;
     set align(value: GtkPopoverAlign);
     get popoverRole(): GtkPopoverRole;
-    /** The navigable rows, in DOM order. Hidden rows are skipped — a filtered list navigates what it shows. */
+    /**
+     * The navigable rows, in DOM order.
+     *
+     * HIDDEN rows are skipped — a filtered list navigates what it shows. DISABLED rows
+     * are skipped for a harder reason: a disabled `<button>` cannot take focus at all, so
+     * `items[index].focus()` is a NO-OP and the arrow key reads as dead. Keeping one in
+     * the walk is the same defect a roving tabindex with no keys behind it has, one row
+     * wide — measured on a menu whose action group reported an action disabled
+     * (ADR 0042): ArrowDown onto it left `document.activeElement` where it was.
+     *
+     * GTK skips them for the same reason and says so in the general rule rather than in
+     * the menu: `gtk_widget_focus_move` walks only widgets `gtk_widget_get_can_focus`
+     * accepts, and an insensitive widget is not one.
+     */
     get items(): HTMLElement[];
     /** Show the popover — `gtk_popover_popup()`. */
     popup(): void;

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

@@ -0,0 +1,99 @@
+import type { AdwMenuActions, AdwMenuModel, AdwMenuPath } from '@gjsify/adwaita-core';
+import type { GtkPopover } from './gtk-popover.js';
+/**
+ * Called when the reader chooses an item, with the path that addresses it in the WHOLE
+ * model — never the item itself. The element resolves it through its own state, which is
+ * what dismisses the menu, so handing over a second copy of the item would give the
+ * activation two sources.
+ */
+export type PopoverMenuActivate = (path: AdwMenuPath) => void;
+/**
+ * The rows of one popover, and which page is showing.
+ *
+ * A view rather than a function because a submenu is a NAVIGATION: the open page has to
+ * survive between renders, and it has to reset when the popover closes — a menu that
+ * reopens three levels deep is a menu the reader cannot get out of.
+ */
+export declare class PopoverMenuView {
+    private readonly surface;
+    /** Class prefix for the element's own hooks — `adw-menu-button`, `adw-split-button-menu`. */
+    private readonly prefix;
+    private readonly onActivate;
+    private _model;
+    private _actions;
+    private _title;
+    /** The submenu whose items are showing; `[]` is the root page. */
+    private _page;
+    /** The rows that OPEN a page — what ArrowRight acts on. Rebuilt by every render. */
+    private _openers;
+    /** The row that LEAVES a page — what ArrowLeft acts on. */
+    private _backRow;
+    /** The canonical text of the model showing, so an unchanged re-render keeps the page. */
+    private _key;
+    private _rows;
+    constructor(surface: GtkPopover, 
+    /** Class prefix for the element's own hooks — `adw-menu-button`, `adw-split-button-menu`. */
+    prefix: string, onActivate: PopoverMenuActivate);
+    /**
+     * LEFT and RIGHT, which change the page. Every other key belongs to `<gtk-popover>`.
+     *
+     * The act is the row's own CLICK, not a second copy of what opening a page means:
+     * `switch_menu` is one behaviour in GTK too, reached by a pointer and by a direction
+     * alike. `preventDefault` before it, for the reason the popover's own Enter handler
+     * gives — a focused `<button>` would otherwise also activate natively.
+     */
+    private _onKeyDown;
+    /** Every row of the open page, in order — including the ones no key can reach. */
+    get rows(): readonly HTMLButtonElement[];
+    /**
+     * The rows a key can actually REACH, which is the only list worth focusing into.
+     *
+     * A hidden row is not rendered and a DISABLED one cannot take focus, so
+     * `element.focus()` on either is a silent no-op — and a no-op after `render()` has
+     * replaced the row that had focus leaves `document.activeElement` on `<body>`,
+     * OUTSIDE an open popover. Measured under real keys: Tab then walked to the control
+     * BEHIND the popup and every arrow was dead, because both keydown listeners are
+     * element-scoped and the event no longer fired inside either. Escape was the only
+     * way out.
+     *
+     * The predicate lived in the two ELEMENTS (their open path) and not in the two page
+     * changes here, which is how it came to be applied in two places out of four. One
+     * list, so there is no fourth place to forget.
+     */
+    get focusableRows(): readonly HTMLButtonElement[];
+    /**
+     * Put focus on a page, counting only rows a key can reach.
+     *
+     * `skip` is how many reachable rows to pass — 1 when ENTERING a submenu, because the
+     * back row is reachable and the reader was going to the first item past it. The
+     * fallback to the first reachable row is what covers a submenu whose every item is
+     * disabled: focus lands on the back row, which is always reachable, and the reader
+     * can still leave with Left, Enter or Escape.
+     */
+    private focusPage;
+    /**
+     * Named for the value it takes, and NOT `setModel` — the portable LIST model gave
+     * `ComboState` a `setModel` (ADR 0046), and two methods called `setModel` over two
+     * unrelated values on one surface is the collision the vocabulary work exists to
+     * remove. It also un-blinds `check-adwaita-collection-reactivity`, which resolves a
+     * collection call by the setter's name.
+     */
+    setMenuModel(model: AdwMenuModel): void;
+    setActions(actions: AdwMenuActions | null): void;
+    setTitle(title: string): void;
+    /** Return to the root page — called when the popover closes. */
+    reset(): void;
+    /** The items of the page currently showing. */
+    private currentItems;
+    /** Rebuild the surface's children from the model. */
+    render(): void;
+    /** The label of the section at `path`, or `null` when it is not a labelled section. */
+    private sectionHeading;
+    private heading;
+    private separator;
+    /** A row, with the class that makes `<gtk-popover>` treat it as navigable. */
+    private baseRow;
+    private backRow;
+    private submenuRow;
+    private itemRow;
+}

package/lib/types/index.d.ts

@@ -19,6 +19,6 @@ export { AdwBottomSheetContent, AdwBottomSheetSheet } from './elements/adw-botto
 export { AdwAlertResponse } from './elements/adw-alert-dialog.js';
 export type { GtkPopoverAlign, GtkPopoverPosition, GtkPopoverRole } from './elements/gtk-popover.js';
 export type { AdwViewStackPageInfo } from './elements/adw-view-stack.js';
-export type { AdwMenuItem } from './elements/gtk-menu-button.js';
+export type { AdwMenuActions, AdwMenuEntryInput, AdwMenuInput, AdwMenuItem, AdwMenuModel, AdwMenuNode, AdwMenuPath, AdwMenuSection, AdwMenuSubmenu, } from '@gjsify/adwaita-core';
 export type { GtkDropDownOption } from './elements/gtk-drop-down.js';
 export type { AdwDialogPresentationMode } from './elements/adw-dialog.js';