@gjsify/adwaita-core 0.31.0 → 0.32.0

package/lib/types/data-grid.d.ts

@@ -0,0 +1,140 @@
+/** Horizontal alignment of a column's header + cells. */
+export type AdwDataGridAlign = 'start' | 'end' | 'center';
+/** Accounting row emphasis. `normal` is the default plain data row. */
+export type AdwDataGridRowVariant = 'normal' | 'section' | 'subtotal' | 'total';
+/** The four row variants, in the order a statement uses them. */
+export declare const ADW_DATA_GRID_ROW_VARIANTS: ReadonlyArray<AdwDataGridRowVariant>;
+/** A column descriptor — what to read (`key`), how to label + align it. */
+export interface AdwDataGridColumn {
+    /** The row-object key this column renders. */
+    key: string;
+    /** Header text (defaults to `key`). */
+    label?: string;
+    /** 'start' | 'end' | 'center'. Defaults to 'start' (or 'end' when numeric). */
+    align?: AdwDataGridAlign;
+    /** Fixed CSS track size (e.g. '80px', '6rem') — pins the column width. */
+    width?: string;
+    /** Fractional track weight (→ `<flex>fr`) — lets the column grow. */
+    flex?: number;
+    /** Render cells in a monospace family (tabular figures apply regardless). */
+    monospace?: boolean;
+    /** Convenience: right-align + tabular-nums (numeric columns of figures). */
+    numeric?: boolean;
+}
+/** What a cell may hold — pre-formatted strings, or anything stringifiable. */
+export type AdwDataGridCellValue = string | number | boolean | AdwDataGridRowVariant | undefined;
+/** A row: cell values keyed by column key + optional accounting metadata. */
+export interface AdwDataGridRow {
+    /** Accounting emphasis. Default 'normal'. */
+    variant?: AdwDataGridRowVariant;
+    /** Make just this row clickable (overrides the element-level flag). */
+    interactive?: boolean;
+    /** Cell values keyed by column key (pre-formatted strings, or numbers). */
+    [key: string]: AdwDataGridCellValue;
+}
+/**
+ * One column track, in renderer-neutral terms.
+ *
+ * `fixed` carries the author's CSS length UNPARSED, because the browser can
+ * resolve every unit CSS has and no other renderer can: it is the one track kind
+ * whose meaning is the stylesheet's. A renderer without a CSS engine parses what
+ * it understands and falls back — see the NativeScript sibling for that call.
+ */
+export type DataGridTrack = 
+/** A pinned track: the `width` string exactly as the column declared it. */
+{
+    kind: 'fixed';
+    css: string;
+}
+/** A weighted track: `flex` fractions of the leftover space. */
+ | {
+    kind: 'flex';
+    weight: number;
+}
+/** The single slack-absorbing track — see {@link dataGridTracks}. */
+ | {
+    kind: 'slack';
+}
+/** A content-sized track. */
+ | {
+    kind: 'auto';
+};
+/** The class every data-grid cell carries, header cells included. */
+export declare const DATA_GRID_CELL_CLASS = "adw-data-grid-cell";
+/** The class every data-grid row carries, the header row included. */
+export declare const DATA_GRID_ROW_CLASS = "adw-data-grid-row";
+/**
+ * The column tracks derived from the column descriptors.
+ *
+ * `width` pins a track and `flex` weights one, each on its own column. The
+ * interesting rule is the third one and it is GLOBAL, not per column: when
+ * NOTHING declares a size anywhere, the FIRST column absorbs the slack and every
+ * other column sizes to its content. That is the statement shape — one label
+ * column taking whatever is left, trailing figures hugging the right edge — and
+ * it is why the emptiest possible column list still produces a usable grid.
+ *
+ * One declared size anywhere turns the rule off for every column, so a caller
+ * pinning a single column does not silently keep an implicit flexible one.
+ */
+export declare function dataGridTracks(columns: ReadonlyArray<AdwDataGridColumn>): DataGridTrack[];
+/**
+ * The CSS `grid-template-columns` value for a track list — the browser mapping.
+ *
+ * The slack track is `minmax(0px, 1fr)` rather than `1fr` so a long cell cannot
+ * push the column past its share (`1fr` floors at the content's min-content
+ * size); `0px` is spelled with its unit because that is the CSSOM-canonical
+ * form, and a bare `0` does not round-trip through `style.gridTemplateColumns`.
+ */
+export declare function dataGridTrackTemplate(tracks: ReadonlyArray<DataGridTrack>): string;
+/**
+ * A column's effective alignment: its own `align`, or `end` when it is numeric.
+ *
+ * The numeric default is the widget's reason to exist — a column of figures that
+ * does not end on a common right edge is a boxed list with extra steps.
+ */
+export declare function dataGridColumnAlign(column: AdwDataGridColumn): AdwDataGridAlign;
+/**
+ * The classes a column's cells carry: the base cell class, the alignment, and
+ * the two typographic opt-ins.
+ *
+ * `numeric` and `mono` are the libadwaita label classes (_labels.scss:81-88):
+ * both set `font-variant-numeric: tabular-nums`, `mono` additionally switching
+ * to the monospace family. A renderer whose stylesheet cannot express that
+ * feature still gets the alignment, which is the half that survives.
+ *
+ * `align` is NOT clamped to {@link AdwDataGridAlign} here, so a value outside
+ * the union produces a class no stylesheet claims and the cell falls back to the
+ * base rule. That is deliberate asymmetry with {@link normalizeDataGridVariant}:
+ * a bogus variant would pick an EMPHASIS (a bold total rule where none belongs),
+ * a bogus alignment only fails to move text.
+ */
+export declare function dataGridColumnClasses(column: AdwDataGridColumn): string[];
+/**
+ * Coerce a cell value to display text — pre-formatted strings pass through.
+ *
+ * The grid FORMATS NOTHING: locale currency, thousands separators and decimals
+ * are the app's, because only the app knows the locale and the rounding. A
+ * number reaching here is a convenience, not a formatting request, so it is
+ * stringified as-is. A missing key is empty rather than `undefined`.
+ */
+export declare function dataGridCellText(value: AdwDataGridCellValue | null): string;
+/** Clamp an arbitrary variant to the known set (unknown → 'normal'). */
+export declare function normalizeDataGridVariant(variant: unknown): AdwDataGridRowVariant;
+/** Normalise raw column descriptors to a stable list (drops malformed entries). */
+export declare function normalizeDataGridColumns(raw: unknown): AdwDataGridColumn[];
+/**
+ * Whether a row activates on click/tap.
+ *
+ * Three conditions, and the order matters. Only a `normal` row can activate at
+ * all — a section header, a subtotal and a total are STRUCTURE, and making them
+ * tappable would offer a detail view for a computed line that has none. Then the
+ * per-row flag wins over the grid-level one in BOTH directions: `false` opts a
+ * single row out of a fully interactive grid, `true` opts a single row into an
+ * otherwise inert one.
+ *
+ * `rowFlag` is `unknown` on purpose: it arrives from a JSON attribute, where
+ * anything can be under the key, and only the two booleans decide. Any other
+ * value defers to the grid, which is what a value the widget cannot read should
+ * do.
+ */
+export declare function dataGridRowInteractive(variant: AdwDataGridRowVariant, rowFlag: unknown, gridInteractive: boolean): boolean;

