@gjsify/adwaita-core 0.36.0 → 0.37.0

package/lib/types/checks.d.ts

@@ -1,25 +1,17 @@
 /**
- * The three states a check or radio can be in.
- *
- * `indeterminate` is not "checked plus a flag": it paints its own glyph, and it
- * maps to a distinct a11y value (`aria-checked="mixed"`), so a renderer that
- * models the pair as two booleans has to re-derive the precedence every time it
- * needs to answer "what does this look like / sound like right now".
+ * The three states a check or radio can be in. `indeterminate` paints its own
+ * glyph and maps to `aria-checked="mixed"`, so it is a state and not a flag.
  */
 export type AdwCheckState = 'unchecked' | 'checked' | 'indeterminate';
 /**
  * Collapse the `checked` / `indeterminate` pair into the one state that paints.
- *
- * Indeterminate WINS, including over checked — see the module header for the
- * cascade reading that settles it (_checks.scss:79-81 re-declares the glyph
- * after both `:checked` rules, at equal specificity).
+ * Indeterminate wins over checked — _checks.scss re-declares the glyph
+ * after both `:checked` rules, at equal specificity.
  */
 export declare function resolveCheckState(checked: boolean, indeterminate: boolean): AdwCheckState;
 /** Payload of a {@link RadioGroupState} change — both halves of one exclusive move. */
 export interface RadioGroupChange {
-    /** The group the move happened in. */
     name: string;
-    /** The value that is now selected. */
     selected: string;
     /** The value that just lost the selection, or `null` when the group was empty. */
     deselected: string | null;
@@ -29,22 +21,14 @@ export type RadioGroupListener = (change: RadioGroupChange) => void;
 /**
  * Which value is selected in each named radio group.
  *
- * ONE registry over MANY groups, keyed by name, because that is the shape the
- * renderers need: a radio knows its own group NAME, not its siblings, exactly as
- * `<input type="radio" name="…">` does. Two independent groups therefore need
- * two names — the registry is as global as its host (one instance per document
- * in `@gjsify/adwaita-web`).
- *
- * {@link select} notifies ONCE per move, carrying the value that gained the
- * selection and the one that lost it, so a renderer repaints both members off a
- * single event. Re-selecting the value already held is a no-op and notifies
- * nothing — a user clicking a checked radio twice must not produce a second
- * event, and must never end up with nothing selected (HTML radios cannot be
- * unchecked by clicking either).
+ * One registry over many groups keyed by name, because a radio knows its own group NAME
+ * and not its siblings, exactly as `<input type="radio" name="…">` does. As global as
+ * its host — one instance per document in `@gjsify/adwaita-web`.
  *
- * A group nobody has picked in reports `null`. Whether GTK instead activates the
- * first member of a group is NOT verifiable here (see the module header), so
- * this reports the state it actually has rather than inventing a default.
+ * {@link select} notifies once per move carrying both halves, so a renderer repaints the
+ * loser too. Re-selecting the held value is a no-op: clicking a checked radio twice must
+ * not fire twice, and must never leave the group empty (HTML radios cannot be unchecked
+ * by clicking).
  */
 export declare class RadioGroupState {
     private readonly _selected;
@@ -55,9 +39,8 @@ export declare class RadioGroupState {
     /** The value selected in `name`, or `null` when nothing is selected there. */
     selected(name: string): string | null;
     /**
-     * Select `value` in group `name`, deselecting whatever was selected there.
-     *
-     * Returns whether the selection actually moved; a no-op notifies nothing.
+     * Select `value` in group `name`, deselecting whatever was selected there. Returns
+     * whether the selection actually moved; a no-op notifies nothing.
      */
     select(name: string, value: string): boolean;
 }

package/lib/types/chrome.d.ts

@@ -1,11 +1,10 @@
 /**
- * The inputs every clamp computation needs: the two properties plus the child's
- * measured minimum and natural size in the clamp's own orientation.
+ * The inputs every clamp computation needs: the two properties plus the child's measured
+ * minimum and natural size in the clamp's own orientation.
  *
- * Sizes are already-resolved PIXELS. `AdwClampLayout:unit` (default `sp`) scales
- * them against the GTK text-scale factor, which is a platform capability rather
- * than headless logic — a renderer that has one runs `adwLengthToPx` (exported
- * from `./split-view.js`) before calling in.
+ * Sizes are already-resolved PIXELS. `AdwClampLayout:unit` (default `sp`) scales them
+ * against the GTK text-scale factor, a platform capability rather than headless logic — a
+ * renderer that has one runs `adwLengthToPx` (from `./length-unit.js`) before calling in.
  */
 export interface ClampParams {
     /** `maximum-size` — how wide the child may get. Default 600. */
@@ -17,7 +16,7 @@ export interface ClampParams {
     /** The child's measured natural size in the clamped orientation. */
     childNat: number;
 }
-/** The libadwaita property defaults (adw-clamp-layout.c:414, :438, :462-464). */
+/** The libadwaita property defaults. */
 export declare const ADW_CLAMP_DEFAULTS: {
     readonly maximumSize: number;
     readonly tighteningThreshold: number;
@@ -32,46 +31,34 @@ export interface ClampThresholds {
     upper: number;
 }
 /**
- * `lower`/`max`/`upper` (adw-clamp-layout.c:173-176, :210-213).
- *
- * Exported because both the measure and the allocate path need them, and
- * because the two cases the renderers got wrong live entirely in these three
- * lines: a threshold ABOVE the maximum collapses the tightening region
- * (`lower === max === upper`), and a child whose own minimum exceeds the maximum
- * raises all three to that minimum — which is how `maximum-size="0"` means "give
- * the child its minimum", not "give it nothing".
+ * `lower`/`max`/`upper`. Exported because both the measure and the allocate path need
+ * them, and because the two easily-missed cases live in these three lines: a threshold
+ * ABOVE the maximum collapses the tightening region (`lower === max === upper`), and a
+ * child whose own minimum exceeds the maximum raises all three to that minimum — which
+ * is how `maximum-size="0"` means "give the child its minimum", not "give it nothing".
  */
 export declare function clampThresholds(params: ClampParams): ClampThresholds;
 /**
- * `child_size_from_clamp` (adw-clamp-layout.c:193-232) — how much of `forSize`
- * the child is allocated.
- *
- * The result is never larger than `forSize`, which is the whole point and what
- * `view.width = maximumSize` in the NativeScript port broke: below `lower` the
- * child gets EXACTLY the available size, so a narrow phone gets a narrow child.
- * The cap only bites from `upper` upward; between the two the size is eased so
- * the transition into the cap is smooth rather than a corner.
+ * `child_size_from_clamp` — how much of `forSize` the child is allocated. The result is
+ * never larger than `forSize`: below `lower` the child gets EXACTLY the available size,
+ * so a narrow phone gets a narrow child. The cap only bites from `upper` upward;
+ * between the two the size is eased so the transition into it is smooth.
  */
 export declare function clampChildSize(forSize: number, params: ClampParams): number;
 /**
- * `clamp_size_from_child` (adw-clamp-layout.c:156-191) — the INVERSE, used while
- * measuring: how much space the clamp itself must report for the child to end up
- * at `childSize`.
- *
- * The inverse of `ease_out_cubic` is `1 + cbrt(t - 1)`, and the rounding goes the
- * OTHER way from {@link clampChildSize} (`ceil`, not `floor`) so the reported
- * request never lands a pixel short of what the child asked for.
+ * `clamp_size_from_child` — the INVERSE, used while measuring: how much space the clamp
+ * must report for the child to end up at `childSize`. The inverse of `ease_out_cubic` is
+ * `1 + cbrt(t - 1)`, and the rounding goes the OTHER way from {@link clampChildSize}
+ * (`ceil`, not `floor`) so the reported request never lands a pixel short.
  */
 export declare function clampSizeFromChild(childSize: number, params: ClampParams): number;
 /** Which of the three size classes `adw_clamp_layout_allocate` stamps on the child. */
 export type AdwClampSizeClass = 'small' | 'medium' | 'large';
 /**
- * All three size classes, so a renderer can CLEAR the ones that no longer apply.
- *
- * `adw_clamp_layout_allocate` removes the other two on every pass and removes
- * all three from a child it stops laying out (adw-clamp-layout.c:333-336), so
- * "which classes does the clamp own" is part of the contract, not a detail each
- * renderer gets to restate.
+ * All three size classes, so a renderer can CLEAR the ones that no longer apply:
+ * `adw_clamp_layout_allocate` removes the other two on every pass and all three from a
+ * child it stops laying out, so "which classes does the clamp own" is part of the
+ * contract.
  */
 export declare const ADW_CLAMP_SIZE_CLASSES: ReadonlyArray<AdwClampSizeClass>;
 /** Everything one clamp allocation decides. */
@@ -88,34 +75,26 @@ export interface ClampAllocation {
     offset: number;
 }
 /**
- * `adw_clamp_layout_allocate` (adw-clamp-layout.c:317-386) — child size, the
- * style class the child carries, and the centring offset, in one call.
- *
- * The class boundaries are INCLUSIVE at both ends and are compared against the
- * CEILED thresholds, not the raw doubles; the offset is C integer division, so
- * it truncates rather than rounds.
+ * `adw_clamp_layout_allocate` — child size, the style class the child carries and the
+ * centring offset, in one call. The class boundaries are INCLUSIVE at both ends and are
+ * compared against the CEILED thresholds, not the raw doubles; the offset is C integer
+ * division, so it truncates rather than rounds.
  */
 export declare function clampAllocate(availableSize: number, params: ClampParams): ClampAllocation;
 /**
- * Normalise a `maximum-size` / `tightening-threshold` coming from an attribute
- * or a property assignment into the `g_param_spec_int (…, 0, G_MAXINT, …)` range
- * both properties declare (adw-clamp-layout.c:413-416, :448-451).
- *
- * Three inputs used to produce three different results across the three
- * implementations, and this is the one answer for all of them:
- *   - `0` is IN RANGE and means "clamp the child to its own minimum". The web
- *     port's `attr || '600'` never fired for the string `"0"` and produced
- *     `max-width: 0`; the NS port's `value > 0` guard silently substituted 600.
- *   - a value GObject would refuse (`NaN`, a non-numeric attribute) never
- *     reaches the layout, so the property keeps its DEFAULT. The web port
- *     assigned `NaNpx`, which the CSSOM drops — leaving whatever cap was set
- *     before silently in force.
- *   - a negative is out of range and clamps to the range floor, 0.
+ * Normalise a `maximum-size` / `tightening-threshold` from an attribute or a property
+ * assignment into the `g_param_spec_int (…, 0, G_MAXINT, …)` range both properties
+ * declare:
+ * - `0` is IN RANGE and means "clamp the child to its own minimum" — not "no width",
+ * and not a missing value to substitute the default for;
+ * - a value GObject would refuse (`NaN`, a non-numeric attribute) never reaches the
+ * layout, so the property keeps its DEFAULT;
+ * - a negative is out of range and clamps to the range floor, 0.
  */
 export declare function normalizeClampSize(value: number | string | null | undefined, fallback: number): number;
-/** `AdwToolbarStyle` (adw-toolbar-view.c:120-125). */
+/** `AdwToolbarStyle`. */
 export type AdwToolbarStyle = 'flat' | 'raised' | 'raised-border';
-/** The toolbar-view property defaults (adw-toolbar-view.c:572, :608, :731-732). */
+/** The toolbar-view property defaults. */
 export declare const ADW_TOOLBAR_VIEW_DEFAULTS: {
     readonly topBarStyle: AdwToolbarStyle;
     readonly bottomBarStyle: AdwToolbarStyle;
@@ -123,19 +102,15 @@ export declare const ADW_TOOLBAR_VIEW_DEFAULTS: {
     readonly extendContentToBottomEdge: boolean;
 };
 /**
- * Read an `AdwToolbarStyle` off an attribute or a property assignment.
- *
- * Anything outside the enum is the default: C rejects it outright
- * (`g_return_if_fail (style <= ADW_TOOLBAR_RAISED_BORDER)`,
- * adw-toolbar-view.c:1004) and leaves the property at whatever it was.
+ * Read an `AdwToolbarStyle` off an attribute or a property assignment. Anything outside
+ * the enum is the default: C rejects it outright
+ * (`g_return_if_fail (style <= ADW_TOOLBAR_RAISED_BORDER)`) and leaves the property as it
+ * was.
  */
 export declare function parseToolbarStyle(value: string | null | undefined): AdwToolbarStyle;
 /**
- * The style classes a bar box carries for `style`
- * (adw-toolbar-view.c:1011-1024, :1097-1110).
- *
- * `raised-border` is `raised` PLUS `border` — the border replaces the shadow in
- * the stylesheet, it does not replace the raised background.
+ * The style classes a bar box carries for `style`. `raised-border` is `raised` PLUS
+ * `border` — the border replaces the shadow in the stylesheet, not the raised background.
  */
 export declare function toolbarBarStyleClasses(style: AdwToolbarStyle): string[];
 /** Everything `update_undershoots` + the two style setters need to decide the classes. */
@@ -167,14 +142,13 @@ export interface ToolbarViewClasses {
     bottomBar: string[];
 }
 /**
- * `update_undershoots` (adw-toolbar-view.c:215-232) plus the two per-bar style
- * class setters, as one derivation.
+ * `update_undershoots` plus the two per-bar style class setters, as one derivation.
  *
- * An undershoot is the scroll-fade under a FLAT bar, so all three conditions
- * must hold: the bar is flat (a raised bar has its own shadow), the content does
- * NOT extend under it (there is nothing to fade), and the bar was actually
- * allocated a height (an absent bar fades nothing). The height being the
- * ALLOCATED one — not "is there a bar widget" — is why this reads a number.
+ * An undershoot is the scroll-fade under a FLAT bar, so all three conditions must hold:
+ * the bar is flat (a raised bar has its own shadow), the content does NOT extend under it
+ * (nothing to fade), and the bar was actually allocated a height (an absent bar fades
+ * nothing). That the height is the ALLOCATED one, not "is there a bar widget", is why
+ * this reads a number.
  */
 export declare function toolbarViewClasses(input: ToolbarViewClassInput): ToolbarViewClasses;
 /** The measured sizes one toolbar-view allocation consumes. */
@@ -208,20 +182,16 @@ export interface ToolbarViewAllocation {
     contentOffset: number;
 }
 /**
- * `adw_toolbar_view_size_allocate` (adw-toolbar-view.c:357-406) — the two chained
- * GLib CLAMPs that turn measured sizes into the three slot heights.
- *
- * Read it as: reserve the content's minimum and the bottom bar's minimum, hand
- * what is left to the top bar (clamped into its own min…nat), then repeat for the
- * bottom bar with the top bar's ACTUAL height. Two consequences a naive
- * "stack them" layout does not reproduce:
- *   - a STRETCHY bar (`nat > min`) grows into spare height and shrinks back
- *     toward its minimum as the content's minimum claims the space;
- *   - once the view is squeezed below everything's minimum, GLib's `CLAMP` — which
- *     tests the HIGH bound first — leaves the BARS at their minimum and lets the
- *     CONTENT go short. `Math.min(high, Math.max(low, x))` gives the same answer
- *     here only because both bounds arrive in order; the primitive is
- *     {@link glibClamp} regardless, since the inputs are caller-supplied.
+ * `adw_toolbar_view_size_allocate` — the two chained GLib CLAMPs that turn measured
+ * sizes into the three slot heights: reserve the content's minimum and the bottom bar's
+ * minimum, hand what is left to the top bar (clamped into its own min…nat), then repeat
+ * for the bottom bar with the top bar's ACTUAL height. Two consequences a naive "stack
+ * them" layout does not reproduce:
+ * - a STRETCHY bar (`nat > min`) grows into spare height and shrinks back toward its
+ * minimum as the content's minimum claims the space;
+ * - once the view is squeezed below everything's minimum, GLib's `CLAMP` — which tests
+ * the HIGH bound first — leaves the BARS at their minimum and lets the CONTENT go
+ * short. {@link glibClamp} is used regardless, since the inputs are caller-supplied.
  */
 export declare function toolbarViewAllocate(input: ToolbarViewAllocateInput): ToolbarViewAllocation;
 /** The measured sizes one toolbar-view measure consumes. */
@@ -253,13 +223,11 @@ export interface AdwMeasurement {
     natural: number;
 }
 /**
- * `adw_toolbar_view_measure` (adw-toolbar-view.c:266-354) — the four-way vertical
- * combination keyed on the two extend flags, plus the horizontal MAX form.
- *
- * The four branches are not four spellings of the same sum: a bar the content
- * extends UNDER contributes via `MAX`, a bar it does not contributes via `+`.
- * With both flags set the two bars are summed first and MAXed as a pair, because
- * they still cannot overlap each other.
+ * `adw_toolbar_view_measure` — the four-way vertical combination keyed on the two extend
+ * flags, plus the horizontal MAX form. The branches are not four spellings of the same
+ * sum: a bar the content extends UNDER contributes via `MAX`, a bar it does not
+ * contributes via `+`. With both flags set the bars are summed first and MAXed as a
+ * pair, because they still cannot overlap each other.
  */
 export declare function toolbarViewMeasure(input: ToolbarViewMeasureInput): AdwMeasurement;
 /** The bar heights subtracted before the content is measured horizontally. */
@@ -285,26 +253,22 @@ export interface ToolbarViewContentForSize {
     forSizeNat: number;
 }
 /**
- * `adw_toolbar_view_measure`'s height-for-width branch (adw-toolbar-view.c:292-316).
- *
- * Two different `for_size` values, not one: a STRETCHY bar leaves the content a
- * different width at the bar's minimum than at its natural size, so the content's
- * minimum and natural have to be measured against different heights. They
- * coincide exactly when every bar is rigid, which is why one value looked
- * sufficient for as long as nobody had a stretchy bar.
+ * `adw_toolbar_view_measure`'s height-for-width branch. Two different `for_size` values,
+ * not one: a STRETCHY bar leaves the content a different width at the bar's minimum than
+ * at its natural size, so the content's minimum and natural must be measured against
+ * different heights. They coincide exactly when every bar is rigid.
  */
 export declare function toolbarViewContentForSize(forSize: number, input: ToolbarViewContentForSizeInput): ToolbarViewContentForSize;
 /**
- * `MIN_SIZE` (adw-spinner.c:14) — reported as BOTH the minimum and the natural
- * size (adw_spinner_measure, :70-84), so a spinner never grows on its own; it
- * only fills an allocation something else made larger.
+ * `MIN_SIZE` — reported as BOTH the minimum and the natural size (`adw_spinner_measure`),
+ * so a spinner never grows on its own; it only fills an allocation something else made
+ * larger.
  */
 export declare const ADW_SPINNER_MIN_SIZE = 16;
 /**
- * The largest ring Adwaita ever draws: `2 * MAX_RADIUS`
- * (adw-spinner-paintable.c:19). Together with {@link ADW_SPINNER_MIN_SIZE} this
- * is the documented "never smaller than 16×16 and never larger than 64×64"
- * (adw-spinner.c:27-28).
+ * The largest ring Adwaita ever draws: `2 * MAX_RADIUS`. With
+ * {@link ADW_SPINNER_MIN_SIZE} this is the documented "never smaller than 16×16 and
+ * never larger than 64×64".
  */
 export declare const ADW_SPINNER_MAX_SIZE = 64;
 /** The circle `AdwSpinnerPaintable` strokes into a `width × height` box. */
@@ -321,35 +285,25 @@ export interface SpinnerGeometry {
     centerY: number;
 }
 /**
- * `adw_spinner_paintable_snapshot_with_weight` (adw-spinner-paintable.c:342-352)
- * plus `calculate_line_width` (:314-321) at the default weight 400, where
- * `width_apply_weight` is the identity branch (:303-306).
+ * `adw_spinner_paintable_snapshot_with_weight` plus `calculate_line_width` at the default
+ * weight 400, where `width_apply_weight` is the identity branch. Three details:
+ * - the SHORTER side decides the radius, and it is FLOORED, so a 31px box draws a 30px
+ * ring rather than a 31px one;
+ * - the radius is capped at 32 while the CENTRE still follows the box, so a 200px
+ * allocation shows a 64px ring in the middle, not a 200px one;
+ * - the stroke is `diameter / 8` exactly — 3px at 24, 6px at 48, 8px at 64.
  *
- * Three details the renderers had each guessed at:
- *   - the SHORTER side decides the radius, and it is FLOORED, so a 31px box
- *     draws a 30px ring rather than a 31px one;
- *   - the radius is capped at 32 while the CENTRE still follows the box, so a
- *     200px allocation shows a 64px ring in the middle, not a 200px one;
- *   - the stroke is `diameter / 8` exactly — 3px at 24, 6px at 48, 8px at 64.
- *     The browser port's `max(2, round(size / 12))` drew 2px, 4px and 5px there.
- *
- * `MIN_RADIUS 8` (adw-spinner-paintable.c:18) is dead in the C source — nothing
- * references it — so it is deliberately NOT a floor here. The real floor is the
- * widget's measured {@link ADW_SPINNER_MIN_SIZE}.
+ * `MIN_RADIUS 8` is dead in the C source — nothing references it — so it is deliberately
+ * NOT a floor here. The real floor is the widget's measured
+ * {@link ADW_SPINNER_MIN_SIZE}.
  */
 export declare function spinnerGeometry(width: number, height: number): SpinnerGeometry;
 /**
- * The box a spinner is actually given for a requested `size`.
- *
- * `adw_spinner_measure` reports 16 as the minimum, and GTK never allocates a
- * widget below its minimum — so a smaller request is not representable, and a
- * request GObject would refuse (`NaN`, a non-numeric attribute, an unset one)
- * leaves the natural size in force. There is no upper bound HERE: an oversized
- * allocation stays oversized and {@link spinnerGeometry} caps the drawn ring,
- * which is how the box and the ring can differ (a 200px allocation, a 64px ring).
- *
- * Replaces the two invented defaults this package shipped — `24` in the browser
- * element and `32` in the NativeScript widget — neither of which is in the C
- * source.
+ * The box a spinner is actually given for a requested `size`. `adw_spinner_measure`
+ * reports 16 as the minimum and GTK never allocates below a minimum, so a smaller
+ * request is not representable, and a request GObject would refuse (`NaN`, a non-numeric
+ * or unset attribute) leaves the natural size in force. No upper bound HERE: an oversized
+ * allocation stays oversized and {@link spinnerGeometry} caps the drawn ring, which is
+ * how a 200px box can hold a 64px ring.
  */
 export declare function resolveSpinnerSize(value: number | string | null | undefined): number;

package/lib/types/color-scheme.d.ts

@@ -8,9 +8,8 @@ export type AdwColorScheme = 'light' | 'dark';
 export declare function adwaitaColorScheme(): AdwColorScheme;
 /**
  * Set the active color scheme. A no-op when unchanged; otherwise notifies every
- * subscriber (so theme-aware icons re-render). The renderer should also apply
- * its platform half (e.g. the `ns-dark` class on NativeScript, a CSS scope in
- * the browser).
+ * subscriber (so theme-aware icons re-render). The renderer must also apply its platform
+ * half — the `ns-dark` class on NativeScript, a CSS scope in the browser.
  */
 export declare function setAdwaitaColorScheme(scheme: AdwColorScheme): void;
 /** Flip light↔dark and return the new scheme. */
@@ -20,8 +19,8 @@ export declare function themeIconColor(): string;
 /** Whether `color` is the current scheme-default fill (i.e. not a caller-set explicit colour). */
 export declare function isThemeIconColor(color: string): boolean;
 /**
- * Subscribe to scheme changes. Returns an unsubscribe function. Widgets should
- * subscribe while on screen and unsubscribe when leaving it (e.g. NS `loaded` /
- * `unloaded`), so the registry only ever holds live subscribers.
+ * Subscribe to scheme changes. Returns an unsubscribe function. Widgets subscribe while
+ * on screen and unsubscribe when leaving it (NS `loaded`/`unloaded`), so the registry
+ * only ever holds live subscribers.
  */
 export declare function onAdwaitaColorSchemeChanged(listener: () => void): () => void;