@gjsify/adwaita-core 0.35.0 → 0.37.0

package/lib/types/preferences.d.ts

@@ -1,67 +1,54 @@
 import { stripMnemonic } from './glib.js';
 /**
- * A caseless-compare normaliser, i.e. what `g_utf8_casefold` does for the C.
- *
- * Injected rather than hard-wired — the same seam style as `ToastScheduler` and
- * the avatar's measurement callback — because full Unicode case folding is a
- * DATA TABLE, not a language builtin, and a size-sensitive renderer may
- * legitimately want to trade the table away. Making it a parameter keeps that a
- * documented choice instead of an accident.
+ * A caseless-compare normaliser, i.e. what `g_utf8_casefold` does for the C. Injected
+ * rather than hard-wired because full Unicode case folding is a DATA TABLE, not a
+ * language builtin, and a size-sensitive renderer may legitimately trade the table away.
  */
 export type CaseFolder = (text: string) => string;
 /**
- * `g_utf8_casefold` (adw-preferences-dialog.c:101, :133) — Unicode FULL case
- * folding, i.e. `toLowerCase()` plus the mappings where a case fold and a
- * lowercase mapping disagree.
- *
- * This is the one place in the family where the obvious implementation ships
- * wrong behaviour in languages people actually use, invisibly to an ASCII test
- * suite. The three canaries, all verified against a real full-folding
- * implementation:
+ * `g_utf8_casefold` — Unicode FULL case folding, i.e. `toLowerCase()` plus the mappings
+ * where a case fold and a lowercase mapping disagree. The obvious implementation ships
+ * wrong behaviour in languages people actually use, invisibly to an ASCII test suite;
+ * the three canaries, verified against a real full-folding implementation:
  *
- * | input    | `toLowerCase()` | case fold  |
+ * | input | `toLowerCase()` | case fold |
  * |----------|-----------------|------------|
- * | `Straße` | `straße`        | `strasse`  |
- * | `ΟΔΟΣ`   | `οδος`          | `οδοσ`     |
- * | `file`    | `file`           | `file`     |
+ * | `Straße` | `straße` | `strasse` |
+ * | `ΟΔΟΣ` | `οδος` | `οδοσ` |
+ * | `file` | `file` | `file` |
  *
- * `normalize('NFKC').toLowerCase()` is NOT a substitute: it repairs the
+ * `normalize('NFKC').toLowerCase` is NOT a substitute: it repairs the
  * ligature, still misses `ß` and final sigma, and OVER-normalises `DŽ` (U+01C4)
  * to the two-character `dž` where a case fold gives the single character `dž`.
  */
 export declare const defaultCaseFolder: CaseFolder;
 /**
- * `g_markup_escape_text` — the escape `create_search_row_subtitle` puts a page
- * title through before it becomes a markup subtitle
- * (adw-preferences-dialog.c:201-207).
- *
- * GLib emits NUMERIC references for the quote characters (`'`, `"`),
- * not `'`/`"`; a port that "tidies" those up produces a different
- * string for the same input. Control characters become `&#xN;` — GLib's own C1
+ * `g_markup_escape_text` — the escape `create_search_row_subtitle` puts a page title
+ * through before it becomes a markup subtitle. GLib emits NUMERIC references for the
+ * quote characters (`'`, `"`), not `'`/`"`, so a port that "tidies"
+ * those up produces a different string. Control characters become `&#xN;`; GLib's own C1
  * branch is unreachable for valid UTF-8 (it compares a signed `char` against
  * `0x7f`-`0x9f`), so only the ASCII controls are escaped here.
  */
 export declare function escapeMarkup(text: string): string;
 /**
- * `pango_parse_markup (text, -1, 0, NULL, &parsed, NULL, &error)` reduced to the
- * part `make_comparable` uses: the plain text, with tags dropped and entities
- * resolved.
+ * `pango_parse_markup (text, -1, 0, NULL, &parsed, NULL, &error)` reduced to the part
+ * `make_comparable` uses: the plain text, tags dropped and entities resolved.
  *
- * Returns `null` — NEVER throws — when the markup does not parse, so callers
- * reproduce the C fallback exactly: `g_critical` and keep the UNPARSED string
- * (adw-preferences-dialog.c:110-113). A row whose title contains a bare `&` must
- * stay in the search index under its literal text, not vanish from it.
+ * Returns `null` — NEVER throws — when the markup does not parse, so callers reproduce
+ * the C fallback exactly (`g_critical`, keep the UNPARSED string): a row whose title
+ * contains a bare `&` must stay in the search index under its literal text.
  *
- * Pango wraps the input in an implicit `<markup>` element, so several top-level
- * tags are legal. Unknown tag names are a parse error, which is why this keeps
- * pango's tag list rather than stripping anything that looks like a tag: `<3`
- * and `<div>` are TEXT to libadwaita, and a search for them must find them.
+ * Pango wraps the input in an implicit `<markup>` element, so several top-level tags are
+ * legal, and unknown tag names are a parse error — which is why this keeps pango's tag
+ * list rather than stripping anything tag-shaped: `<3` and `<div>` are TEXT to
+ * libadwaita and a search for them must find them.
  *
- * Deviations, both in the fail-closed direction (unparsed → caller keeps the raw
- * string, never a wrongly-stripped one): pango additionally validates `<span>`'s
- * attribute NAMES, and this does not; GMarkup's DOCTYPE/PI/CDATA handling is
- * modelled as plain passthrough, which is what pango's parser does with it
- * (its `passthrough` handler is NULL, so the content is discarded).
+ * Deviations, both fail-closed (unparsed → the caller keeps the raw string, never a
+ * wrongly-stripped one): pango additionally validates `<span>`'s attribute NAMES, and
+ * this does not; GMarkup's DOCTYPE/PI/CDATA handling is modelled as plain passthrough,
+ * which is what pango's parser does with it (its `passthrough` handler is NULL, so the
+ * content is discarded).
  */
 export declare function stripMarkup(text: string): string | null;
 /** Per-row flags `make_comparable` reads off the row it is comparing. */