package/lib/types/data-grid.spec.d.ts

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

package/lib/types/dialog.d.ts

@@ -98,3 +98,147 @@ export declare class AdwAlertResponses {
      */
     resolveLabel(label: string | null | undefined): string;
 }
+/**
+ * Which affordance asked a bottom sheet to close.
+ *
+ * These are not interchangeable: the C source runs each through a DIFFERENT
+ * gate, and the differences are exactly what a renderer flattening them into one
+ * `_attemptClose()` loses.
+ *
+ * - `'dimming'`      — a click on the modal scrim (`released_cb`).
+ * - `'escape'`       — the <kbd>Escape</kbd> shortcut on the sheet (`maybe_close_cb`).
+ * - `'close-button'` — the `sheet.close` widget action (`sheet_close_cb`).
+ * - `'drag-handle'`  — the pill at the top of the sheet. Decorative in libadwaita.
+ * - `'swipe'`        — a downward swipe on the sheet (`prepare_cb` → `end_swipe_cb`).
+ */
+export type BottomSheetCloseSource = 'dimming' | 'escape' | 'close-button' | 'drag-handle' | 'swipe';
+/**
+ * What a renderer must do about a close request.
+ *
+ * - `'close'`         — close the sheet.
+ * - `'close-attempt'` — emit `close-attempt`; the sheet stays as it is.
+ * - `'delegate'`      — forward the `sheet.close` action to the PARENT (a sheet
+ *                       nested in another sheet/dialog closes the outer one).
+ * - `'ignored'`       — do nothing, and emit nothing. Not the same as
+ *                       `'close-attempt'`: a locked sheet swallows a swipe
+ *                       silently but SIGNALS a scrim click.
+ */
+export type BottomSheetCloseOutcome = 'close' | 'close-attempt' | 'delegate' | 'ignored';
+/** The two bits {@link resolveBottomSheetClose} decides from. */
+export interface BottomSheetCloseState {
+    /** Whether the sheet is currently revealed (`AdwBottomSheet:open`). */
+    open: boolean;
+    /** Whether the user may dismiss it (`AdwBottomSheet:can-close`). */
+    canClose: boolean;
+}
+/**
+ * The dismissal decision table — `Adw.BottomSheet`'s five dismissal affordances
+ * as one pure function, callable without owning any state.
+ *
+ * Three rows are worth reading twice, because no renderer got them right:
+ *
+ * - `('drag-handle', …)` is ALWAYS `'ignored'`. The handle is created with
+ *   `can_focus = FALSE` + `can_target = FALSE` (adw-bottom-sheet.c:1197-1198),
+ *   so it cannot be clicked at all; its only behavioural role is elsewhere
+ *   (`allow_mouse_drag = show_drag_handle || bottom_bar`, adw-bottom-sheet.c:455).
+ *   Both ports had turned it into a close BUTTON, which is the one behaviour it
+ *   provably does not have.
+ * - `('escape', { open: false })` is `'close-attempt'`, not nothing. The emit in
+ *   `maybe_close_cb` (adw-bottom-sheet.c:393-399) is the fallthrough for EVERY
+ *   case that is not `can_close && open`, and a closed sheet is still focusable
+ *   while it shows a bottom bar.
+ * - `('close-button', { open: false, canClose: true })` is `'delegate'`:
+ *   `sheet_close_cb` (adw-bottom-sheet.c:377-385) activates the parent's
+ *   `sheet.close` action instead of doing nothing.
+ *
+ * The `'dimming'`/`'swipe'` closed rows encode a REACHABILITY gate rather than a
+ * branch inside the callback: `released_cb` never tests `open`, but the scrim is
+ * `can_target = open` (adw-bottom-sheet.c:1148, 1692), and `prepare_cb` refuses
+ * to even detect a swipe unless the direction matches the state
+ * (adw-bottom-sheet.c:1050-1053). Neither can fire on a closed sheet, so neither
+ * signals anything.
+ */
+export declare function resolveBottomSheetClose(source: BottomSheetCloseSource, state: BottomSheetCloseState): BottomSheetCloseOutcome;
+/** One entry in a {@link BottomSheetPresentation}'s teardown callback pair. */
+export type BottomSheetTeardownCallback = 'closing' | 'closed';
+/** Subscriber for {@link BottomSheetPresentation} `open` changes. */
+export type BottomSheetPresentationListener = (open: boolean) => void;
+/**
+ * The two callbacks `AdwDialog` installs on its bottom sheet
+ * (`adw_bottom_sheet_set_callbacks`, adw-bottom-sheet.c:2227-2238). They are
+ * NOT the same event twice:
+ *
+ * - `onClosing` fires when the close STARTS — adw-dialog.c:231-240 turns it into
+ *   the public `AdwDialog::closed` signal.
+ * - `onClosed` fires when the sheet has finished hiding — adw-dialog.c:243-249
+ *   turns it into the dialog's removal from the widget tree.
+ */
+export interface BottomSheetPresentationOptions {
+    /** The close started (`closing_callback`). */
+    onClosing?: () => void;
+    /** The sheet finished hiding (`closed_callback`). */
+    onClosed?: () => void;
+}
+/**
+ * The open/closed half of `Adw.BottomSheet` — the part with no geometry in it:
+ * the idempotent `open` flag, the `can-close` gate applied through
+ * {@link resolveBottomSheetClose}, and the `has_been_open` teardown replay.
+ *
+ * `setOpen` is the PROGRAMMATIC path and deliberately ignores `can-close`
+ * ("Bottom sheet can still be closed using [property@BottomSheet:open]",
+ * adw-bottom-sheet.c:2071); {@link requestClose} is the INTERACTIVE path that
+ * runs the gate. Keeping them apart is what lets a locked sheet still be closed
+ * by its owner — the distinction NativeScript lacked entirely (every dismissal
+ * went through one unconditional `close()`).
+ */
+export declare class BottomSheetPresentation {
+    private _open;
+    private _canClose;
+    private _hasBeenOpen;
+    private readonly _listeners;
+    private readonly _onClosing;
+    private readonly _onClosed;
+    constructor(options?: BottomSheetPresentationOptions);
+    /** Subscribe to `open` changes (the `notify::open` seam). Returns an unsubscribe function. */
+    subscribe(listener: BottomSheetPresentationListener): () => void;
+    private _emit;
+    /** Whether the sheet is revealed (`AdwBottomSheet:open`). */
+    get open(): boolean;
+    /** Whether the user may dismiss the sheet (`AdwBottomSheet:can-close`). */
+    get canClose(): boolean;
+    /**
+     * Whether the sheet has ever been open. Drives the teardown replay in
+     * {@link setOpen}; `has_been_open` in the C source (adw-bottom-sheet.c:153).
+     */
+    get hasBeenOpen(): boolean;
+    /** Set `can-close`. Returns whether it changed (adw-bottom-sheet.c:2076-2091). */
+    setCanClose(canClose: boolean): boolean;
+    /**
+     * The programmatic open/close — `adw_bottom_sheet_set_open`
+     * (adw-bottom-sheet.c:1661-1778). Returns whether `open` changed, i.e.
+     * whether a `notify::open` was emitted.
+     *
+     * `can-close` is NOT consulted: this is the owner's path, and it is how
+     * `adw_dialog_force_close` closes a locked dialog (adw-dialog.c:1979-1997).
+     */
+    setOpen(open: boolean): boolean;
+    /**
+     * Route a dismissal affordance through {@link resolveBottomSheetClose} and
+     * APPLY the outcome — `'close'` closes the sheet, everything else leaves it
+     * untouched. The returned outcome tells the renderer what to emit: a
+     * `close-attempt` signal, a `sheet.close` forwarded to the parent, or
+     * nothing at all.
+     */
+    requestClose(source: BottomSheetCloseSource): BottomSheetCloseOutcome;
+    /**
+     * The sheet has finished hiding — `open_animation_done_cb`'s teardown
+     * (adw-bottom-sheet.c:335-349) reduced to what a renderer without a spring
+     * animation can observe. Fires `onClosed` and returns whether it did.
+     *
+     * The C guard is `progress < 0.5` ("settled on the closed side"); with no
+     * animation the settled progress IS `open`, so an open sheet fires nothing.
+     * Call it only after a {@link setOpen} that RETURNED TRUE — the replay branch
+     * has already fired both callbacks for a never-opened sheet.
+     */
+    finishClose(): boolean;
+}

