@gjsify/adwaita-core 0.32.0 → 0.34.0

package/lib/types/spinner.d.ts

@@ -0,0 +1,117 @@
+/** `SPIN_DURATION_MS` (adw-spinner-paintable.c:20) — one full turn. */
+export declare const ADW_SPINNER_SPIN_DURATION_MS = 1200;
+/**
+ * `START_ANGLE` (adw-spinner-paintable.c:21) — a fixed phase offset added to
+ * both arc ends (:379-380), so the figure does not start at 3 o'clock.
+ *
+ * Neither port had it, which is a constant rotation error rather than a wrong
+ * speed — invisible in a still frame, visible against a GTK spinner beside it.
+ */
+export declare const ADW_SPINNER_START_ANGLE: number;
+/**
+ * `CIRCLE_OPACITY` (adw-spinner-paintable.c:22) — the track is the WIDGET's
+ * colour at 15%, not a hardcoded grey.
+ *
+ * The browser port used `rgba(127, 127, 127, 0.25)`: too dark, and
+ * hue-independent, so a spinner on a coloured background lost its track
+ * relationship entirely.
+ */
+export declare const ADW_SPINNER_TRACK_OPACITY = 0.15;
+/** `MIN_ARC_LENGTH` (:24) — GSK refuses to draw an arc shorter than this. */
+export declare const ADW_SPINNER_MIN_ARC_LENGTH: number;
+/** `MAX_ARC_LENGTH` (:25) — the LERP TARGET, 162°. The drawn arc peaks at 102.8°. */
+export declare const ADW_SPINNER_MAX_ARC_LENGTH: number;
+/** `IDLE_DISTANCE` (:26). */
+export declare const ADW_SPINNER_IDLE_DISTANCE: number;
+/** `OVERLAP_DISTANCE` (:27). */
+export declare const ADW_SPINNER_OVERLAP_DISTANCE: number;
+/** `EXTEND_DISTANCE` (:28). */
+export declare const ADW_SPINNER_EXTEND_DISTANCE: number;
+/** `CONTRACT_DISTANCE` (:29). */
+export declare const ADW_SPINNER_CONTRACT_DISTANCE: number;
+/**
+ * `N_CYCLES` (:33) — how many full TURNS the animation runs before repeating.
+ *
+ * The C states the constraint it satisfies: the cycle length
+ * `IDLE + EXTEND + CONTRACT - OVERLAP` must divide `N_CYCLES * 2pi` exactly, or
+ * the arc would jump when the animation loops. It does — 53 turns is 40 arc
+ * cycles — and {@link ADW_SPINNER_CYCLES_PER_LOOP} is that quotient, asserted
+ * rather than assumed.
+ */
+export declare const ADW_SPINNER_N_CYCLES = 53;
+/**
+ * One arc cycle, in radians of base angle:
+ * `IDLE_DISTANCE + EXTEND_DISTANCE + CONTRACT_DISTANCE - OVERLAP_DISTANCE`
+ * (adw-spinner-paintable.c:112, :130).
+ */
+export declare const ADW_SPINNER_CYCLE_LENGTH: number;
+/** Whole arc cycles per animation loop — an integer, which is the C's constraint. */
+export declare const ADW_SPINNER_CYCLES_PER_LOOP: number;
+/**
+ * The base angle a NON-animating spinner is drawn at — `EXTEND_DISTANCE -
+ * OVERLAP_DISTANCE / 2` (adw-spinner-paintable.c:375-376), i.e. `pi * 0.75`.
+ *
+ * Reached whenever there is no animation object: before the paintable has a
+ * widget, and in a still frame. Both ports left the resting pose undefined, so a
+ * spinner that had not started yet drew whatever its keyframe origin happened to
+ * be.
+ */
+export declare const ADW_SPINNER_STILL_PROGRESS: number;
+/**
+ * `normalize_angle` (adw-spinner-paintable.c:97-107) — fold into `[0, 2pi]`.
+ *
+ * The C loops rather than taking a modulo, and the boundary follows: it stops at
+ * `angle > G_PI * 2`, so exactly `2pi` is left alone where a modulo would give 0.
+ */
+export declare function normalizeSpinnerAngle(angle: number): number;
+/**
+ * `get_arc_start` (adw-spinner-paintable.c:109-125) — the trailing end of the
+ * arc, relative to the base angle.
+ *
+ * The `- angle * MAX_ARC_LENGTH / l` term is the drift that makes the arc
+ * advance around the circle as it breathes; without it the figure would pulse in
+ * place.
+ */
+export declare function spinnerArcStart(angle: number): number;
+/**
+ * `get_arc_end` (adw-spinner-paintable.c:127-145) — the leading end.
+ *
+ * Its phase is offset by `EXTEND_DISTANCE - OVERLAP_DISTANCE`: the end only
+ * starts moving once the start has extended past the overlap, which is what
+ * makes the arc grow before it slides.
+ */
+export declare function spinnerArcEnd(angle: number): number;
+/** The two ends of the drawn arc, in radians clockwise from 3 o'clock. */
+export interface SpinnerArc {
+    /** Trailing end, folded into `[0, 2pi]`. */
+    start: number;
+    /** Leading end, folded into `[0, 2pi]`. */
+    end: number;
+    /**
+     * Arc length along the circle, `start - end` unwrapped into `(0, 2pi]`.
+     *
+     * The segment runs from `end` to `start` (`gsk_path_builder_add_segment
+     * (builder, circle, &end_point, &start_point)`, :395) — the naming is the C's
+     * and it is the opposite way round from what "start" suggests.
+     */
+    length: number;
+}
+/**
+ * The arc for a base angle — `adw_spinner_paintable_snapshot_with_weight`
+ * (adw-spinner-paintable.c:373-383).
+ *
+ * `progress` is the animation's value: 0 at the start of a loop, rising linearly
+ * to `N_CYCLES * 2pi`. A renderer that has no animation passes
+ * {@link ADW_SPINNER_STILL_PROGRESS}.
+ */
+export declare function spinnerArc(progress: number): SpinnerArc;
+/**
+ * The animation's value after `elapsedMs` — `adw_timed_animation_new (widget, 0,
+ * N_CYCLES * 2pi, SPIN_DURATION_MS * N_CYCLES, target)` with `ADW_LINEAR` easing
+ * and `repeat_count = 0`, i.e. forever (adw-spinner-paintable.c:532-540).
+ *
+ * A linear ramp over the whole loop reduces to one turn per
+ * {@link ADW_SPINNER_SPIN_DURATION_MS}; the loop length only decides where it
+ * restarts, and it restarts at a point the arc phase agrees with.
+ */
+export declare function spinnerProgressAt(elapsedMs: number): number;

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

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

