@gjsify/adwaita-core 0.36.0 → 0.37.0

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

@@ -33,12 +33,10 @@ export interface AdwDataGridRow {
     [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.
+ * One column track, in renderer-neutral terms. `fixed` carries the author's CSS length
+ * UNPARSED, because only a browser can resolve every unit CSS has: 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.
  */
 export type DataGridTrack = 
 /** A pinned track: the `width` string exactly as the column declared it. */
@@ -66,56 +64,51 @@ 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.
+ * `width` pins a track and `flex` weights one, each on its own column. The third rule 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 — the statement shape, one label
+ * column taking what is left and trailing figures hugging the right edge. One declared
+ * size anywhere turns the rule off for every column, so 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`.
+ * 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` carries
+ * its unit because 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.
+ * 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.
+ * 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.
+ * `numeric` IS libadwaita's own label class (`font-variant-numeric: tabular-nums`);
+ * `mono` is this widget's cell class, which `@extend`s upstream's `.monospace` on top of
+ * the tabular figures. A renderer whose stylesheet cannot express the font 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.
+ * `align` is NOT clamped to {@link AdwDataGridAlign}, so a value outside the union
+ * produces a class no stylesheet claims and the cell falls back to the base rule —
+ * 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`.
+ * 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'). */
@@ -125,16 +118,13 @@ export declare function normalizeDataGridColumns(raw: unknown): AdwDataGridColum
 /**
  * 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.
+ * 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. The per-row flag then wins over the grid-level one in BOTH directions:
+ * `false` opts a single row out of a fully interactive grid, `true` opts one into an
+ * otherwise inert grid.
  *
- * `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.
+ * `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.
  */
 export declare function dataGridRowInteractive(variant: AdwDataGridRowVariant, rowFlag: unknown, gridInteractive: boolean): boolean;

package/lib/types/dialog.d.ts

@@ -101,9 +101,8 @@ export declare class AdwAlertResponses {
 /**
  * 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.
+ * Not interchangeable: the C 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`).
@@ -135,28 +134,22 @@ export interface BottomSheetCloseState {
  * 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:
+ * Three rows are worth reading twice:
  *
  * - `('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.
+ *   `can_focus = FALSE` + `can_target = FALSE`, so it cannot be clicked at all; its only
+ *   behavioural role is elsewhere (`allow_mouse_drag = show_drag_handle || bottom_bar`). It
+ *   is NOT a close button.
  * - `('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.
+ *   `maybe_close_cb` 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`
+ *   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.
+ * 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`,
+ * and `prepare_cb` refuses to even detect a swipe unless the direction matches the state.
+ * 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. */
@@ -165,13 +158,12 @@ export type BottomSheetTeardownCallback = 'closing' | 'closed';
 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:
+ * (`adw_bottom_sheet_set_callbacks`). 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.
+ * - `onClosing` fires when the close STARTS — `AdwDialog` turns it into the public
+ *   `AdwDialog::closed` signal.
+ * - `onClosed` fires when the sheet has finished hiding — `AdwDialog` turns it into the
+ *   dialog's removal from the widget tree.
  */
 export interface BottomSheetPresentationOptions {
     /** The close started (`closing_callback`). */
@@ -184,12 +176,10 @@ export interface BottomSheetPresentationOptions {
  * 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()`).
+ * `setOpen` is the PROGRAMMATIC path and deliberately ignores `can-close` ("Bottom sheet can
+ * still be closed using [property@BottomSheet:open]"); {@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.
  */
 export declare class BottomSheetPresentation {
     private _open;
@@ -208,37 +198,35 @@ export declare class BottomSheetPresentation {
     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).
+     * {@link setOpen}; `has_been_open` in the C source.
      */
     get hasBeenOpen(): boolean;
-    /** Set `can-close`. Returns whether it changed (adw-bottom-sheet.c:2076-2091). */
+    /** Set `can-close`. Returns whether it changed. */
     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.
+     * The programmatic open/close — `adw_bottom_sheet_set_open`. 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).
+     * `adw_dialog_force_close` closes a locked dialog.
      */
     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.
+     * 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 sheet has finished hiding — `open_animation_done_cb`'s teardown 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.
+     * 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/easing.d.ts

@@ -1,21 +1,15 @@
-/** `adw_lerp` (adw-animation-util.c:23-27) — `a * (1 - t) + b * t`. */
+/** `adw_lerp` — `a * (1 - t) + b * t`. */
 export declare function adwLerp(a: number, b: number, t: number): number;
 /**
- * The inverse: where `r` sits between `a` and `b`, as a 0..1 fraction.
- *
- * Not a libadwaita function — C writes the division inline — but it is the same
- * expression at every call site, and naming it is what keeps the two directions
- * from drifting apart.
+ * The inverse: where `r` sits between `a` and `b`, as a 0..1 fraction. Not a
+ * libadwaita function — C writes the division inline at each call site.
  */
 export declare function inverseLerp(a: number, b: number, r: number): number;
 /** `ease_out_cubic` (adw-easing.c) — `(t - 1)^3 + 1`. */
 export declare function easeOutCubic(t: number): number;
 /**
- * `ease_in_out_sine` (adw-easing.c:276-281) — `-0.5 * (cos(pi * t) - 1)`, with
- * the duration argument at its only used value, 1.
- *
- * This is the curve the spinner's arc breathes on, at BOTH ends: `get_arc_start`
- * eases the extend phase and `get_arc_end` the contract phase
- * (adw-spinner-paintable.c:121, :141).
+ * `ease_in_out_sine` — `-0.5 * (cos(pi * t) - 1)`, with the duration argument at its
+ * only used value, 1. The curve the spinner's arc breathes on at BOTH ends:
+ * `get_arc_start` eases the extend phase, `get_arc_end` the contract phase.
  */
 export declare function easeInOutSine(t: number): number;