@gjsify/adwaita-web 0.64.12-next.280 → 0.64.12

package/src/gtk-drop-down.spec.ts

@@ -8,7 +8,9 @@
 // composes the same `ComboState` and drives the same table from its own DOM
 // (`adw-row-state.spec.ts`) — it could not while two of its four step ops had no DOM
 // spelling there, its model arriving through an attribute at connect time only (#1525).
-// The two are worth driving separately because they part on ONE row, below.
+// The two used to part on ONE row — `an index past the end`, which this element rejected
+// and the row accepted — and that carve-out is GONE: ADR 0122 § 4 measured libadwaita,
+// found the rejection right, and the row adopted it. Both selectors now drive every row.
 import { describe, it, expect } from '@gjsify/unit';
 
 import {
@@ -17,9 +19,13 @@ import {
     LIST_MODEL_OWNERSHIP_VECTORS,
     LIST_NORMALIZE_VECTORS,
     LIST_PARSE_VECTORS,
+    applyListMutation,
     applyListReadback,
+    listModelForInput,
 } from '@gjsify/adwaita-core/conformance';
-import type { ComboSelectionStep, ComboSelectionVector } from '@gjsify/adwaita-core/conformance';
+import type { ComboSelectionStep } from '@gjsify/adwaita-core/conformance';
+import { GjsifyOptionList } from '@gjsify/adwaita-core';
+import type { AdwComboOptionInput } from '@gjsify/adwaita-core';
 
 import type { GtkDropDown } from './elements/gtk-drop-down.js';
 
@@ -29,6 +35,20 @@ function makeDropDown(): GtkDropDown {
     return el;
 }
 
+/**
+ * Assign a model built out of an authored array.
+ *
+ * The array itself no longer goes to the property — ADR 0122 § 4 narrowed `model` to a real
+ * `Gio.ListModel` — so every test below that is about something OTHER than the door says so
+ * in one place. The tests that ARE about the door (`LIST_NORMALIZE_VECTORS` and the array
+ * refusal in `gtk-value-doors.spec.ts`) write to `model` directly.
+ */
+function setModel(dd: GtkDropDown, options: readonly AdwComboOptionInput[]): GjsifyOptionList {
+    const list = GjsifyOptionList.new(options);
+    dd.model = list;
+    return list;
+}
+
 /** The text the closed button shows — the rendered `selectedLabel`. */
 function labelText(dd: GtkDropDown): string {
     return dd.querySelector('.adw-drop-down-label')?.textContent ?? '';
@@ -42,12 +62,21 @@ function openChooser(dd: GtkDropDown): void {
 /**
  * Replay one vector step against the real element — property sets for the
  * programmatic ops, a popover gesture for the interactive one.
+ *
+ * Every `setModel` builds a FRESH list, which is what makes `setModelAgain` — assigning the
+ * identity the element already holds — a distinct step rather than a repeat of the one above
+ * it.
  */
 function applyStep(dd: GtkDropDown, step: ComboSelectionStep): void {
     switch (step.op) {
         case 'setModel':
-            dd.model = step.model;
+            setModel(dd, [...step.model]);
+            return;
+        case 'setModelAgain': {
+            const held = dd.model;
+            dd.model = held;
             return;
+        }
         case 'setSelectedIndex':
             dd.selected = step.index;
             return;
@@ -67,23 +96,6 @@ function applyStep(dd: GtkDropDown, step: ComboSelectionStep): void {
     }
 }
 
-/**
- * The ONE row this element answers differently, on purpose: its published `selected`
- * contract REJECTS an out-of-range set (`_selectIndex` gates on `ComboState.hasIndex`)
- * where the core state accepts it and reports an empty value — the split
- * `ComboState.hasIndex`'s doc records and `<adw-combo-row>` takes the other side of. The
- * row is still driven below, against the element's answer, so neither policy can change
- * silently.
- */
-const DROP_DOWN_REJECTS = 'an index past the end';
-
-/** The named vector — a hard failure if the table renamed it out from under the carve-out. */
-function vectorNamed(name: string): ComboSelectionVector {
-    const vector = COMBO_SELECTION_VECTORS.find((v) => v.name === name);
-    if (!vector) throw new Error(`COMBO_SELECTION_VECTORS has no row "${name}" — this spec's carve-out is stale`);
-    return vector;
-}
-
 /** Mount a drop-down and record every `change` detail it dispatches. */
 function mountRecording(): { dd: GtkDropDown; changes: unknown[] } {
     const dd = makeDropDown();
@@ -95,8 +107,6 @@ function mountRecording(): { dd: GtkDropDown; changes: unknown[] } {
 export const GtkDropDownTest = async () => {
     await describe('gtk-drop-down selection (libadwaita conformance vectors)', async () => {
         for (const vector of COMBO_SELECTION_VECTORS) {
-            if (vector.name === DROP_DOWN_REJECTS) continue;
-
             await it(`${vector.name} — ${vector.rule}`, async () => {
                 const { dd, changes } = mountRecording();
                 for (const step of vector.steps) applyStep(dd, step);
@@ -115,43 +125,24 @@ export const GtkDropDownTest = async () => {
                 dd.remove();
             });
         }
-
-        await it(`${DROP_DOWN_REJECTS} — rejected here: the element's published contract, not the state's`, async () => {
-            const vector = vectorNamed(DROP_DOWN_REJECTS);
-            const { dd, changes } = mountRecording();
-
-            for (const step of vector.steps.slice(0, -1)) applyStep(dd, step);
-            const before = { selected: dd.selected, value: dd.selectedValue, label: labelText(dd) };
-            // The out-of-range set itself, which the core state would accept and report
-            // as nothing-to-draw (`value`/`label` both empty below).
-            expect(vector.value).toBe('');
-            expect(vector.label).toBe('');
-            applyStep(dd, vector.steps[vector.steps.length - 1]);
-
-            // The element refused it: the selection did not move, and a refusal
-            // is not a change, so nothing was dispatched either.
-            expect({ selected: dd.selected, value: dd.selectedValue, label: labelText(dd) }).toStrictEqual(before);
-            expect(changes).toStrictEqual([]);
-            dd.remove();
-        });
     });
 
     await describe('gtk-drop-down model', async () => {
         await it('accepts a string[] (value === label)', async () => {
             const dd = makeDropDown();
-            dd.model = ['One', 'Two', 'Three'];
-            expect(dd.model.length).toBe(3);
-            expect(dd.model[0]).toStrictEqual({ value: 'One', label: 'One' });
+            setModel(dd, ['One', 'Two', 'Three']);
+            expect(dd.options.length).toBe(3);
+            expect(dd.options[0]).toStrictEqual({ value: 'One', label: 'One' });
             expect(dd.querySelector('.adw-drop-down-label')?.textContent).toBe('One');
             dd.remove();
         });
 
         await it('accepts {value,label}[] and shows the selected label', async () => {
             const dd = makeDropDown();
-            dd.model = [
+            setModel(dd, [
                 { value: 'a', label: 'Apple' },
                 { value: 'b', label: 'Banana' },
-            ];
+            ]);
             dd.selected = 1;
             expect(dd.querySelector('.adw-drop-down-label')?.textContent).toBe('Banana');
             expect(dd.selectedValue).toBe('b');
@@ -163,7 +154,7 @@ export const GtkDropDownTest = async () => {
             dd.setAttribute('model', '[{"value":"x","label":"Ex"},{"value":"y","label":"Why"}]');
             dd.setAttribute('selected', '1');
             document.body.appendChild(dd);
-            expect(dd.model.length).toBe(2);
+            expect(dd.options.length).toBe(2);
             expect(dd.selected).toBe(1);
             expect(dd.selectedValue).toBe('y');
             dd.remove();
@@ -171,7 +162,7 @@ export const GtkDropDownTest = async () => {
 
         await it('renders one popover item per option', async () => {
             const dd = makeDropDown();
-            dd.model = ['a', 'b', 'c'];
+            setModel(dd, ['a', 'b', 'c']);
             expect(dd.querySelectorAll('.adw-drop-down-item').length).toBe(3);
             dd.remove();
         });
@@ -179,8 +170,10 @@ export const GtkDropDownTest = async () => {
         for (const vector of LIST_NORMALIZE_VECTORS) {
             await it(`normalize — ${vector.rule}`, async () => {
                 const dd = makeDropDown();
-                dd.model = vector.input;
-                expect(dd.model).toStrictEqual([...vector.model]);
+                // `listModelForInput` is the table's own answer to which door a row reaches
+                // through now that `model` takes no array (ADR 0122 § 4).
+                dd.model = listModelForInput(vector.input);
+                expect(dd.options).toStrictEqual([...vector.model]);
                 expect(
                     [...dd.querySelectorAll('.adw-drop-down-item-label')].map((label) => label.textContent),
                 ).toStrictEqual(vector.model.map((item) => item.label));
@@ -198,21 +191,26 @@ export const GtkDropDownTest = async () => {
                 // Set AFTER connect, so the attribute reaches the callback rather than the
                 // seeding path: a total parser has to be total on the live door too.
                 dd.setAttribute('model', vector.attribute);
-                expect(dd.model).toStrictEqual([...vector.model]);
+                expect(dd.options).toStrictEqual([...vector.model]);
                 dd.remove();
             });
         }
 
-        // The half no pure test reaches: a replaced model must SPLICE the row buttons, not
+        // The half no pure test reaches: a markup update must SPLICE the row buttons, not
         // rebuild them. Identity is what says which happened — and it is what a user feels,
         // because a rebuilt row loses its focus and the popover its scroll position.
+        //
+        // Driven through the ATTRIBUTE, which is the door that still computes a splice: it
+        // reconciles the element's own authored list (ADR 0122 amendment A4) and so keeps its
+        // identity. A `model` PROPERTY write cannot answer these rows any more — a different
+        // list is a replacement, and a replacement carries nothing over by definition.
         for (const vector of LIST_ITEMS_CHANGED_VECTORS) {
             await it(`items-changed — ${vector.rule}`, async () => {
                 const dd = makeDropDown();
-                dd.model = vector.previous;
+                dd.setAttribute('model', JSON.stringify(vector.previous));
                 const before = [...dd.querySelectorAll('.adw-drop-down-item')];
 
-                dd.model = vector.next;
+                dd.setAttribute('model', JSON.stringify(vector.next));
 
                 const after = [...dd.querySelectorAll('.adw-drop-down-item')];
                 expect(after.map((item) => item.querySelector('.adw-drop-down-item-label')?.textContent)).toStrictEqual(
@@ -223,19 +221,23 @@ export const GtkDropDownTest = async () => {
             });
         }
 
-        // WHO OWNS the array `model` hands back — the row buttons are what shows it, for
-        // the reason `adw-row-state.spec.ts` gives on the same table.
+        // WHO OWNS the options either side of the model, and what the model's own API moves
+        // — the row buttons are what shows it, for the reason `adw-row-state.spec.ts` gives
+        // on the same table.
         for (const vector of LIST_MODEL_OWNERSHIP_VECTORS) {
             await it(`ownership — ${vector.rule}`, async () => {
                 const dd = makeDropDown();
                 const input = vector.initial.map((item) => ({ ...item }));
-                dd.model = input;
+                const list = setModel(dd, input);
                 const before = [...dd.querySelectorAll('.adw-drop-down-item')];
 
-                const mutated = applyListReadback(vector.source === 'input' ? input : dd.model, vector.op);
-                if (vector.assign) dd.model = mutated;
+                if (vector.source === 'model') applyListMutation(list, vector.op);
+                else applyListReadback(vector.source === 'input' ? input : dd.options, vector.op);
 
-                expect(dd.model).toStrictEqual([...vector.model]);
+                expect(dd.options).toStrictEqual([...vector.model]);
+                // None of these ops is a replacement, so the element must still be pointing
+                // at the list it was handed.
+                expect(dd.model).toBe(list);
                 const after = [...dd.querySelectorAll('.adw-drop-down-item')];
                 expect(after.map((item) => item.querySelector('.adw-drop-down-item-label')?.textContent)).toStrictEqual(
                     vector.model.map((item) => item.label),
@@ -250,9 +252,10 @@ export const GtkDropDownTest = async () => {
         // not, so the handler asks the list where the row is now.
         await it('a row that a splice shifted still selects itself', async () => {
             const dd = makeDropDown();
-            dd.model = ['b', 'c'];
+            // Through the attribute door, the one that splices — see the items-changed loop.
+            dd.setAttribute('model', '["b","c"]');
             const rowForB = dd.querySelectorAll('.adw-drop-down-item')[0] as HTMLButtonElement;
-            dd.model = ['a', 'b', 'c'];
+            dd.setAttribute('model', '["a","b","c"]');
             expect(dd.querySelectorAll('.adw-drop-down-item')[1]).toBe(rowForB);
 
             (dd.querySelector('.adw-drop-down-button') as HTMLButtonElement).click();
@@ -265,11 +268,11 @@ export const GtkDropDownTest = async () => {
     await describe('gtk-drop-down selected ↔ value sync', async () => {
         await it('selectedValue setter finds the index by value', async () => {
             const dd = makeDropDown();
-            dd.model = [
+            setModel(dd, [
                 { value: 'r', label: 'Red' },
                 { value: 'g', label: 'Green' },
                 { value: 'b', label: 'Blue' },
-            ];
+            ]);
             dd.selectedValue = 'b';
             expect(dd.selected).toBe(2);
             expect(dd.querySelector('.adw-drop-down-label')?.textContent).toBe('Blue');
@@ -278,7 +281,7 @@ export const GtkDropDownTest = async () => {
 
         await it('get_selected / set_selected are the GTK spelling of `selected`', async () => {
             const dd = makeDropDown();
-            dd.model = ['a', 'b', 'c'];
+            setModel(dd, ['a', 'b', 'c']);
             (dd as unknown as { set_selected(n: number): void }).set_selected(2);
             expect(dd.selected).toBe(2);
             expect((dd as unknown as { get_selected(): number }).get_selected()).toBe(2);
@@ -289,7 +292,7 @@ export const GtkDropDownTest = async () => {
 
         await it('selected reflects to the attribute + marks the row', async () => {
             const dd = makeDropDown();
-            dd.model = ['a', 'b'];
+            setModel(dd, ['a', 'b']);
             dd.selected = 1;
             expect(dd.getAttribute('selected')).toBe('1');
             const items = dd.querySelectorAll('.adw-drop-down-item');
@@ -298,10 +301,23 @@ export const GtkDropDownTest = async () => {
             dd.remove();
         });
 
-        await it('selectedItem returns the descriptor', async () => {
+        // `selected-item` is the MODEL'S OWN item, by identity (ADR 0122 § 4) — not a
+        // `{ value, label }` descriptor, which is what this read used to hand back. The
+        // identity is the point: it is what every `selected-item` consumer compares.
+        await it('selectedItem is the model’s own item, by identity', async () => {
+            const dd = makeDropDown();
+            const list = setModel(dd, [{ value: 'k', label: 'Key' }]);
+            expect(dd.selectedItem).toBe(list.get_item(0));
+            expect((dd as unknown as { get_selected_item(): unknown }).get_selected_item()).toBe(list.get_item(0));
+            dd.remove();
+        });
+
+        await it('selectedItem is null with no model and with no selection', async () => {
             const dd = makeDropDown();
-            dd.model = [{ value: 'k', label: 'Key' }];
-            expect(dd.selectedItem).toStrictEqual({ value: 'k', label: 'Key' });
+            expect(dd.model).toBeNull();
+            expect(dd.selectedItem).toBeNull();
+            setModel(dd, []);
+            expect(dd.selectedItem).toBeNull();
             dd.remove();
         });
 
@@ -309,7 +325,7 @@ export const GtkDropDownTest = async () => {
             // The property setters can run BEFORE connectedCallback builds the DOM, where
             // _updateLabel would touch an undefined label element.
             const dd = document.createElement('gtk-drop-down') as GtkDropDown;
-            dd.model = ['a', 'b', 'c'];
+            setModel(dd, ['a', 'b', 'c']);
             dd.selected = 2;
             expect(dd.isConnected).toBe(false);
             document.body.appendChild(dd);
@@ -323,7 +339,7 @@ export const GtkDropDownTest = async () => {
     await describe('gtk-drop-down notify-on-change', async () => {
         await it('a programmatic set fires notify::selected but NOT change (DOM <select> semantics)', async () => {
             const dd = makeDropDown();
-            dd.model = ['a', 'b', 'c'];
+            setModel(dd, ['a', 'b', 'c']);
             let notifyCount = 0;
             let changeCount = 0;
             dd.addEventListener('notify::selected', () => notifyCount++);
@@ -346,7 +362,7 @@ export const GtkDropDownTest = async () => {
 
         await it('a popover item click selects, fires change + closes', async () => {
             const dd = makeDropDown();
-            dd.model = ['a', 'b', 'c'];
+            setModel(dd, ['a', 'b', 'c']);
             let change: unknown = null;
             dd.addEventListener('change', (e) => {
                 change = (e as CustomEvent).detail;
@@ -365,7 +381,7 @@ export const GtkDropDownTest = async () => {
     await describe('gtk-drop-down popover behaviour', async () => {
         await it('opens on button click and closes on outside pointerdown', async () => {
             const dd = makeDropDown();
-            dd.model = ['a', 'b'];
+            setModel(dd, ['a', 'b']);
             const button = dd.querySelector('.adw-drop-down-button') as HTMLButtonElement;
             const popover = dd.querySelector('.adw-drop-down-popover') as HTMLElement;
             expect(popover.hidden).toBe(true);
@@ -381,7 +397,7 @@ export const GtkDropDownTest = async () => {
 
         await it('a disabled dropdown does not open', async () => {
             const dd = makeDropDown();
-            dd.model = ['a', 'b'];
+            setModel(dd, ['a', 'b']);
             dd.setAttribute('disabled', '');
             (dd.querySelector('.adw-drop-down-button') as HTMLButtonElement).click();
             expect(dd.active).toBe(false);
@@ -392,7 +408,7 @@ export const GtkDropDownTest = async () => {
     await describe('gtk-drop-down search', async () => {
         await it('renders a search entry and filters the list', async () => {
             const dd = makeDropDown();
-            dd.model = ['Apple', 'Banana', 'Cherry'];
+            setModel(dd, ['Apple', 'Banana', 'Cherry']);
             dd.enableSearch = true;
             const search = dd.querySelector('.adw-drop-down-search') as HTMLInputElement;
             expect(search).toBeTruthy();

package/src/gtk-value-doors.spec.ts

@@ -1,16 +1,22 @@
 // `Gtk.StringList` and `Gtk.Adjustment` AT THE ELEMENT, held against the spelling they
 // replace.
 //
-// THE CLAIM UNDER TEST is backward compatibility, and it is the one claim a core-side spec
-// cannot make. `@gjsify/adwaita-core` proves the two classes reduce to the same value as
-// the array and the object literal; what a reader needs to know is that the ELEMENT cannot
-// tell them apart — that `el.model = ['Blue', 'Teal']` and
-// `el.model = new Gtk.StringList({ strings: ['Blue', 'Teal'] })` leave `<adw-combo-row>` in
-// the same state, down to the `<option>` nodes it renders, and likewise for the two
-// adjustment spellings on `<adw-spin-row>`. Four spellings, each asserted against what the
-// element shows.
+// THE CLAIM UNDER TEST is what each property's value IS at the ELEMENT, and it is the one
+// claim a core-side spec cannot make: `@gjsify/adwaita-core` proves what the two classes
+// hold, what a reader needs to know is what the element does with them — down to the
+// `<option>` nodes it renders.
 //
-// The NativeScript port asserts the same four at its own widget door
+// The two properties answer DIFFERENTLY, which is why both are here. `adjustment` is still a
+// convenience door: `el.adjustment = FONT_SIZE` and `el.adjustment = new Gtk.Adjustment(…)`
+// leave `<adw-spin-row>` in the same state, and the object literal is the shorthand. `model`
+// is not, since ADR 0122: it is an object property over `Gio.ListModel`, it holds the list BY
+// IDENTITY, and `el.model = ['Blue', 'Teal']` is a `TypeError` naming the type rather than a
+// shorthand for one. The array door it replaces is asserted here as the refusal it became —
+// this file is where a reader looking for `el.model = [...]` arrives, so this is where the
+// answer belongs. The `model` ATTRIBUTE is a separate, untouched door; `value-lists.spec.ts`
+// and `adw-row-state.spec.ts` hold that one.
+//
+// The NativeScript port asserts the same doors at its own widget seam
 // (`gtk-value-doors.spec.ts` there), so the two renderers cannot part on this without one
 // of them failing.
 //
@@ -43,24 +49,29 @@ function mount<T extends HTMLElement>(tag: string): T {
 
 /** Everything a `model` write leaves behind, the rendered options included. */
 const modelState = (el: AdwComboRow | GtkDropDown, options: string) =>
-    JSON.stringify({ model: el.model, selected: el.selected, value: el.selectedValue, options });
+    JSON.stringify({ options: el.options, selected: el.selected, value: el.selectedValue, painted: options });
 
 /** The option labels the row actually paints, which is what a reader sees. */
 const comboOptions = (el: HTMLElement) =>
     [...el.querySelectorAll('option, .adw-drop-down-item-label')].map((node) => node.textContent).join('|');
 
 export const GtkValueDoorsTest = async () => {
-    await describe('<adw-combo-row> takes a plain array and a Gtk.StringList alike', async () => {
-        await it('leaves the row in the same state, rendered options included', () => {
-            const array = mount<AdwComboRow>('adw-combo-row');
-            const list = mount<AdwComboRow>('adw-combo-row');
-            array.model = COLOURS;
-            list.model = new GtkStringList({ strings: COLOURS });
-            array.selected = 1;
-            list.selected = 1;
-
-            expect(modelState(list, comboOptions(list))).toBe(modelState(array, comboOptions(array)));
-            expect(list.selectedValue).toBe('Teal');
+    await describe('<adw-combo-row>.model takes a Gtk.StringList and refuses an array', async () => {
+        await it('holds the list by identity and paints what it holds', () => {
+            const list = new GtkStringList({ strings: COLOURS });
+            const row = mount<AdwComboRow>('adw-combo-row');
+            row.model = list;
+            row.selected = 1;
+
+            expect(row.model === list).toBe(true);
+            expect(modelState(row, comboOptions(row))).toBe(
+                JSON.stringify({
+                    options: COLOURS.map((colour) => ({ value: colour, label: colour })),
+                    selected: 1,
+                    value: 'Teal',
+                    painted: COLOURS.join('|'),
+                }),
+            );
         });
 
         await it('follows a list that was appended to before it was assigned', () => {
@@ -72,19 +83,46 @@ export const GtkValueDoorsTest = async () => {
 
             expect(row.selectedValue).toBe('Teal');
         });
+
+        await it('follows a list appended to WHILE the row holds it', () => {
+            const strings = new GtkStringList({ strings: ['Blue'] });
+            const row = mount<AdwComboRow>('adw-combo-row');
+            row.model = strings;
+            strings.append('Teal');
+            row.selected = 1;
+
+            expect(row.selectedValue).toBe('Teal');
+        });
+
+        // The array door this file used to assert, as the refusal it became: `model` is an
+        // object property over `Gio.ListModel`, so the message is the property's own.
+        await it('refuses a plain array by naming the type', () => {
+            const row = mount<AdwComboRow>('adw-combo-row');
+
+            expect(() => {
+                (row as unknown as { model: unknown }).model = COLOURS;
+            }).toThrow("Object is not a subclass of GObject_Object, it's a Array");
+        });
     });
 
-    await describe('<gtk-drop-down> takes a plain array and a Gtk.StringList alike', async () => {
-        await it('leaves the drop-down in the same state', () => {
-            const array = mount<GtkDropDown>('gtk-drop-down');
-            const list = mount<GtkDropDown>('gtk-drop-down');
-            array.model = COLOURS;
-            list.model = new GtkStringList({ strings: COLOURS });
-            array.selected = 2;
-            list.selected = 2;
-
-            expect(modelState(list, comboOptions(list))).toBe(modelState(array, comboOptions(array)));
-            expect(list.selectedValue).toBe('Green');
+    await describe('<gtk-drop-down>.model takes a Gtk.StringList and refuses an array', async () => {
+        await it('holds the list by identity and paints what it holds', () => {
+            const list = new GtkStringList({ strings: COLOURS });
+            const dropDown = mount<GtkDropDown>('gtk-drop-down');
+            dropDown.model = list;
+            dropDown.selected = 2;
+
+            expect(dropDown.model === list).toBe(true);
+            expect(dropDown.selectedValue).toBe('Green');
+            expect(comboOptions(dropDown)).toBe(COLOURS.join('|'));
+        });
+
+        await it('refuses a plain array by naming the type', () => {
+            const dropDown = mount<GtkDropDown>('gtk-drop-down');
+
+            expect(() => {
+                (dropDown as unknown as { model: unknown }).model = COLOURS;
+            }).toThrow("Object is not a subclass of GObject_Object, it's a Array");
         });
     });
 

package/src/namespace/gdk.ts

@@ -34,4 +34,5 @@ export const {
     KEY_Up,
     KEY_Right,
     KEY_Down,
+    KEY_Back,
 } = GDK_KEYS;

package/src/namespace/gio.ts

@@ -29,6 +29,9 @@ import { createAppInfo } from '@gjsify/adwaita-core';
 import { webPlatformHost } from '../platform-host.js';
 
 export { GioMenu as Menu, GioMenuItem as MenuItem } from '@gjsify/adwaita-core';
+// ADR 0122 § 2: the interface a `Gtk.StringList` implements and an `Implements: [Gio.ListModel]`
+// names. It is a token, not a class — the whole of the subset's interface support.
+export { ListModel } from '@gjsify/adwaita-core';
 export {
     GioFile as File,
     GioListStore as ListStore,

package/src/namespace/gtk.ts

@@ -11,14 +11,18 @@
 // which is what `<adw-radio>`'s own `why` in the ledger says. So the plain form takes the
 // GIR name and the grouped one keeps its flat export in `src/index.ts`.
 //
-// TWO MEMBERS HERE ARE NOT WIDGETS — `Gtk.Adjustment` and `Gtk.StringList`, the values an
-// `adjustment` and a `model` property take. ADR 0034 § Amendment 19 is what lets a
-// clause-2 namespace carry them, `CONSTRUCTIBLE_VALUES` in `scripts/value-types.mjs` is
-// where each one is declared, and the GIR answers for both in gtk-host's committed
-// `generated/value-types.mts`. They are re-exported from `@gjsify/adwaita-core`, which is
-// where the portable list and adjustment already live: the class IS that value wearing the
-// GIR spelling, so `model: ['a','b']` and `model: new Gtk.StringList({ strings: ['a','b'] })`
-// are the same write and nothing in this package had to learn a second input shape.
+// THREE MEMBERS HERE ARE NOT WIDGETS — `Gtk.Adjustment`, `Gtk.StringList` and the
+// `Gtk.StringObject` the list holds, the values an `adjustment` and a `model` property take.
+// ADR 0034 § Amendment 19 is what lets a clause-2 namespace carry them,
+// `CONSTRUCTIBLE_VALUES` in `scripts/value-types.mjs` is where each one is declared, and the
+// GIR answers for all three in gtk-host's committed `generated/value-types.mts`. They are
+// re-exported from `@gjsify/adwaita-core`, which is where the portable list and adjustment
+// already live.
+//
+// `Gtk.StringList` IS A LIST MODEL, NOT AN ARRAY (ADR 0122). The first version of it was an
+// `Array` subclass, which made `model: ['a','b']` and `model: new Gtk.StringList(…)` the same
+// write; it is now what GTK ships — `Implements: [Gio.ListModel]`, items that are
+// `Gtk.StringObject`s, read by `get_n_items` / `get_item` and never by `length` or `[0]`.
 
 export { GtkAdjustment as Adjustment } from '@gjsify/adwaita-core';
 // ADR 0100: the file dialog is no element either — `present`-less, it asks the driver
@@ -89,7 +93,7 @@ export { GtkStack as Stack } from '../elements/gtk-stack.js';
 export { GtkStackPage as StackPage } from '../elements/gtk-stack-page.js';
 export { GtkStackSidebar as StackSidebar } from '../elements/gtk-stack-sidebar.js';
 export { GtkStackSwitcher as StackSwitcher } from '../elements/gtk-stack-switcher.js';
-export { GtkStringList as StringList } from '@gjsify/adwaita-core';
+export { GtkStringList as StringList, GtkStringObject as StringObject } from '@gjsify/adwaita-core';
 export { GtkSwitch as Switch } from '../elements/gtk-switch.js';
 export { GtkText as Text } from '../elements/gtk-text.js';
 export { GtkTextView as TextView } from '../elements/gtk-text-view.js';