package/lib/types/split-view.d.ts

@@ -1,11 +1,8 @@
-/** `AdwLengthUnit` — the unit min/max sidebar widths are written in. */
-export type AdwLengthUnit = 'px' | 'pt' | 'sp';
+import { type AdwLengthUnit } from './length-unit.js';
 /** `GtkPackType` — which side of the view a pane is packed on. */
 export type AdwPackType = 'start' | 'end';
 /** `GtkTextDirection` — the reading direction `start`/`end` are resolved against. */
 export type AdwTextDirection = 'ltr' | 'rtl';
-/** The dpi `adw_length_unit_to_px` falls back to when `gtk-xft-dpi` is unset. */
-export declare const DEFAULT_DPI = 96;
 /** `min-sidebar-width` default, in {@link DEFAULT_SIDEBAR_WIDTH_UNIT}. */
 export declare const DEFAULT_MIN_SIDEBAR_WIDTH = 180;
 /** `max-sidebar-width` default, in {@link DEFAULT_SIDEBAR_WIDTH_UNIT}. */
@@ -16,14 +13,6 @@ export declare const DEFAULT_SIDEBAR_WIDTH_FRACTION = 0.25;
 export declare const DEFAULT_SIDEBAR_WIDTH_UNIT: AdwLengthUnit;
 /** The minimum grabbable edge width for the reveal gesture — `ADW_SWIPE_BORDER`. */
 export declare const ADW_SWIPE_BORDER = 32;