package/lib/types/entry-row.d.ts

@@ -0,0 +1,308 @@
+/** How long the empty↔filled title transition runs — adw-entry-row.c:18. */
+export declare const EMPTY_ANIMATION_DURATION_MS = 150;
+/**
+ * Gap between the shrunken title and the text baseline, in px —
+ * adw-entry-row.c:19 (`TITLE_SPACING`), used in the vertical measure (C:318,320)
+ * and in both the title offset and the baseline shift (C:384,407).
+ *
+ * Exported as DATA rather than applied here: the two renderers currently
+ * hardcode `1px` (web `_entry_row.scss`) and `2` (NS `theme/adwaita.css`), and
+ * neither knew it was meant to be the same number as the other's.
+ */
+export declare const ENTRY_ROW_TITLE_SPACING = 3;
+/**
+ * Upper bound of `Adw.EntryRow:max-length` / `:text-length`.
+ *
+ * `text-length` is declared `0, G_MAXUINT16, 0` (adw-entry-row.c:666-669) and
+ * `max-length` runs `0..GTK_ENTRY_BUFFER_MAX_SIZE` (C:678-682) — the same 16-bit
+ * ceiling. `0` means unlimited, so this is only the clamp for an absurd input.
+ */
+export declare const ENTRY_ROW_MAX_LENGTH_LIMIT = 65535;
+/** Icon name of the trailing pencil — adw-entry-row.ui (`edit_icon`). */
+export declare const ENTRY_ROW_EDIT_ICON_NAME = "adw-entry-edit-symbolic";
+/** Icon name of the apply button — adw-entry-row.ui (`apply_button`). */
+export declare const ENTRY_ROW_APPLY_ICON_NAME = "adw-entry-apply-symbolic";
+/** Tooltip of the apply button — adw-entry-row.ui. */
+export declare const ENTRY_ROW_APPLY_TOOLTIP = "Apply";
+/** Peek-button icon while the password is masked — adw-password-entry-row.c:74. */
+export declare const PASSWORD_REVEAL_ICON_NAME = "view-reveal-symbolic";
+/** Peek-button icon while the password is revealed — adw-password-entry-row.c:69. */
+export declare const PASSWORD_CONCEAL_ICON_NAME = "view-conceal-symbolic";
+/** Peek-button tooltip while the password is masked — adw-password-entry-row.c:76. */
+export declare const PASSWORD_REVEAL_LABEL = "Show Password";
+/** Peek-button tooltip while the password is revealed — adw-password-entry-row.c:71. */
+export declare const PASSWORD_CONCEAL_LABEL = "Hide Password";
+/** Caps-lock indicator icon — adw-password-entry-row.c:169. */
+export declare const CAPS_LOCK_ICON_NAME = "caps-lock-symbolic";
+/** Caps-lock indicator tooltip — adw-password-entry-row.c:171. */
+export declare const CAPS_LOCK_TOOLTIP = "Caps Lock is on";
+/**
+ * The number of CHARACTERS in `text`, i.e. what `adw_entry_row_get_text_length`
+ * reports ("The current number of characters in @self", adw-entry-row.c:1304).
+ *
+ * Code points, never UTF-16 units: a port that reaches for `.length` reports 3
+ * for `'🔒é'` where GTK reports 2, and then truncates a surrogate pair in half.
+ * This one function is why `max-length` and `text-length` cannot be left to the
+ * renderers.
+ */
+export declare function entryTextLength(text: string): number;
+/**
+ * Truncate `text` to `maxLength` CHARACTERS, with `0` meaning unlimited —
+ * `Adw.EntryRow:max-length` is documented as "Maximum number of characters for
+ * the entry" and both its default and its range floor are `0`
+ * (adw-entry-row.c:674 + :678-682).
+ *
+ * Split out of {@link EntryRowState} so a renderer can also apply it on an
+ * IME/paste path before the state sees the value.
+ */
+export declare function clampEntryText(text: string, maxLength: number): string;
+/**
+ * The complete render snapshot of an entry row: the five outputs of
+ * `update_empty` (adw-entry-row.c:149-154), the animation endpoint it drives
+ * (C:158-161), and the inputs a renderer echoes into CSS classes.
+ *
+ * ONE object rather than per-flag notifications so a renderer applies the whole
+ * derivation in a single pass and can never apply half of it.
+ */
+export interface EntryRowRenderState {
+    /** The entry contents (already truncated to `maxLength`). */
+    text: string;
+    /** {@link entryTextLength} of {@link text} — `Adw.EntryRow:text-length`. */
+    textLength: number;
+    /** `empty && !(focused && editable) && !text_changed` — C:154. Drives the placeholder title. */
+    empty: boolean;
+    /** Whether the embedded entry has focus — C:181. Renderers mirror it as the `focused` state class (C:183-186). */
+    editing: boolean;
+    /** Whether the embedded entry accepts edits (`GtkEditable:editable`). */
+    editable: boolean;
+    /** The pending-apply latch — C:170-172. */
+    textChanged: boolean;
+    /** `!text_changed && (!editing || !editable)` — C:149. */
+    editIconVisible: boolean;
+    /** `editable` — C:150. The pencil stays VISIBLE but goes insensitive on a read-only row. */
+    editIconSensitive: boolean;
+    /** `editing && show_indicator` — C:151. */
+    indicatorVisible: boolean;
+    /** `text_changed` — C:152. */
+    applyButtonVisible: boolean;
+    /**
+     * Where the empty↔filled transition is headed: `0` while {@link empty}, `1`
+     * otherwise — C:160-161. The renderer animates its OWN progress toward this
+     * over {@link EMPTY_ANIMATION_DURATION_MS}, starting from wherever the
+     * progress currently is (C:158-159 sets `value_from` to the live value), so
+     * an interrupted transition resumes instead of restarting.
+     */
+    emptyTarget: 0 | 1;
+}
+/**
+ * Per-instance subscriber for {@link EntryRowState}. Matches the
+ * `ExpanderState`/`ToggleGroupState` shape in rows.ts — the change carries no
+ * `interactive` flag, see the module header for why.
+ */
+export type EntryRowStateListener = (state: EntryRowRenderState) => void;
+/**
+ * What <kbd>Enter</kbd> resolves to. A discriminated union because
+ * `text_activated_cb` (adw-entry-row.c:243-266) emits exactly ONE of the two
+ * signals, never both; `activateDefault` carries the ordering requirement that
+ * the default widget is activated BEFORE `entry-activated` is emitted (the
+ * `gtk_widget_activate_default` call is C:254, the `g_signal_emit` is C:256).
+ */
+export type EntryRowActivation = {
+    signal: 'apply';
+} | {
+    signal: 'entry-activated';
+    activateDefault: boolean;
+};
+/**
+ * `Adw.EntryRow`'s derivation, headless: the `update_empty` truth table, the
+ * `text_changed` latch with both of its reset paths, character-counted
+ * max-length truncation, and the two-way <kbd>Enter</kbd> dispatch.
+ *
+ * The setter guards are NOT uniform, and that is faithful rather than sloppy:
+ * {@link setShowApplyButton} early-outs on an unchanged value and retracts a
+ * pending latch when turned off (C:982-995), while {@link setShowIndicator}
+ * deliberately has NO equality guard and always re-derives (C:1281-1296) — it is
+ * the private `adw-entry-row-private.h` hook the password row drives, not a
+ * public property, which is why it returns `void`.
+ */
+export declare class EntryRowState {
+    private _text;
+    private _maxLength;
+    private _editing;
+    private _editable;
+    private _showApplyButton;
+    private _showIndicator;
+    private _textChanged;
+    private _activatesDefault;
+    private readonly _listeners;
+    /** Subscribe to render-state changes. Returns an unsubscribe function. */
+    subscribe(listener: EntryRowStateListener): () => void;
+    /** Re-run `update_empty` and push the fresh snapshot to every subscriber. */
+    private _update;
+    /** The current render snapshot — `update_empty`'s outputs, freshly derived. */
+    get state(): EntryRowRenderState;
+    /** The entry contents. */
+    get text(): string;
+    /**
+     * Set the contents (truncated to {@link maxLength}) and run the latch +
+     * derivation, exactly as the buffer's `changed` signal does — C:166-174.
+     *
+     * Idempotent on an identical value. GTK routes this through GtkEntryBuffer,
+     * whose emission for a same-value set is a GtkText internal this checkout
+     * has no source for (`refs/gtk` is empty), so the headless contract is the
+     * house convention — and it is what a renderer's `input`/`textChange` event
+     * produces anyway, since neither platform fires one without a real edit.
+     *
+     * Returns whether the text changed.
+     */
+    setText(text: string): boolean;
+    /** `text_changed_cb` — latch iff the apply button is armed AND we are editing (C:170-171), then re-derive (C:173). */
+    private _latchAndUpdate;
+    /** {@link entryTextLength} of the contents — `Adw.EntryRow:text-length` (C:1308-1318). */
+    get textLength(): number;
+    /** Maximum number of CHARACTERS, `0` = unlimited (C:674, :678-682). */
+    get maxLength(): number;
+    /**
+     * Set the maximum length, clamped into `[0, ENTRY_ROW_MAX_LENGTH_LIMIT]`
+     * (C:678-682). Over-long contents are truncated immediately, which runs the
+     * same latch + derivation a buffer edit does.
+     *
+     * Returns whether the property changed. Upstream emits NO `notify` here
+     * (there is no `g_object_notify_by_pspec` in C:1329-1343) — pinned by a
+     * vector so a port does not "helpfully" add one.
+     */
+    setMaxLength(maxLength: number): boolean;
+    /** Whether the embedded entry has focus — `priv->editing` (C:181). */
+    get editing(): boolean;
+    /** Feed the focus state in and re-derive — `text_state_flags_changed_cb` (C:176-189). Returns whether it changed. */
+    setEditing(editing: boolean): boolean;
+    /** Whether the embedded entry accepts edits (`GtkEditable:editable`). */
+    get editable(): boolean;
+    /** Set editability and re-derive — the `notify::editable` → `update_empty` binding in adw-entry-row.ui. Returns whether it changed. */
+    setEditable(editable: boolean): boolean;
+    /** Whether typing reveals an apply button — `Adw.EntryRow:show-apply-button`. */
+    get showApplyButton(): boolean;
+    /**
+     * Arm/disarm the apply button (C:982-995). Turning it OFF retracts a pending
+     * apply (C:989-992); turning it ON changes no derived output, which is why
+     * the C re-derives only in the retract branch.
+     *
+     * Returns whether the property changed — the caller's cue to re-emit
+     * `notify::show-apply-button`.
+     */
+    setShowApplyButton(show: boolean): boolean;
+    /**
+     * The private indicator hook — `adw_entry_row_set_show_indicator`
+     * (adw-entry-row-private.h, C:1281-1296). `void` and UNGUARDED on purpose:
+     * the C assigns and calls `update_empty` unconditionally, with no equality
+     * check, so a redundant call still re-derives and still notifies.
+     *
+     * `Adw.PasswordEntryRow` is the only caller upstream; a renderer reaches it
+     * through {@link PasswordEntryRowState}.
+     */
+    setShowIndicator(show: boolean): void;
+    /** Whether <kbd>Enter</kbd> may activate the default widget — `Adw.EntryRow:activates-default`. */
+    get activatesDefault(): boolean;
+    /**
+     * Set `activates-default` (C:1238-1253). Returns whether it changed — the
+     * caller's cue to re-emit `notify::activates-default`.
+     *
+     * The C compares the raw `gboolean` because GValue already normalised it;
+     * a JS caller has no such guarantee, so coerce first.
+     */
+    setActivatesDefault(value: boolean): boolean;
+    /** The pending-apply latch (C:170-172) — `true` while the apply button is showing. */
+    get textChanged(): boolean;
+    /**
+     * Clear the latch and re-derive — `apply_button_clicked_cb` (C:237-238). The
+     * renderer emits `apply` right after (C:240); focus handling (C:234-235) is
+     * a platform concern and stays there.
+     */
+    apply(): void;
+    /**
+     * <kbd>Enter</kbd> — `text_activated_cb` (C:243-266). Dispatches to the
+     * apply path when the apply button is showing (C:248-249), otherwise reports
+     * `entry-activated` plus whether the default widget must be activated FIRST
+     * (C:253-256).
+     *
+     * The `GtkActionable` action fired afterwards (C:258-264) has no headless
+     * equivalent and stays with the renderer.
+     */
+    activate(): EntryRowActivation;
+}
+/**
+ * The render snapshot of a password entry row: `notify_visibility_cb`'s icon +
+ * tooltip pair (adw-password-entry-row.c:62-81) plus the caps-lock inputs, as
+ * data.
+ *
+ * The icon names and English strings are the literals from the C source, so the
+ * two renderers stop inventing their own spellings (`revealed` vs `peeking`,
+ * `view-reveal` vs `viewRevealSymbolic`) and a renderer can map ONE canonical
+ * name onto whatever asset it actually ships.
+ */
+export interface PasswordEntryRowRenderState {
+    /** Whether the contents are shown in clear text (`GtkText:visibility`). */
+    revealed: boolean;
+    /** Whether the keyboard reports Caps Lock engaged (`gdk_device_get_caps_lock_state`). */
+    capsLockOn: boolean;
+    /** Icon the peek button shows — C:68,73. */
+    peekIconName: typeof PASSWORD_REVEAL_ICON_NAME | typeof PASSWORD_CONCEAL_ICON_NAME;
+    /** Tooltip/accessible label of the peek button — C:71,76. */
+    peekLabel: typeof PASSWORD_REVEAL_LABEL | typeof PASSWORD_CONCEAL_LABEL;
+    /** Icon of the caps-lock indicator — C:169. Constant, exposed so a renderer reads one object. */
+    indicatorIconName: typeof CAPS_LOCK_ICON_NAME;
+    /** Tooltip of the caps-lock indicator — C:171. */
+    indicatorTooltip: typeof CAPS_LOCK_TOOLTIP;
+}
+/** Per-instance subscriber for {@link PasswordEntryRowState}. */
+export type PasswordEntryRowStateListener = (state: PasswordEntryRowRenderState) => void;
+/**
+ * `Adw.PasswordEntryRow`'s extra behaviour, headless: the reveal/conceal pair
+ * and the caps-lock warning with BOTH of its suppression rules.
+ *
+ * COMPOSES an {@link EntryRowState} rather than extending it, mirroring the C:
+ * `AdwPasswordEntryRow` is a subclass but reaches its parent through the private
+ * `adw_entry_row_set_show_indicator` hook, not a protected field. Composition
+ * also keeps `EntryRowState` usable on its own for a plain entry row.
+ *
+ * Every reveal/caps-lock change recomputes `!revealed && capsLockOn` and pushes
+ * it into the entry (C:57-59) — which is why peeking makes the caps-lock warning
+ * disappear. The second suppression is the entry's own (`editing && show_indicator`,
+ * C:151): the warning only shows while the entry has focus. Focus changes
+ * therefore need no push from here — they re-derive on the entry side, which is
+ * what `notify_has_focus_cb` (C:83-88) achieves by re-running `update_caps_lock`.
+ */
+export declare class PasswordEntryRowState {
+    private readonly _entry;
+    private _revealed;
+    private _capsLockOn;
+    private readonly _listeners;
+    constructor(entry: EntryRowState);
+    /** Subscribe to peek/caps-lock changes. Returns an unsubscribe function. */
+    subscribe(listener: PasswordEntryRowStateListener): () => void;
+    private _emit;
+    /** The current render snapshot — `notify_visibility_cb`'s derivation (C:62-81). */
+    get state(): PasswordEntryRowRenderState;
+    /** Whether the contents are shown in clear text. */
+    get revealed(): boolean;
+    /**
+     * Set the peek state. Early-outs on an unchanged value — every settable
+     * property in this family does (C:984, :1198, :1247), which is why the web
+     * port's unguarded `notify::revealed` on a redundant `setAttribute` is a
+     * defect and not a style choice.
+     *
+     * Returns whether it changed.
+     */
+    setRevealed(revealed: boolean): boolean;
+    /** Flip masked↔revealed — `show_text_clicked_cb` (C:94-96). Returns whether it changed. */
+    togglePeek(): boolean;
+    /** Whether Caps Lock is engaged. */
+    get capsLockOn(): boolean;
+    /**
+     * Feed the keyboard's caps-lock state in — the `notify::caps-lock-state`
+     * handler (C:111-115). Returns whether it changed.
+     */
+    setCapsLockOn(on: boolean): boolean;
+    /** `update_caps_lock` — C:57-59. */
+    private _pushIndicator;
+}

