@gjsify/adwaita-core 0.36.0 → 0.37.0

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

@@ -1,7 +1,7 @@
 import { type AdwLengthUnit } from './length-unit.js';
-/** `AdwJustifyMode` — the three values of `Adw.WrapBox:justify` (adw-wrap-layout.h:26-30). */
+/** `AdwJustifyMode` — the three values of `Adw.WrapBox:justify`. */
 export type AdwWrapBoxJustify = 'none' | 'fill' | 'spread';
-/** `AdwWrapPolicy` — whether children may shrink before a line wraps (adw-wrap-layout.h:39-43). */
+/** `AdwWrapPolicy` — whether children may shrink before a line wraps. */
 export type AdwWrapPolicy = 'minimum' | 'natural';
 /** `AdwPackDirection` — which end of a line children are packed from. */
 export type AdwWrapBoxPackDirection = 'start-to-end' | 'end-to-start';
@@ -11,133 +11,82 @@ export type AdwWrapBoxOrientation = 'horizontal' | 'vertical';
 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.
- */
+/** `Adw.WrapBox:child-spacing` / `:line-spacing` default, in px — both
+ * `g_param_spec_int (…, 0, G_MAXINT, 0, …)`. */
 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.
- */
+/** `Adw.WrapBox:align` default — `g_param_spec_float (…, 0, 1, 0, …)`, so GObject
+ * clamps 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). */
+/** `Adw.WrapBox:justify` default — `ADW_JUSTIFY_NONE`. */
 export declare const ADW_WRAP_BOX_DEFAULT_JUSTIFY: AdwWrapBoxJustify;
-/** `Adw.WrapBox:justify-last-line` default — `FALSE` (adw-wrap-box.c:379-381). */
+/** `Adw.WrapBox:justify-last-line` default — `FALSE`. */
 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). */
+/** `Adw.WrapBox:wrap-policy` default — `ADW_WRAP_NATURAL`. */
 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.
- */
+/** `Adw.WrapBox:natural-line-length` default — `-1` = UNSET, range `-1 … G_MAXINT`.
+ * Not "zero length": 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.
- */
+/** The unit default for all three length properties — `ADW_LENGTH_UNIT_PX`. DIFFERS from
+ * the split views' `sp` (`DEFAULT_SIDEBAR_WIDTH_UNIT`); sharing `normalizeLengthUnit` 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). */
+/** `Adw.WrapBox:pack-direction` default — `ADW_PACK_START_TO_END`. */
 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.
- */
+/** `adw_wrap_box_set_child_spacing` / `set_line_spacing`  — a negative spacing is clamped to 0 before it can reach the layout.
+ * 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`. */
 export declare function normalizeWrapBoxSpacing(value: unknown): number;
-/** `Adw.WrapBox:align` — `g_param_spec_float (…, 0, 1, 0, …)`, adw-wrap-box.c:335-337. */
+/** `Adw.WrapBox:align` — `g_param_spec_float (…, 0, 1, 0, …)`, so GObject clamps on set. */
 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.
- */
+/** `Adw.WrapBox:natural-line-length` — an `int` in `[-1, G_MAXINT]`. Any NEGATIVE value
+ * lands on the sentinel rather than on 0: a GObject setter would have refused an
+ * out-of-range write, and "unset" is where the property started. */
 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.
- */
+/** One length property resolved to pixels — the `adw_length_unit_to_px` call the measure
+ * and allocate paths both make. The UNSET natural line length passes through untouched,
+ * mirroring the C's `if (self->natural_line_length >= 0)` gate: converting `-1` would turn
+ * a sentinel into a length, and at dpi ≠ 96 would not even leave it -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).
-     */
+    /** The justify mode governing THIS line, after the last-line gate — the widget's
+     * `justify` except on the final line, which needs `justify-last-line`. */
     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.
-     */
+    /** Whether the CHILDREN absorb the leftover (`allocated_size` grows to
+     * `available_size`). 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`.
-     */
+    /** Whether the GAPS absorb it instead — children keep `minimum_size` and are spread by
+     * `size_delta`. 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)`.
-     */
+    /** The MAIN-axis offset factor applied to the whole line block when nothing grows:
+     * `widget_offset += roundf (length_delta * align)`, 0 = line start, 1 = line end.
+     * Reported as 0 once the line is justified, because C computes `length_delta` only
+     * 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.
+ * `lastLine` is the FINAL line, complete or not (`i == *n_lines - 1`), 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).
+ * `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.
  *
- * Held to `WRAP_BOX_LINE_VECTORS` in `@gjsify/adwaita-core/conformance`, which
- * both renderer suites drive their real widgets with.
+ * Held to `WRAP_BOX_LINE_VECTORS` in `@gjsify/adwaita-core/conformance`.
  */
 export declare function resolveWrapBoxLine(input: {
     justify: AdwWrapBoxJustify;
@@ -148,24 +97,19 @@ export declare function resolveWrapBoxLine(input: {
 }): 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
+ * 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).
+ * "shrink[s] them down to their minimum size before wrapping".
  *
- * 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.
+ * NOT a full mapping, and the limit matters: flexbox breaks lines on the items'
+ * HYPOTHETICAL main sizes and `flex-shrink` only distributes negative free space WITHIN an
+ * already-broken line, so no value of it packs more children per line — which is what
+ * `minimum` is for. It does faithfully decide whether an overflowing line squeezes its
+ * children or lets them spill.
  *
- * 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.
+ * Deriving it is still worth it for the DEFAULT: CSS defaults `flex-shrink` to 1
+ * (= `minimum`) where libadwaita defaults `wrap-policy` to `natural`, so a renderer with
+ * no policy silently draws the one Adwaita does not choose.
  */
 export declare function wrapPolicyFlexShrink(policy: AdwWrapPolicy): number;
 /** Which child-list operation is being resolved. */
@@ -173,20 +117,15 @@ 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.
+ * Both delegate to `gtk_widget_insert_after (child, self, sibling)`, whose rule is
+ * counter-intuitive: a NULL sibling inserts at the FIRST position, not the last. Reading
+ * it as "append" fails silently — the child lands somewhere plausible.
  *
- * 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.
+ * MODIFICATION: the C's `g_return_if_fail`s become a refusal (`null`) rather than a throw,
+ * because a renderer has no `g_critical` to fall through to; the caller then leaves its
+ * view tree untouched, as C does. Insert demands an UNPARENTED child and a sibling of this
+ * box, reorder demands the child already be one, and `child === sibling` returns early in
+ * both.
  */
 export declare function resolveWrapBoxChildOrder<T>(input: {
     /** The box's children, in order. */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-core",
-    "version": "0.36.0",
+    "version": "0.37.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.36.0",
-        "@gjsify/unit": "^0.36.0",
+        "@gjsify/cli": "^0.37.0",
+        "@gjsify/unit": "^0.37.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },