@gjsify/adwaita-core 0.31.0 → 0.32.0

package/lib/types/preferences.d.ts

@@ -0,0 +1,349 @@
+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.
+ */
+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:
+ *
+ * | input    | `toLowerCase()` | case fold  |
+ * |----------|-----------------|------------|
+ * | `Straße` | `straße`        | `strasse`  |
+ * | `ΟΔΟΣ`   | `οδος`          | `οδοσ`     |
+ * | `file`    | `file`           | `file`     |
+ *
+ * `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
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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).
+ */
+export declare function stripMarkup(text: string): string | null;
+/** Per-row flags `make_comparable` reads off the row it is comparing. */
+export interface MakeComparableOptions {
+    /** `AdwPreferencesRow:use-markup`. Defaults to `true`, as the property does. */
+    useMarkup?: boolean;
+    /** `AdwPreferencesRow:use-underline`. Defaults to `false`, as the property does. */
+    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 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.
+ *
+ * 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.
+ */
+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).
+     */
+    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
+     * with no behavioural consequence, since the visibility test treats NULL and
+     * `""` alike.
+     */
+    description?: string | null;
+    /** Whether an `AdwPreferencesGroup:header-suffix` widget is set. */
+    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
+     * `get_rows` builds, so a row with an empty title still keeps the card
+     * painted.
+     */
+    rowCount?: number;
+    /**
+     * Whether the title/description labels interpret Pango markup. `true` by
+     * default because both labels are `use-markup=True` in
+     * adw-preferences-group.ui — a renderer that shows the strings verbatim
+     * passes `false`.
+     */
+    useMarkup?: boolean;
+}
+/** The five derived visual states of a preferences group. */
+export interface PreferencesGroupHeaderState {
+    /** `update_title_visibility` (adw-preferences-group.c:91-99). */
+    titleVisible: boolean;
+    /** `update_description_visibility` (:101-109). */
+    descriptionVisible: boolean;
+    /** `update_header_visibility` (:142-156) — the header box takes no space otherwise. */
+    headerVisible: boolean;
+    /**
+     * `is_single_line` (:125-140), 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).
+     */
+    singleLine: boolean;
+    /** `update_listbox_visibility` (:111-123) — the `.boxed-list` card is hidden at zero rows. */
+    listboxVisible: boolean;
+}
+/**
+ * The five header/listbox states of an `Adw.PreferencesGroup`, derived once for
+ * every renderer.
+ *
+ * A pure derivation rather than a state machine, which is the honest shape: C
+ * recomputes all of this from scratch in `update_*_visibility` on every change,
+ * holding no state of its own beyond the widgets it is reading.
+ *
+ * Only the EXACT empty string hides a label — `g_strcmp0 (text, "")`, so a title
+ * of a single space is a visible title and must not be trimmed. That is the same
+ * rule {@link stringIsNotEmpty} carries for the label bindings, so it is applied
+ * from there rather than respelled here; what stays local is only which STRING it
+ * is applied to, since this widget judges the markup-stripped display text.
+ */
+export declare function derivePreferencesGroupHeader(input: PreferencesGroupHeaderInput): PreferencesGroupHeaderState;
+/**
+ * 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
+ * text typed into an entry row is deliberately not searchable. Same for
+ * `AdwExpanderRow` and `AdwButtonRow`.
+ */
+export interface PreferencesSearchRow<T = unknown> {
+    /** `AdwPreferencesRow:title`. A row with an empty title is not indexed at all. */
+    title: string;
+    /** `AdwActionRow:subtitle`, consulted only when `isActionRow`. */
+    subtitle?: string | null;
+    /** `AdwPreferencesRow:use-markup`, default `true`. */
+    useMarkup?: boolean;
+    /** `AdwPreferencesRow:use-underline`, default `false`. */
+    useUnderline?: boolean;
+    /** `gtk_widget_get_visible`, default `true`. A hidden row leaves the corpus. */
+    visible?: boolean;
+    /** Whether the row derives from `AdwActionRow`, default `false`. */
+    isActionRow?: boolean;
+    /** The renderer's own row object, carried through to the result untouched. */
+    ref?: T;
+}
+/** One group of rows, as the search reasons about it. */
+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`. */
+    visible?: boolean;
+    /** The group's preferences rows, in listbox order. */
+    rows: readonly PreferencesSearchRow<T>[];
+    /** The renderer's own group object. */
+    ref?: T;
+}
+/**
+ * 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),
+ * so a renderer holds the page ORDER and SELECTION there and describes the
+ * same pages here for indexing.
+ */
+export interface PreferencesSearchPage<T = unknown> {
+    /** `AdwPreferencesPage:name`, the view stack child name. */
+    name?: string | null;
+    /** `AdwPreferencesPage:title`; shown in a result subtitle when several pages are visible. */
+    title?: string;
+    /** `AdwPreferencesPage:icon-name`. Not read by the search; carried for the switcher. */
+    iconName?: string | null;
+    /** `AdwPreferencesPage:use-underline`, default `false`. */
+    useUnderline?: boolean;
+    /** `AdwViewStackPage:visible`, default `true`. An invisible page contributes nothing. */
+    visible?: boolean;
+    /** `AdwPreferencesPage:description`. Not searched — only rows are. */
+    description?: string;
+    /** The page's groups, in order. */
+    groups: readonly PreferencesSearchGroup<T>[];
+    /** The renderer's own page object. */
+    ref?: T;
+}
+/** One row of the corpus, with the ancestors a result subtitle needs. */
+export interface PreferencesSearchEntry<T = unknown> {
+    page: PreferencesSearchPage<T>;
+    group: PreferencesSearchGroup<T>;
+    row: PreferencesSearchRow<T>;
+}
+/**
+ * `get_n_pages` (adw-preferences-dialog.c:150-166) — 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;
+/**
+ * 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
+ * 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`.
+ *
+ * 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
+ * untitled separator row) or, with the visibility half missing, rows that are
+ * not on screen. The `ADW_IS_PREFERENCES_ROW` half of it is expressed
+ * statically here — a `PreferencesSearchRow[]` cannot hold a plain list-box row.
+ */
+export declare function collectSearchRows<T>(pages: readonly PreferencesSearchPage<T>[]): PreferencesSearchEntry<T>[];
+/**
+ * `filter_search_results` (adw-preferences-dialog.c:125-153): 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.
+ */
+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
+ * catalogue can pass its own through `untitledPageLabel`.
+ */
+export declare const UNTITLED_PAGE_LABEL = "Untitled page";
+/** What {@link createSearchRowSubtitle} needs about a matched row's ancestors. */
+export interface SearchRowSubtitleInput {
+    /** The group's title. `''` counts as absent. */
+    groupTitle?: string | null;
+    /**
+     * The page's title. `undefined` means there is no page ancestor at all —
+     * unreachable through the public API, since a row always sits in a page.
+     */
+    pageTitle?: string | null;
+    /** `AdwPreferencesPage:use-underline` — decides whether the page title is mnemonic-stripped. */
+    pageUseUnderline?: boolean;
+    /** The matched ROW's `use-markup` — decides whether the page title is markup-escaped. Default `true`. */
+    rowUseMarkup?: boolean;
+    /** `get_n_pages` — the page is only named when more than one page is visible. */
+    nVisiblePages: number;
+    /** Override for {@link UNTITLED_PAGE_LABEL}. */
+    untitledPageLabel?: string;
+}
+/**
+ * `create_search_row_subtitle` (adw-preferences-dialog.c:168-234) — 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.
+ *
+ * `null` means "no subtitle at all", which is what a renderer should render as
+ * an absent line rather than as an empty one.
+ */
+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). */
+    title: string;
+    /** {@link createSearchRowSubtitle}; `null` when there is nothing to show. */
+    subtitle: string | null;
+    /** The matched row's `use-markup`, copied onto the result row. */
+    useMarkup: boolean;
+    /** The matched row's `use-underline`, copied onto the result row. */
+    useUnderline: boolean;
+    /** The page the row lives on — what `search_result_activated_cb` switches to. */
+    page: PreferencesSearchPage<T>;
+    /** The group the row lives in. */
+    group: PreferencesSearchGroup<T>;
+    /** The matched row — what `search_result_activated_cb` focuses. */
+    row: PreferencesSearchRow<T>;
+}
+/** Knobs for {@link searchPreferences}. */
+export interface SearchPreferencesOptions {
+    /** Case folder to compare with. Defaults to {@link defaultCaseFolder}. */
+    fold?: CaseFolder;
+    /** Translated replacement for {@link UNTITLED_PAGE_LABEL}. */
+    untitledPageLabel?: string;
+}
+/**
+ * The whole search half in one call: corpus → filter → result rows, in corpus
+ * order (which is page order, then group order, then row order — the same order
+ * `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) —
+ * 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>[];
+export { stripMnemonic };

package/lib/types/preferences.spec.d.ts

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

package/lib/types/rows.d.ts

@@ -30,6 +30,31 @@ export interface AdwComboOption {
     /** Underlying value returned by {@link ComboState.selectedValue}. */
     value: string;
 }
+/**
+ * What an author may write for one option before {@link normalizeComboOptions}
+ * has seen it: a bare string (value === label, the `Gtk.StringList` case), or a
+ * partial descriptor where either half may stand in for the other.
+ */
+export type AdwComboOptionInput = string | {
+    value?: unknown;
+    label?: unknown;
+};
+/**
+ * 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.
+ */
+export declare function normalizeComboOptions(raw: ReadonlyArray<AdwComboOptionInput> | null | undefined): AdwComboOption[];
 /** Payload of a {@link ComboState} change. */
 export interface ComboStateChange {
     /** The (new) selected index. */
@@ -78,10 +103,32 @@ export declare class ComboState {
     get selectedLabel(): string;
     /** Programmatic value set — moves the index to the first option with this `value`. No-op for an unknown value. */
     setSelectedValue(value: string): boolean;
+    /**
+     * 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`.
+     */
+    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 a negative index or the
-     * already-selected one, matching the renderer's chooser guard.
+     * `interactive: true`. A no-op (returns false) for the already-selected index
+     * or one that addresses no option, matching the renderer's chooser guard.
+     *
+     * 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".
      */
     select(index: number): boolean;
     /** Number of options. */