package/lib/types/entry-row.spec.d.ts

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

package/lib/types/glib.d.ts

@@ -0,0 +1,49 @@
+/**
+ * GLib's `g_strstrip` — trim ASCII whitespace from both ends, and ONLY ASCII
+ * whitespace.
+ *
+ * NOT `String.prototype.trim()`, which also eats U+00A0 NBSP, U+FEFF and the
+ * Unicode space separators. Two widgets already depend on the difference:
+ * `Adw.Avatar` derives its initials from the stripped name, so a name that
+ * starts with U+00A0 keeps the NBSP as its initial in GTK, where a
+ * `trim()`-based port yields the first LETTER instead; and
+ * `Adw.AboutDialog`'s `parse_person` (adw-about-dialog.c:533) strips the credit
+ * name the same way, so an NBSP-padded contributor name keeps its padding.
+ */
+export declare function gStrStrip(value: string): string;
+/**
+ * libadwaita's `string_is_not_empty` template closure — the predicate EVERY
+ * Adwaita label binds its `visible` property to.
+ *
+ * `return string && string[0];` — verbatim in six widgets that each declare
+ * their own private copy (`adw-action-row.c:112-117`, `adw-button-row.c:92-97`,
+ * `adw-sidebar.c`, `adw-shortcut-row.c`, `adw-status-page.c`,
+ * `adw-toast-widget.c`), bound from the matching `.ui`
+ * (`adw-action-row.ui:49-53` for the title, `:71-75` for the subtitle).
+ *
+ * Two properties of it are load-bearing and are what a hand-rolled copy gets
+ * wrong: only the EXACT empty string (and NULL) is false — one space is a
+ * visible label, because the C never trims — and the rule applies to the TITLE
+ * as much as to the subtitle. Every port so far hid an empty subtitle and left
+ * an empty title occupying a line.
+ */
+export declare function stringIsNotEmpty(value: string | null | undefined): boolean;
+/**
+ * GLib's `CLAMP`, which tests the HIGH bound FIRST:
+ * `x > high ? high : (x < low ? low : x)`.
+ *
+ * NOT interchangeable with `Math.min(high, Math.max(low, x))` — the two disagree
+ * whenever the bounds are inverted, and Adwaita reaches inverted bounds for
+ * real: a split view's sidebar caps invert whenever the content minimum exceeds
+ * what is left of the width.
+ */
+export declare function glibClamp(x: number, low: number, high: number): number;
+/**
+ * Drop GTK mnemonic markers from a label (`gtk_label_new_with_mnemonic`).
+ *
+ * A single `_` marks the character after it and is itself removed; `__` is an
+ * escaped literal underscore. A renderer with no accelerator layer wants the
+ * plain text, which is what this returns — GTK would underline the marked
+ * character instead.
+ */
+export declare function stripMnemonic(text: string): string;