@@ -72,37 +59,33 @@ export interface MakeComparableOptions {
     useUnderline?: boolean;
     /**
      * `make_comparable`'s third argument. The TITLE path passes `true`, the
-     * SUBTITLE path passes `false` (adw-preferences-dialog.c:133, :141) — so a
+     * SUBTITLE path passes `false` — so a
      * subtitle keeps its underscores even on a row that uses mnemonics.
      */
     allowUnderline?: boolean;
 }
 /**
- * `make_comparable` (adw-preferences-dialog.c:96-123): the form of a string the
- * search compares against, i.e. case-folded, markup-stripped and (for titles on
- * mnemonic rows) mnemonic-stripped.
+ * `make_comparable`: the form of a string the search compares against — case-folded,
+ * markup-stripped and (for titles on mnemonic rows) mnemonic-stripped.
  *
- * THE ORDER IS THE POINT AND IT IS NOT THE OBVIOUS ONE: fold FIRST, parse the
- * FOLDED string second. Parsing first would work too — but folding first is what
- * the C does, and the two differ for any markup whose tag name is case-sensitive
- * to the parser. Folding a lowercase-only tag set leaves it parseable, which is
- * why `<b>Dark</b> Style` still reduces to `dark style` rather than keeping its
- * tags.
+ * THE ORDER IS NOT THE OBVIOUS ONE: fold FIRST, parse the FOLDED string second, as the C
+ * does. The two differ for any markup whose tag name is case-sensitive to the parser;
+ * folding a lowercase-only tag set leaves it parseable, which is why `<b>Dark</b> Style`
+ * still reduces to `dark style` rather than keeping its tags.
  */
 export declare function makeComparable(source: string | null | undefined, options?: MakeComparableOptions, fold?: CaseFolder): string;
 /** What {@link derivePreferencesGroupHeader} is asked about. */
 export interface PreferencesGroupHeaderInput {
     /**
      * `AdwPreferencesGroup:title`. `null`/`undefined` is the empty string —
-     * `adw_preferences_group_set_title` normalises NULL to `""`
-     * (adw-preferences-group.c:508).
+     * `adw_preferences_group_set_title` normalises NULL to `""`.
      */
     title?: string | null;
     /**
      * `AdwPreferencesGroup:description`. Normalised here as well, although
      * `adw_preferences_group_set_description` passes NULL straight through
-     * (:555) where its own `set_title` and `adw_preferences_page_set_title`
-     * (adw-preferences-page.c:538) both normalise — an inconsistency in the C
+     * where its own `set_title` and `adw_preferences_page_set_title`
+     * both normalise — an inconsistency in the C
      * with no behavioural consequence, since the visibility test treats NULL and
      * `""` alike.
      */
@@ -111,8 +94,8 @@ export interface PreferencesGroupHeaderInput {
     hasHeaderSuffix?: boolean;
     /**
      * How many children the listbox holds. This is the RAW child count —
-     * `update_listbox_visibility` reads `gtk_widget_observe_children (listbox)`
-     * (adw-preferences-group.c:111-123), NOT the title-filtered model that
+     * `update_listbox_visibility` reads `gtk_widget_observe_children (listbox)`,
+     * NOT the title-filtered model that
      * `get_rows` builds, so a row with an empty title still keeps the card
      * painted.
      */
@@ -127,20 +110,20 @@ export interface PreferencesGroupHeaderInput {
 }
 /** The five derived visual states of a preferences group. */
 export interface PreferencesGroupHeaderState {
-    /** `update_title_visibility` (adw-preferences-group.c:91-99). */
+    /** `update_title_visibility`. */
     titleVisible: boolean;
-    /** `update_description_visibility` (:101-109). */
+    /** `update_description_visibility`. */
     descriptionVisible: boolean;
-    /** `update_header_visibility` (:142-156) — the header box takes no space otherwise. */
+    /** `update_header_visibility` — the header box takes no space otherwise. */
     headerVisible: boolean;
     /**
-     * `is_single_line` (:125-140), carried as the `single-line` style class.
+     * `is_single_line`, carried as the `single-line` style class.
      * Load-bearing: the stylesheet gives a single-line header `min-height: 34px`
      * and a multi-line one `margin-bottom: 6px`
-     * (stylesheet/widgets/_preferences.scss:6-13).
+     * (stylesheet/widgets/_preferences.scss).
      */
     singleLine: boolean;
-    /** `update_listbox_visibility` (:111-123) — the `.boxed-list` card is hidden at zero rows. */
+    /** `update_listbox_visibility` — the `.boxed-list` card is hidden at zero rows. */
     listboxVisible: boolean;
 }
 /**
@@ -162,9 +145,9 @@ export declare function derivePreferencesGroupHeader(input: PreferencesGroupHead
  * One indexable row, as the search reasons about it.
  *
  * `isActionRow` is load-bearing and is NOT "has a subtitle": only
- * `ADW_IS_ACTION_ROW` rows have their subtitle searched
- * (adw-preferences-dialog.c:140-146), and `AdwEntryRow` derives from
- * `AdwPreferencesRow`, not from `AdwActionRow` (adw-entry-row.c:90) — so the
+ * `ADW_IS_ACTION_ROW` rows have their subtitle searched,
+ * and `AdwEntryRow` derives from
+ * `AdwPreferencesRow`, not from `AdwActionRow` — so the
  * text typed into an entry row is deliberately not searchable. Same for
  * `AdwExpanderRow` and `AdwButtonRow`.
  */
@@ -188,7 +171,7 @@ export interface PreferencesSearchRow<T = unknown> {
 export interface PreferencesSearchGroup<T = unknown> {
     /** `AdwPreferencesGroup:title`; an empty one drops out of the result subtitle. */
     title?: string | null;
-    /** `is_visible_group` (adw-preferences-page.c:76-82), default `true`. */
+    /** `is_visible_group`, default `true`. */
     visible?: boolean;
     /** The group's preferences rows, in listbox order. */
     rows: readonly PreferencesSearchRow<T>[];
@@ -199,7 +182,7 @@ export interface PreferencesSearchGroup<T = unknown> {
  * One page, as the search reasons about it.
  *
  * `visible` is the same flag `ViewStackState.setPageVisible` maintains —
- * the dialog's pages ARE an `AdwViewStack` (adw-preferences-dialog.c:707-711),
+ * the dialog's pages ARE an `AdwViewStack`,
  * so a renderer holds the page ORDER and SELECTION there and describes the
  * same pages here for indexing.
  */
@@ -228,7 +211,7 @@ export interface PreferencesSearchEntry<T = unknown> {
     row: PreferencesSearchRow<T>;
 }
 /**
- * `get_n_pages` (adw-preferences-dialog.c:150-166) — how many pages are visible,
+ * `get_n_pages` — how many pages are visible,
  * which is what decides whether a result subtitle names its page.
  */
 export declare function countVisiblePages<T>(pages: readonly PreferencesSearchPage<T>[]): number;
@@ -236,14 +219,14 @@ export declare function countVisiblePages<T>(pages: readonly PreferencesSearchPa
  * The search corpus: every row the dialog will ever match against.
  *
  * This is the filter → map → flatten chain of `adw_preferences_dialog_init`
- * (:632-641) composed with `adw_preferences_page_get_rows` (:821-841) and
- * `adw_preferences_group_get_rows` (:726-741), i.e. THREE filters written in
+ * composed with `adw_preferences_page_get_rows` and
+ * `adw_preferences_group_get_rows`, i.e. THREE filters written in
  * three different C files:
  *
- *   1. visible PAGES only — a `GtkBoolFilter` over `AdwViewStackPage:visible`;
- *   2. visible GROUPS only — `is_visible_group`;
- *   3. rows that are preferences rows AND visible AND have a NON-EMPTY title —
- *      `row_has_title`.
+ * 1. visible PAGES only — a `GtkBoolFilter` over `AdwViewStackPage:visible`;
+ * 2. visible GROUPS only — `is_visible_group`;
+ * 3. rows that are preferences rows AND visible AND have a NON-EMPTY title —
+ * `row_has_title`.
  *
  * Filter 3 is the one a port drops, and dropping it is invisible: nothing
  * errors, the search just silently indexes rows a user cannot recognise (an
@@ -253,23 +236,23 @@ export declare function countVisiblePages<T>(pages: readonly PreferencesSearchPa
  */
 export declare function collectSearchRows<T>(pages: readonly PreferencesSearchPage<T>[]): PreferencesSearchEntry<T>[];
 /**
- * `filter_search_results` (adw-preferences-dialog.c:125-153): whether a row
+ * `filter_search_results`: whether a row
  * matches the current search terms.
  *
  * Three properties a port tends to get wrong, all of them user-visible:
  *
- *   - it is a SUBSTRING test (`strstr`), not a prefix and not word-boundary —
- *     `ARK` matches `Dark Style`;
- *   - the EMPTY query matches everything (`strstr (title, "")` returns `title`),
- *     which is why the dialog shows "results" and not "no results" before the
- *     user has typed anything;
- *   - the query is only case-FOLDED. It is not markup-parsed and not
- *     mnemonic-stripped, so typing `_` searches for a literal underscore.
+ * - it is a SUBSTRING test (`strstr`), not a prefix and not word-boundary —
+ * `ARK` matches `Dark Style`;
+ * - the EMPTY query matches everything (`strstr (title, "")` returns `title`),
+ * which is why the dialog shows "results" and not "no results" before the
+ * user has typed anything;
+ * - the query is only case-FOLDED. It is not markup-parsed and not
+ * mnemonic-stripped, so typing `_` searches for a literal underscore.
  */
 export declare function rowMatchesQuery<T>(row: PreferencesSearchRow<T>, query: string, fold?: CaseFolder): boolean;
 /**
- * The translated fallback for a page with no title
- * (adw-preferences-dialog.c:218). Exported so a renderer with a translation
+ * The translated fallback for a page with no title.
+ * Exported so a renderer with a translation
  * catalogue can pass its own through `untitledPageLabel`.
  */
 export declare const UNTITLED_PAGE_LABEL = "Untitled page";
@@ -292,21 +275,21 @@ export interface SearchRowSubtitleInput {
     untitledPageLabel?: string;
 }
 /**
- * `create_search_row_subtitle` (adw-preferences-dialog.c:168-234) — the second
+ * `create_search_row_subtitle` — the second
  * line of a search result, e.g. `General → Appearance`.
  *
  * The rules, in the order the C applies them, none of them symmetric:
  *
- *   - an empty GROUP title becomes "absent", and the whole `page → group` join
- *     is then skipped — the result falls through to the bare page title;
- *   - the PAGE title is mnemonic-stripped when the PAGE uses underline, then
- *     markup-escaped when the ROW uses markup (a page-level property and a
- *     row-level property deciding two steps on the same string), and only then
- *     tested for emptiness;
- *   - the join happens only when more than one page is VISIBLE; with a single
- *     page the subtitle is the group title alone;
- *   - the group title is NOT escaped, so the two halves of `page → group` are
- *     escaped differently on purpose.
+ * - an empty GROUP title becomes "absent", and the whole `page → group` join
+ * is then skipped — the result falls through to the bare page title;
+ * - the PAGE title is mnemonic-stripped when the PAGE uses underline, then
+ * markup-escaped when the ROW uses markup (a page-level property and a
+ * row-level property deciding two steps on the same string), and only then
+ * tested for emptiness;
+ * - the join happens only when more than one page is VISIBLE; with a single
+ * page the subtitle is the group title alone;
+ * - the group title is NOT escaped, so the two halves of `page → group` are
+ * escaped differently on purpose.
  *
  * `null` means "no subtitle at all", which is what a renderer should render as
  * an absent line rather than as an empty one.
@@ -314,7 +297,7 @@ export interface SearchRowSubtitleInput {
 export declare function createSearchRowSubtitle(input: SearchRowSubtitleInput): string | null;
 /** One row of the search results list. */
 export interface PreferencesSearchResult<T = unknown> {
-    /** Copied verbatim from the matched row (`new_search_row_for_preference`, :245-256). */
+    /** Copied verbatim from the matched row (`new_search_row_for_preference`). */
     title: string;
     /** {@link createSearchRowSubtitle}; `null` when there is nothing to show. */
     subtitle: string | null;
@@ -342,7 +325,7 @@ export interface SearchPreferencesOptions {
  * `GtkFlattenListModel` produces).
  *
  * Each result carries the source `page`/`group`/`row` so a renderer can
- * implement `search_result_activated_cb` (adw-preferences-dialog.c:267-290) —
+ * implement `search_result_activated_cb` —
  * switch the visible page, focus the row — without re-deriving anything.
  */
 export declare function searchPreferences<T>(pages: readonly PreferencesSearchPage<T>[], query: string, options?: SearchPreferencesOptions): PreferencesSearchResult<T>[];

package/lib/types/rows.d.ts

@@ -40,34 +40,25 @@ export type AdwComboOptionInput = string | {
     label?: unknown;
 };
 /**
- * Raw authored options → the stable `{ value, label }` descriptors every combo
- * surface works with.
+ * Raw authored options → the stable `{ value, label }` descriptors every combo surface
+ * works with.
  *
  * A bare string is both value and label (`Gtk.StringList`'s model, which is what
- * `Adw.ComboRow` is fed in the common case). In a descriptor either half stands
- * in for the missing other, so `{ label: 'Apple' }` is addressable by the value
- * `'Apple'` rather than by `undefined`.
- *
- * ONE home, because there were two: `<adw-combo-row>` mapped `string[]` inline
- * from its JSON attribute while `<adw-drop-down>` carried a private
- * `normalizeOptions` that also handled descriptors — so the same widget family
- * accepted two different option vocabularies depending on which element you
- * reached for.
+ * `Adw.ComboRow` is fed in the common case). In a descriptor either half stands in for the
+ * missing other, so `{ label: 'Apple' }` is addressable by the value `'Apple'` rather than
+ * by `undefined`. ONE home for the rule, so `<adw-combo-row>` and `<adw-drop-down>` cannot
+ * accept two different option vocabularies.
  */
 export declare function normalizeComboOptions(raw: ReadonlyArray<AdwComboOptionInput> | null | undefined): AdwComboOption[];
 /**
  * The "no item is selected" index — the TS mirror of `GTK_INVALID_LIST_POSITION`
- * (`AdwComboRow:selected`'s default and empty value, adw-combo-row.c:593-596,
- * :809-810).
- *
- * libadwaita spells it `G_MAXUINT` because the property is a `guint`; `-1` is the
- * idiomatic TS sentinel and the spelling {@link ADW_SIDEBAR_NO_SELECTION} already
- * uses for the same GTK constant.
+ * (`AdwComboRow:selected`'s default and empty value).
  *
- * It exists because an EMPTY model and a model whose first item happens to have
- * an empty label were previously indistinguishable: both reported index 0 with
- * `selectedValue === ''`. A renderer that wants to draw a placeholder had nothing
- * to test.
+ * libadwaita spells it `G_MAXUINT` because the property is a `guint`; `-1` is the idiomatic
+ * TS sentinel and the spelling {@link ADW_SIDEBAR_NO_SELECTION} uses for the same GTK
+ * constant. Without it, an EMPTY model and a model whose first item has an empty label are
+ * indistinguishable — both report index 0 with `selectedValue === ''` — so a renderer that
+ * wants to draw a placeholder has nothing to test.
  */
 export declare const ADW_COMBO_NO_SELECTION = -1;
 /** Payload of a {@link ComboState} change. */
@@ -102,38 +93,33 @@ export declare class ComboState {
     /** The selectable options. */
     get options(): AdwComboOption[];
     /**
-     * Replace the options, then notify (`interactive: false`) so the renderer
-     * re-syncs the inline value label — which may change even at an unchanged
-     * index, because the label is read out of the MODEL.
+     * Replace the options, then notify (`interactive: false`) so the renderer re-syncs the
+     * inline value label — which may change even at an unchanged index, because the label is
+     * read out of the MODEL.
      *
-     * Replacing the model re-runs autoselect, so an index the new one does not
-     * have falls back to 0 — including the sentinel, which is how a row recovers
-     * a selection when its model grows. An EMPTY model has no 0 to fall back to
-     * and lands on {@link ADW_COMBO_NO_SELECTION}; that case is the one both
-     * ports used to spell as index 0.
+     * Replacing the model re-runs autoselect, so an index the new one does not have falls
+     * back to 0 — including the sentinel, which is how a row recovers a selection when its
+     * model grows. An EMPTY model has no 0 to fall back to and lands on
+     * {@link ADW_COMBO_NO_SELECTION}.
      *
-     * The check is `hasIndex`, not `selected >= length`: the sentinel is BELOW
-     * the range, so the one-sided comparison left a `-1` in place and a model
-     * that had been emptied and refilled came back with nothing selected.
+     * The check is `hasIndex`, not `selected >= length`: the sentinel is BELOW the range, so
+     * a one-sided comparison leaves a `-1` in place and a model that was emptied and
+     * refilled comes back with nothing selected.
      */
     setOptions(options: AdwComboOption[]): void;
     /**
-     * The selected option index, or {@link ADW_COMBO_NO_SELECTION}.
-     *
-     * May also sit PAST the options length: {@link setSelectedIndex} is
-     * deliberately permissive, mirroring a `guint` property that takes any
-     * position. {@link selectedValue} reads `''` in both cases, which is why the
-     * sentinel is what distinguishes "nothing selected" from "an empty label".
+     * The selected option index, or {@link ADW_COMBO_NO_SELECTION}. May also sit PAST the
+     * options length: {@link setSelectedIndex} is deliberately permissive, mirroring a
+     * `guint` property that takes any position. {@link selectedValue} reads `''` in both
+     * cases, which is why the sentinel is what distinguishes "nothing selected" from "an
+     * empty label".
      */
     get selectedIndex(): number;
     /**
-     * Whether the row presents itself as a CHOOSER — `model_changed`
-     * (adw-combo-row.c:187-195) makes the arrow visible and the row activatable
-     * on `n_items > 1` and hides both otherwise.
-     *
-     * One item or none is not a choice, so `Adw.ComboRow` stops looking like one:
-     * no chevron, and tapping does nothing. Neither port did this, so a
-     * single-option row showed its arrow and opened a chooser with one entry.
+     * Whether the row presents itself as a CHOOSER — `model_changed` makes the arrow visible
+     * and the row activatable on `n_items > 1`, and hides both otherwise. One item or none is
+     * not a choice, so `Adw.ComboRow` stops looking like one: no chevron, and tapping does
+     * nothing.
      */
     get presentsChooser(): boolean;
     /** Programmatic index set — notifies `interactive: false`. Returns whether it changed. */
@@ -147,29 +133,25 @@ export declare class ComboState {
     /**
      * Whether `index` addresses an option that exists.
      *
-     * The bounds arithmetic lives here; the POLICY for a programmatic
-     * out-of-range set does not, because this tree cannot settle it:
-     * `adw_combo_row_set_selected` forwards the position straight to
-     * `gtk_single_selection_set_selected` (adw-combo-row.c:788) and documents
-     * `GTK_INVALID_LIST_POSITION` as a legal argument, but `refs/gtk` is EMPTY
-     * so what GtkSingleSelection does with it is not verifiable here. So each
-     * renderer states its own answer against this one predicate:
-     * {@link setSelectedIndex} keeps the permissive model (an index past the end
-     * is how "nothing selected" is spelled — {@link selectedValue} then reads
-     * `''`), while `<adw-drop-down>` rejects the set, as its published `selected`
-     * docs promise. Neither re-derives `index >= 0 && index < count`.
+     * The bounds arithmetic lives here; the POLICY for a programmatic out-of-range set does
+     * not, because this tree cannot settle it: `adw_combo_row_set_selected` forwards the
+     * position straight to `gtk_single_selection_set_selected` and documents
+     * `GTK_INVALID_LIST_POSITION` as a legal argument, but `refs/gtk` is EMPTY so what
+     * GtkSingleSelection does with it is not verifiable here. Each renderer therefore states
+     * its own answer against this one predicate: {@link setSelectedIndex} keeps the permissive
+     * model (an index past the end is how "nothing selected" is spelled and
+     * {@link selectedValue} reads `''`), while `<adw-drop-down>` rejects the set, as its
+     * published `selected` docs promise.
      */
     hasIndex(index: number): boolean;
     /**
      * Select an option by index as a USER pick (the chooser result) — notifies
-     * `interactive: true`. A no-op (returns false) for the already-selected index
-     * or one that addresses no option, matching the renderer's chooser guard.
+     * `interactive: true`. A no-op for the already-selected index or one that addresses no
+     * option.
      *
-     * The upper bound is part of that guard: a pick is a pick OF something, so
-     * `select(99)` on a three-option model is not "select nothing", it is a
-     * chooser reporting an index the model does not have. Only the negative half
-     * used to be checked, which left the interactive path able to move the index
-     * somewhere {@link setSelectedIndex} would have called "no selection".
+     * The UPPER bound is part of that guard: a pick is a pick OF something, so `select(99)` on
+     * a three-option model is not "select nothing", it is a chooser reporting an index the
+     * model does not have.
      */
     select(index: number): boolean;
     /** Number of options. */

package/lib/types/shortcut-label.d.ts

@@ -0,0 +1,79 @@
+/** One keycap. `sideMarker` is the `L`/`R` subscript of a sided modifier key. */
+export interface ShortcutKeycap {
+    /** The untranslated label — a `GTK_KEY_LABEL` msgid, a character, or a glyph. */
+    label: string;
+    /** `L` or `R` for `Control_L` / `Control_R` and friends (:115-196). */
+    sideMarker?: 'L' | 'R';
+}
+/** One node of the rendered label, in order. */
+export type ShortcutLabelNode = 
+/** A combination: keycaps drawn side by side, no separator (:370-395). */
+{
+    readonly kind: 'keys';
+    readonly keys: readonly ShortcutKeycap[];
+}
+/** A dimmed separator between groups (:359-368). */
+ | {
+    readonly kind: 'separator';
+    readonly text: string;
+}
+/** The `disabled-text` placeholder, shown for an empty accelerator (:513-520). */
+ | {
+    readonly kind: 'disabled';
+    readonly text: string;
+};
+/** What a renderer needs to draw one `AdwShortcutLabel`. */
+export interface ShortcutLabelParse {
+    /** The nodes, in visual order. */
+    readonly nodes: readonly ShortcutLabelNode[];
+    /** The `aria-label` GTK builds alongside the widgets (:423-424, :538-540). */
+    readonly accessibleLabel: string;
+    /**
+     * The fragment that failed to parse, or `null`.
+     *
+     * GTK warns and stops mid-build (:531-534), keeping whatever it had already
+     * placed — so `nodes` is the partial result, not an empty one.
+     */
+    readonly error: string | null;
+}
+/** Options a renderer supplies from its own environment. */
+export interface ShortcutLabelOptions {
+    /** Shown when the accelerator is empty (:513-520). Defaults to `''`. */
+    readonly disabledText?: string;
+    /** Text direction — picks the sequence arrow (:439, :447). */
+    readonly direction?: 'ltr' | 'rtl';
+    /**
+     * Which modifier glyphs to use.
+     *
+     * The C picks this at COMPILE time with `#ifdef __APPLE__` (:153-182,
+     * :216-245, :318-331), so it is a build constant there and a runtime option
+     * here — a renderer knows its platform, and a browser one can be running on
+     * either.
+     */
+    readonly platform?: 'default' | 'apple';
+}
+/** The modifier bits `gtk_accelerator_parse` understands, in GTK's spelling. */
+type Modifier = 'shift' | 'control' | 'alt' | 'meta' | 'super' | 'hyper';
+/** An accelerator split into its modifiers and its key name. */
+interface ParsedAccelerator {
+    readonly modifiers: ReadonlySet<Modifier>;
+    readonly key: string;
+}
+/**
+ * `gtk_accelerator_parse`, over names instead of keyvals.
+ *
+ * Returns `null` for a malformed accelerator — an unterminated `<`, an unknown
+ * modifier name, or no key at all. Every one of those is decidable without the
+ * keysym table; an unknown KEY name is not, and is accepted (see the header).
+ */
+export declare function parseAccelerator(accelerator: string, platform?: 'default' | 'apple'): ParsedAccelerator | null;
+/** Every keycap of one accelerator: modifiers in GTK's order, then the key (:198-357). */
+export declare function shortcutKeycaps(accelerator: string, platform?: 'default' | 'apple'): readonly ShortcutKeycap[] | null;
+/**
+ * Parse an accelerator into the nodes a renderer draws.
+ *
+ * The four grammar levels of the widget's own `rebuild` → `parse_range` →
+ * `parse_sequence` → `parse_combination` chain (:398-544), in that nesting.
+ */
+export declare function parseShortcutLabel(accelerator: string, options?: ShortcutLabelOptions): ShortcutLabelParse;
+export {};

package/lib/types/shortcut-label.spec.d.ts

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