-/**
- * `adw_length_unit_to_px` (adw-length-unit.c:57-82) — convert `value` to pixels.
- *
- * `pt` and `sp` both scale with the text-scale factor, which GTK reads from
- * `gtk-xft-dpi`; a renderer that has no such setting passes the default 96, where
- * `sp` is a pixel passthrough and `pt` is the familiar 4/3 ratio.
- */
-export declare function adwLengthToPx(unit: AdwLengthUnit, value: number, dpi?: number): number;
 /**
  * GLib's `CLAMP` (gmacros.h) — `x > high ? high : x < low ? low : x`.
  *

package/lib/types/view-stack.d.ts

@@ -19,6 +19,12 @@ export interface AdwViewStackPageSpec<T = unknown> {
     content?: T;
     /** Whether the page participates in selection at all. Defaults to `true`. */
     visible?: boolean;
+    /** `AdwViewStackPage:badge-number`. Defaults to 0 — no badge. */
+    badgeNumber?: number;
+    /** `AdwViewStackPage:needs-attention`. Defaults to `false`. */
+    needsAttention?: boolean;
+    /** `AdwViewStackPage:use-underline`. Defaults to `false`. */
+    useUnderline?: boolean;
 }
 /**
  * A resolved page descriptor, as a bound switcher reads it.
@@ -39,6 +45,12 @@ export interface AdwViewStackPageInfo<T = unknown> {
     readonly content: T | undefined;
     /** Whether the page can be selected — `AdwViewStackPage:visible`. */
     readonly visible: boolean;
+    /** `AdwViewStackPage:badge-number`. 0 means no badge. */
+    readonly badgeNumber: number;
+    /** `AdwViewStackPage:needs-attention` — the bare dot, with or without a badge. */
+    readonly needsAttention: boolean;
+    /** `AdwViewStackPage:use-underline` — whether the title carries a mnemonic. */
+    readonly useUnderline: boolean;
 }
 /** Payload of a selection change. */
 export interface ViewStackStateChange<T = unknown> {

package/lib/types/view-switcher.d.ts

@@ -106,12 +106,15 @@ export declare function createViewSwitcherPage(init: AdwViewSwitcherPageInit): A
  * Project a wave-1 stack page descriptor onto a switcher page, for a switcher
  * BOUND to an `Adw.ViewStack` rather than owning its own pages.
  *
- * Two fidelity notes a caller has to know, both consequences of what
- * `AdwViewStackPageInfo` carries: its `title` is already resolved against the
- * page name, so it is never `null` and the button-visibility rule reduces to the
- * `visible` flag; and it carries none of `badge-number`, `needs-attention`,
- * `use-underline`, so a bound switcher derives an empty badge and no
- * description. Only a switcher that owns its pages sees those.
+ * One fidelity note remains: `AdwViewStackPageInfo.title` is already resolved
+ * against the page name, so it is never `null` and the button-visibility rule
+ * reduces to the `visible` flag.
+ *
+ * The second one is gone. This used to say the stack page carried none of
+ * `badge-number`, `needs-attention` or `use-underline`, "so a bound switcher
+ * derives an empty badge and no description" — which made a switcher bound to a
+ * stack STRUCTURALLY unable to show a badge, and both `ViewSwitcherBar`s go
+ * through here. The stack page carries all three now.
  */
 export declare function viewSwitcherPageFromStackPage(page: AdwViewStackPageInfo): AdwViewSwitcherPage;
 /** {@link viewSwitcherPageFromStackPage} over a whole page list. */

package/lib/types/wrap-box.d.ts

@@ -0,0 +1,200 @@
+import { type AdwLengthUnit } from './length-unit.js';
+/** `AdwJustifyMode` — the three values of `Adw.WrapBox:justify` (adw-wrap-layout.h:26-30). */
+export type AdwWrapBoxJustify = 'none' | 'fill' | 'spread';
+/** `AdwWrapPolicy` — whether children may shrink before a line wraps (adw-wrap-layout.h:39-43). */
+export type AdwWrapPolicy = 'minimum' | 'natural';
+/** `AdwPackDirection` — which end of a line children are packed from. */
+export type AdwWrapBoxPackDirection = 'start-to-end' | 'end-to-start';
+/** `GtkOrientation` — the axis children are packed along. */
+export type AdwWrapBoxOrientation = 'horizontal' | 'vertical';
+/** The three justify modes, for validating an attribute against the C enum. */
+export declare const ADW_WRAP_BOX_JUSTIFY_MODES: readonly AdwWrapBoxJustify[];
+/** The two wrap policies, for validating an attribute against the C enum. */
+export declare const ADW_WRAP_POLICIES: readonly AdwWrapPolicy[];
+/**
+ * `Adw.WrapBox:child-spacing` and `:line-spacing` defaults, in px.
+ *
+ * Both are `g_param_spec_int (…, 0, G_MAXINT, 0, …)` — adw-wrap-box.c:285-287
+ * and :393-395. The NativeScript port defaulted BOTH to 6 DIPs, so identical
+ * markup was looser on a phone than in the browser.
+ */
+export declare const ADW_WRAP_BOX_DEFAULT_SPACING = 0;
+/**
+ * `Adw.WrapBox:align` default (adw-wrap-box.c:335-337).
+ *
+ * Declared `g_param_spec_float (…, 0, 1, 0, …)`, so GObject validates an
+ * out-of-range value back into `[0, 1]` on set.
+ */
+export declare const ADW_WRAP_BOX_DEFAULT_ALIGN = 0;
+/** `Adw.WrapBox:justify` default — `ADW_JUSTIFY_NONE` (adw-wrap-box.c:364-366). */
+export declare const ADW_WRAP_BOX_DEFAULT_JUSTIFY: AdwWrapBoxJustify;
+/** `Adw.WrapBox:justify-last-line` default — `FALSE` (adw-wrap-box.c:379-381). */
+export declare const ADW_WRAP_BOX_DEFAULT_JUSTIFY_LAST_LINE = false;
+/** `Adw.WrapBox:wrap-policy` default — `ADW_WRAP_NATURAL` (adw-wrap-box.c:491-495). */
+export declare const ADW_WRAP_BOX_DEFAULT_WRAP_POLICY: AdwWrapPolicy;
+/**
+ * `Adw.WrapBox:natural-line-length` default — `-1`, i.e. UNSET
+ * (adw-wrap-box.c:438-441, range `-1 … G_MAXINT`).
+ *
+ * `-1` is not "zero length": it means the box asks for whatever its children
+ * need, so a renderer must not write it into a size.
+ */
+export declare const ADW_WRAP_BOX_NATURAL_LINE_LENGTH_UNSET = -1;
+/**
+ * The unit default for all three length properties — `ADW_LENGTH_UNIT_PX`
+ * (adw-wrap-box.c:300-305, :408-413, :454-458).
+ *
+ * Note this DIFFERS from the split views, which default to `sp`
+ * (`DEFAULT_SIDEBAR_WIDTH_UNIT`). Sharing `normalizeLengthUnit` between them is
+ * only safe because the default is the caller's argument, not the helper's.
+ */
+export declare const ADW_WRAP_BOX_DEFAULT_LENGTH_UNIT: AdwLengthUnit;
+/** `Adw.WrapBox:pack-direction` default — `ADW_PACK_START_TO_END` (adw-wrap-box.c:313-318). */
+export declare const ADW_WRAP_BOX_DEFAULT_PACK_DIRECTION: AdwWrapBoxPackDirection;
+/** The two pack directions, for validating an attribute against the C enum. */
+export declare const ADW_WRAP_BOX_PACK_DIRECTIONS: readonly AdwWrapBoxPackDirection[];
+/**
+ * `adw_wrap_box_set_child_spacing` / `set_line_spacing`
+ * (adw-wrap-box.c:587-588, :927-928) — a negative spacing is clamped to 0 BEFORE
+ * anything else happens, so it never reaches the layout.
+ *
+ * The property is declared with a minimum of 0, which is why the clamp exists at
+ * all: without it GObject would reject the value and warn. The non-numeric cases
+ * have no C counterpart — the property is an `int` — and resolve to the default,
+ * so a typo cannot put `NaN` into a `column-gap` or a native layout pass.
+ */
+export declare function normalizeWrapBoxSpacing(value: unknown): number;
+/** `Adw.WrapBox:align` — `g_param_spec_float (…, 0, 1, 0, …)`, adw-wrap-box.c:335-337. */
+export declare function normalizeWrapBoxAlign(value: unknown): number;
+/** An out-of-range enum value leaves a GObject property at its default. */
+export declare function normalizeWrapBoxJustify(value: unknown): AdwWrapBoxJustify;
+/** `Adw.WrapBox:wrap-policy` — same enum gate, defaulting to `natural`. */
+export declare function normalizeWrapPolicy(value: unknown): AdwWrapPolicy;
+/**
+ * `Adw.WrapBox:natural-line-length` — an `int` in `[-1, G_MAXINT]`.
+ *
+ * Anything below -1 is out of the declared range, so it lands on the sentinel
+ * rather than on 0: a GObject setter would have refused it and left the property
+ * where it was, and "unset" is what the property was born as.
+ */
+export declare function normalizeNaturalLineLength(value: unknown): number;
+/** `Adw.WrapBox`'s three length units — `px` by default, unlike the split views' `sp`. */
+export declare function normalizeWrapBoxLengthUnit(value: unknown): AdwLengthUnit;
+/** `Adw.WrapBox:pack-direction` — the same enum gate, defaulting to `start-to-end`. */
+export declare function normalizeWrapBoxPackDirection(value: unknown): AdwWrapBoxPackDirection;
+/**
+ * One length property resolved to pixels — the `adw_length_unit_to_px` call the
+ * measure and allocate paths both make before laying anything out
+ * (adw-wrap-layout.c:554-565, :798-804).
+ *
+ * The UNSET natural line length passes through untouched, mirroring the C's own
+ * `if (self->natural_line_length >= 0)` gate (:562): converting `-1` would turn
+ * a sentinel into a length, and at dpi ≠ 96 it would not even stay -1.
+ */
+export declare function wrapBoxLengthToPx(value: number, unit: AdwLengthUnit, dpi?: number): number;
+/** What a renderer has to do with a line's leftover space. */
+export interface WrapBoxLineLayout {
+    /**
+     * The justify mode that governs THIS line, after the last-line gate. It is
+     * the widget's `justify` for every line except the final one, and for the
+     * final one only when `justify-last-line` is set
+     * (adw-wrap-layout.c:397-400, :705-706).
+     */
+    justify: AdwWrapBoxJustify;
+    /**
+     * Whether the CHILDREN absorb the leftover (`allocated_size` grows to
+     * `available_size`, adw-wrap-layout.c:336-341). CSS: `flex-grow` on the
+     * items.
+     */
+    growChildren: boolean;
+    /**
+     * Whether the GAPS absorb the leftover — children keep `minimum_size` and
+     * are spread apart by `size_delta` (adw-wrap-layout.c:338-339, :752-757).
+     * CSS: `justify-content: space-between`.
+     */
+    growGaps: boolean;
+    /**
+     * The MAIN-axis offset factor applied to the whole line block when nothing
+     * grows: `widget_offset += roundf (length_delta * align)`
+     * (adw-wrap-layout.c:717-725). 0 packs the line at the start of the main
+     * axis, 1 at its end. Meaningless — and reported as 0 — as soon as the line
+     * is justified, because C only computes `length_delta` inside
+     * `if (!justify_line)`.
+     */
+    align: number;
+}
+/**
+ * The line-layout decision, straight from the C.
+ *
+ * `lastLine` is the FINAL line, complete or not (`i == *n_lines - 1`,
+ * adw-wrap-layout.c:463-464), so a wrap box whose children all fit on one line
+ * has that line governed by `justify-last-line` rather than by `justify` — which
+ * makes the single-line case, the common one, the counter-intuitive one.
+ *
+ * `spread` with exactly ONE child in the line does not spread anything:
+ * `n_children > 1` guards the branch that keeps children at `minimum_size`, so a
+ * lone child is STRETCHED instead, which the property documentation states
+ * outright (adw-wrap-box.c:349-352).
+ *
+ * Held to `WRAP_BOX_LINE_VECTORS` in `@gjsify/adwaita-core/conformance`, which
+ * both renderer suites drive their real widgets with.
+ */
+export declare function resolveWrapBoxLine(input: {
+    justify: AdwWrapBoxJustify;
+    justifyLastLine: boolean;
+    align: number;
+    lastLine: boolean;
+    childrenInLine: number;
+}): WrapBoxLineLayout;
+/**
+ * `wrap-policy` as the child `flex-shrink` both flex-based renderers express it
+ * with.
+ *
+ * `ADW_WRAP_NATURAL` wraps "as soon as the previous line cannot fit any more
+ * children without shrinking them past their natural size"; `ADW_WRAP_MINIMUM`
+ * "shrink[s] them down to their minimum size before wrapping"
+ * (adw-wrap-box.c:476-489).
+ *
+ * STATE THE LIMIT, because it is not a full mapping. Flexbox breaks lines on the
+ * items' HYPOTHETICAL main sizes and `flex-shrink` only distributes negative
+ * free space WITHIN a line that is already broken — so no value of it makes CSS
+ * pack more children per line, which is exactly what `minimum` is for. What it
+ * does decide is whether a line that still overflows squeezes its children or
+ * lets them spill, and that half is faithful.
+ *
+ * The reason to derive it anyway is the default. CSS defaults `flex-shrink` to
+ * **1**, i.e. to `minimum`; libadwaita defaults `wrap-policy` to `natural`. Both
+ * renderers had no policy at all, so both drew the one Adwaita does not choose,
+ * on every wrap box, silently.
+ */
+export declare function wrapPolicyFlexShrink(policy: AdwWrapPolicy): number;
+/** Which child-list operation is being resolved. */
+export type WrapBoxChildOrderOp = 'insert-after' | 'reorder-after';
+/**
+ * Where `adw_wrap_box_insert_child_after` / `reorder_child_after` put a child.
+ *
+ * Both delegate to `gtk_widget_insert_after (child, self, sibling)`
+ * (adw-wrap-box.c:1283-1300, :1315-1332), whose documented rule is the
+ * counter-intuitive one: a NULL sibling inserts at the FIRST position, not the
+ * last. Reading it as "append" is the obvious misreading, and it is silent —
+ * the child lands somewhere plausible.
+ *
+ * The guards are the C's `g_return_if_fail`s, expressed as a refusal rather than
+ * a throw because a renderer has no `g_critical` to fall through to: an insert
+ * demands the child be UNPARENTED and the sibling be a child of this box, a
+ * reorder demands the child already be one, and `child === sibling` is an
+ * explicit early return in both.
+ *
+ * Returns the new child list, or `null` when the operation is refused — the
+ * caller then leaves its view tree exactly as it was, which is what C does.
+ */
+export declare function resolveWrapBoxChildOrder<T>(input: {
+    /** The box's children, in order. */
+    children: readonly T[];
+    /** The child being placed. */
+    child: T;
+    /** The child to place it after, or `null`/`undefined` for the FIRST position. */
+    sibling?: T | null;
+    /** Which operation — they differ only in whether `child` is expected to be present. */
+    op: WrapBoxChildOrderOp;
+}): T[] | null;

package/lib/types/wrap-box.spec.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-core",
-    "version": "0.32.0",
+    "version": "0.34.0",
     "description": "Headless Adwaita widget behavior (breakpoint condition grammar + apply/unapply state machine, color-scheme observable, avatar derivation) shared by the web and NativeScript Adwaita renderers — pure TS, no platform imports",
     "type": "module",
     "module": "lib/esm/index.js",
@@ -46,8 +46,8 @@
         "headless"
     ],
     "devDependencies": {
-        "@gjsify/cli": "^0.32.0",
-        "@gjsify/unit": "^0.32.0",
+        "@gjsify/cli": "^0.34.0",
+        "@gjsify/unit": "^0.34.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },