@gjsify/adwaita-web 0.32.0 → 0.33.0

package/src/elements/adw-wrap-box.ts

@@ -1,103 +1,75 @@
 // <adw-wrap-box> — A box-like container that lays its children out in a line and
-// wraps them onto new lines when they run out of room (the web analog of
-// flexbox `flex-wrap: wrap` with a gap). Mirrors Adw.WrapBox.
-// Attributes:
-//   child-spacing   (px, default 0) — spacing between children on the same line
-//                                      → CSS column-gap
-//   line-spacing    (px, default 0) — spacing between lines → CSS row-gap
-//   orientation     ("horizontal" | "vertical", default "horizontal") — the main
-//                                      axis children are packed along
-//   align           (0..1, default 0) — where the children sit ALONG the line
-//                                      (main axis); 0 = start, 0.5 = middle, 1 = end
-//   justify         ("none" | "fill" | "spread", default "none") — whether/how
-//                                      each line is stretched to fill the widget
-//   justify-last-line (boolean) — also justify the last (final) line
-//   line-homogeneous  (boolean) — make every line take the same amount of space
-//   pack-direction  ("start-to-end" | "end-to-start", default "start-to-end") —
-//                                      direction children are packed within a line
-//   wrap-reverse    (boolean) — reverse the wrap direction (lines wrap upwards)
-// Events: notify::child-spacing, notify::line-spacing (CustomEvent, bubbles —
-//   mirrors GObject signal naming, including its "only on a real change" rule).
+// wraps them onto new lines when they run out of room (the web analog of flexbox
+// `flex-wrap: wrap` with a gap). Mirrors Adw.WrapBox.
+//
+// Attributes — all fourteen of the widget's properties, each with a
+// `notify::<property>` (adw-wrap-box.c:284-497). The element used to carry nine
+// attributes and notify for two, so a consumer binding to any of the other
+// twelve was listening to a signal that could not fire.
+//
+//   child-spacing / line-spacing        (int >= 0, default 0) -> column-gap / row-gap
+//   child-spacing-unit / line-spacing-unit ("px" | "pt" | "sp", default "px")
+//   orientation      ("horizontal" | "vertical", default "horizontal")
+//   pack-direction   ("start-to-end" | "end-to-start", default "start-to-end")
+//   align            (0..1, default 0) — MAIN-axis offset of the whole line block
+//   justify          ("none" | "fill" | "spread", default "none")
+//   justify-last-line (boolean)
+//   line-homogeneous  (boolean)
+//   wrap-reverse      (boolean)
+//   wrap-policy      ("minimum" | "natural", default "natural")
+//   natural-line-length (int >= -1, default -1 = unset) + -unit
+//
+// The property CONTRACT — the normalisers and the justify/align/last-line
+// decision — is `@gjsify/adwaita-core`'s `wrap-box.ts`, held to
+// `WRAP_BOX_LINE_VECTORS` and friends, which the NativeScript suite drives too.
+// This element used to carry its own copy of all of it.
+//
 // Reference: refs/libadwaita/src/adw-wrap-box.c / adw-wrap-layout.c (Adw.WrapBox)
 // Reference: refs/adwaita-web/adwaita-web/scss/_wrap_box.scss
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
-/** `AdwJustifyMode` (adw-wrap-layout.c:74-83). */
-type JustifyMode = 'none' | 'fill' | 'spread';
-
-/** The three modes, for validating the attribute against the C enum. */
-const JUSTIFY_MODES: readonly JustifyMode[] = ['none', 'fill', 'spread'];
-
-/** What one line does with the space its children do not use. */
-interface LineLayout {
-    /** The mode governing this line, after the last-line gate. */
-    justify: JustifyMode;
-    /** Whether the CHILDREN absorb the leftover (adw-wrap-layout.c:336-341). */
-    growChildren: boolean;
-    /** Whether the GAPS absorb it (adw-wrap-layout.c:338-339, :752-757). */
-    growGaps: boolean;
-    /** The main-axis offset factor for an un-justified line (adw-wrap-layout.c:717-725). */
-    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`.
- *
- * The conformance table this must agree with is
- * `@gjsify/adwaita-core/conformance` → `WRAP_BOX_LINE_VECTORS`; the same rows
- * are asserted against the NativeScript port, so the two cannot drift apart
- * without a test naming the input.
- */
-function resolveLine(
-    justify: JustifyMode,
-    justifyLastLine: boolean,
-    align: number,
-    lastLine: boolean,
-    childrenInLine: number,
-): LineLayout {
-    // adw-wrap-layout.c:397-400 / :705-706 — the final line is only justified on
-    // request; otherwise it falls back to ADW_JUSTIFY_NONE and to `align`.
-    const effective: JustifyMode = lastLine && !justifyLastLine ? 'none' : justify;
-    if (effective === 'none') return { justify: 'none', growChildren: false, growGaps: false, align };
-    // adw-wrap-layout.c:338 — SPREAD keeps children at their minimum size and
-    // widens the gaps, but the branch is guarded by `n_children > 1`: a lone
-    // child has nothing to spread against and is stretched instead, which the
-    // property documentation states outright (adw-wrap-box.c:349-352).
-    const spreadsGaps = effective === 'spread' && childrenInLine > 1;
-    return { justify: effective, growChildren: !spreadsGaps, growGaps: spreadsGaps, align: 0 };
-}
+import {
+    ADW_WRAP_BOX_NATURAL_LINE_LENGTH_UNSET,
+    normalizeNaturalLineLength,
+    normalizeWrapBoxAlign,
+    normalizeWrapBoxJustify,
+    normalizeWrapBoxLengthUnit,
+    normalizeWrapBoxPackDirection,
+    normalizeWrapBoxSpacing,
+    normalizeWrapPolicy,
+    resolveWrapBoxChildOrder,
+    resolveWrapBoxLine,
+    wrapBoxLengthToPx,
+    wrapPolicyFlexShrink,
+    type AdwLengthUnit,
+} from '@gjsify/adwaita-core';
 
 /**
- * `Adw.WrapBox:child-spacing` / `:line-spacing` normalisation.
+ * The attributes that carry a property, in the order the C installs them.
  *
- * C clamps a negative value to 0 before it reaches the layout
- * (adw-wrap-box.c:587-588, :927-928) — the property is declared with a minimum
- * of 0, so without the clamp GObject would reject it. The non-numeric cases have
- * no C counterpart (the property is an `int`); they resolve to the default so a
- * typo cannot put `NaN` into a `column-gap`.
+ * Doubles as the `notify::` roster: every entry gets an event on a real change,
+ * so adding an attribute without its notification is not expressible here.
  */
-function normalizeSpacing(raw: string | null): number {
-    const value = Number.parseFloat(raw ?? '');
-    if (!Number.isFinite(value) || value < 0) return 0;
-    return value;
-}
-
-/** `Adw.WrapBox:align` — `g_param_spec_float (…, 0, 1, 0, …)`, adw-wrap-box.c:335-337. */
-function normalizeAlign(raw: string | null): number {
-    const value = Number.parseFloat(raw ?? '');
-    if (!Number.isFinite(value)) return 0;
-    return Math.min(1, Math.max(0, value));
-}
+const PROPERTY_ATTRIBUTES = [
+    'child-spacing',
+    'child-spacing-unit',
+    'pack-direction',
+    'align',
+    'justify',
+    'justify-last-line',
+    'line-spacing',
+    'line-spacing-unit',
+    'line-homogeneous',
+    'natural-line-length',
+    'natural-line-length-unit',
+    'wrap-reverse',
+    'wrap-policy',
+    'orientation',
+] as const;
 
-/** An out-of-range enum value leaves a GObject property at its default. */
-function normalizeJustify(raw: string | null): JustifyMode {
-    return JUSTIFY_MODES.includes(raw as JustifyMode) ? (raw as JustifyMode) : 'none';
-}
+/** One attribute's normalised value, for the "did it really change" comparison. */
+type PropertyValue = string | number | boolean;
 
 /**
  * `align` as a `justify-content` keyword.
@@ -117,37 +89,186 @@ export class AdwWrapBox extends HTMLElement {
     private _initialized = false;
 
     static get observedAttributes() {
-        return [
-            'child-spacing',
-            'line-spacing',
-            'orientation',
-            'align',
-            'justify',
-            'justify-last-line',
-            'line-homogeneous',
-            'pack-direction',
-            'wrap-reverse',
-        ];
-    }
-
-    /** Spacing between children on the same line, in px (CSS column-gap). */
+        return [...PROPERTY_ATTRIBUTES];
+    }
+
+    // --- properties ---
+
+    /** Spacing between children on the same line, in `child-spacing-unit`. */
     get childSpacing(): number {
-        return normalizeSpacing(this.getAttribute('child-spacing'));
+        return normalizeWrapBoxSpacing(this.getAttribute('child-spacing'));
     }
 
     set childSpacing(value: number) {
         this.setAttribute('child-spacing', String(value));
     }
 
-    /** Spacing between lines, in px (CSS row-gap). */
+    /** The unit `child-spacing` is written in. Defaults to `px`, as in C. */
+    get childSpacingUnit(): AdwLengthUnit {
+        return normalizeWrapBoxLengthUnit(this.getAttribute('child-spacing-unit'));
+    }
+
+    set childSpacingUnit(value: AdwLengthUnit) {
+        this.setAttribute('child-spacing-unit', value);
+    }
+
+    /** Spacing between lines, in `line-spacing-unit`. */
     get lineSpacing(): number {
-        return normalizeSpacing(this.getAttribute('line-spacing'));
+        return normalizeWrapBoxSpacing(this.getAttribute('line-spacing'));
     }
 
     set lineSpacing(value: number) {
         this.setAttribute('line-spacing', String(value));
     }
 
+    /** The unit `line-spacing` is written in. Defaults to `px`, as in C. */
+    get lineSpacingUnit(): AdwLengthUnit {
+        return normalizeWrapBoxLengthUnit(this.getAttribute('line-spacing-unit'));
+    }
+
+    set lineSpacingUnit(value: AdwLengthUnit) {
+        this.setAttribute('line-spacing-unit', value);
+    }
+
+    /** Where the children sit ALONG the line (main axis): 0 start, 0.5 middle, 1 end. */
+    get align(): number {
+        return normalizeWrapBoxAlign(this.getAttribute('align'));
+    }
+
+    set align(value: number) {
+        this.setAttribute('align', String(value));
+    }
+
+    /** Whether and how each line is stretched to fill the widget. */
+    get justify(): 'none' | 'fill' | 'spread' {
+        return normalizeWrapBoxJustify(this.getAttribute('justify'));
+    }
+
+    set justify(value: 'none' | 'fill' | 'spread') {
+        this.setAttribute('justify', value);
+    }
+
+    /** Whether the FINAL line is justified too. Default false, as in C. */
+    get justifyLastLine(): boolean {
+        return this.hasAttribute('justify-last-line');
+    }
+
+    set justifyLastLine(value: boolean) {
+        this.toggleAttribute('justify-last-line', !!value);
+    }
+
+    /** Whether an overflowing line squeezes its children or lets them spill. */
+    get wrapPolicy(): 'minimum' | 'natural' {
+        return normalizeWrapPolicy(this.getAttribute('wrap-policy'));
+    }
+
+    set wrapPolicy(value: 'minimum' | 'natural') {
+        this.setAttribute('wrap-policy', value);
+    }
+
+    /** The direction children are packed in each line. */
+    get packDirection(): 'start-to-end' | 'end-to-start' {
+        return normalizeWrapBoxPackDirection(this.getAttribute('pack-direction'));
+    }
+
+    set packDirection(value: 'start-to-end' | 'end-to-start') {
+        this.setAttribute('pack-direction', value);
+    }
+
+    /** Whether lines wrap upwards (horizontal) / towards the start (vertical). */
+    get wrapReverse(): boolean {
+        return this.hasAttribute('wrap-reverse');
+    }
+
+    set wrapReverse(value: boolean) {
+        this.toggleAttribute('wrap-reverse', !!value);
+    }
+
+    /** Whether every line takes the same amount of space. */
+    get lineHomogeneous(): boolean {
+        return this.hasAttribute('line-homogeneous');
+    }
+
+    set lineHomogeneous(value: boolean) {
+        this.toggleAttribute('line-homogeneous', !!value);
+    }
+
+    /** The natural line length in `natural-line-length-unit`, or `-1` when unset. */
+    get naturalLineLength(): number {
+        return normalizeNaturalLineLength(this.getAttribute('natural-line-length'));
+    }
+
+    set naturalLineLength(value: number) {
+        this.setAttribute('natural-line-length', String(value));
+    }
+
+    /** The unit `natural-line-length` is written in. Defaults to `px`, as in C. */
+    get naturalLineLengthUnit(): AdwLengthUnit {
+        return normalizeWrapBoxLengthUnit(this.getAttribute('natural-line-length-unit'));
+    }
+
+    set naturalLineLengthUnit(value: AdwLengthUnit) {
+        this.setAttribute('natural-line-length-unit', value);
+    }
+
+    /** The axis children are packed along. */
+    get orientation(): 'horizontal' | 'vertical' {
+        return this.getAttribute('orientation') === 'vertical' ? 'vertical' : 'horizontal';
+    }
+
+    set orientation(value: 'horizontal' | 'vertical') {
+        this.setAttribute('orientation', value);
+    }
+
+    // --- child list (adw_wrap_box_insert_child_after / reorder / remove_all) ---
+    //
+    // `adw_wrap_box_append`, `_prepend` and `_remove` are deliberately NOT
+    // redeclared: `ParentNode.append` / `.prepend` and `Node.removeChild` are
+    // those three, with the same semantics, and shadowing them would give this
+    // element two spellings of one operation. Only the three the DOM has no
+    // counterpart for are added.
+
+    /** The element children, which are what the layout actually lays out. */
+    private get _children(): Element[] {
+        return [...this.children];
+    }
+
+    /**
+     * `adw_wrap_box_insert_child_after` (adw-wrap-box.c:1283-1300).
+     *
+     * A NULL/absent `sibling` inserts at the FIRST position, not the last —
+     * `gtk_widget_insert_after`'s documented rule, pinned by
+     * `WRAP_BOX_CHILD_ORDER_VECTORS`. Returns whether the insert happened; a
+     * refusal is where C would have hit a `g_return_if_fail`.
+     */
+    insertChildAfter(child: Element, sibling: Element | null = null): boolean {
+        return this._applyOrder('insert-after', child, sibling);
+    }
+
+    /** `adw_wrap_box_reorder_child_after` (adw-wrap-box.c:1315-1332). Same NULL rule. */
+    reorderChildAfter(child: Element, sibling: Element | null = null): boolean {
+        return this._applyOrder('reorder-after', child, sibling);
+    }
+
+    /** `adw_wrap_box_remove_all` (adw-wrap-box.c:1406-1414). */
+    removeAll(): void {
+        for (const child of this._children) this.removeChild(child);
+    }
+
+    private _applyOrder(op: 'insert-after' | 'reorder-after', child: Element, sibling: Element | null): boolean {
+        const next = resolveWrapBoxChildOrder({ children: this._children, child, sibling, op });
+        if (next === null) return false;
+        // Move exactly the one node: `insertBefore` relocates a node already in
+        // the tree, and a null reference node appends. Re-appending the whole
+        // resolved list would reach the same order while detaching and
+        // re-attaching every sibling, which resets focus and any element state.
+        const at = next.indexOf(child);
+        this.insertBefore(child, next[at + 1] ?? null);
+        return true;
+    }
+
+    // --- lifecycle ---
+
     connectedCallback() {
         if (this._initialized) return;
         this._initialized = true;
@@ -159,40 +280,56 @@ export class AdwWrapBox extends HTMLElement {
         this._sync();
         // C compares AFTER normalising and returns early when nothing changed
         // (adw-wrap-box.c:592-593), so `child-spacing="-5"` on a box already at 0
-        // notifies nobody.
-        if (name === 'child-spacing') {
-            const next = normalizeSpacing(value);
-            if (next === normalizeSpacing(old)) return;
-            this.dispatchEvent(
-                new CustomEvent('notify::child-spacing', { bubbles: true, detail: { childSpacing: next } }),
-            );
-        } else if (name === 'line-spacing') {
-            const next = normalizeSpacing(value);
-            if (next === normalizeSpacing(old)) return;
-            this.dispatchEvent(
-                new CustomEvent('notify::line-spacing', { bubbles: true, detail: { lineSpacing: next } }),
-            );
+        // notifies nobody. The same gate applies to every property, not just the
+        // two spacings this element used to special-case.
+        const next = this._normalized(name, value);
+        if (next === this._normalized(name, old)) return;
+        this.dispatchEvent(new CustomEvent(`notify::${name}`, { bubbles: true, detail: { [name]: next } }));
+    }
+
+    /** One attribute's value as the widget stores it — the notify comparison key. */
+    private _normalized(name: string, raw: string | null): PropertyValue {
+        switch (name) {
+            case 'child-spacing':
+            case 'line-spacing':
+                return normalizeWrapBoxSpacing(raw);
+            case 'child-spacing-unit':
+            case 'line-spacing-unit':
+            case 'natural-line-length-unit':
+                return normalizeWrapBoxLengthUnit(raw);
+            case 'align':
+                return normalizeWrapBoxAlign(raw);
+            case 'justify':
+                return normalizeWrapBoxJustify(raw);
+            case 'wrap-policy':
+                return normalizeWrapPolicy(raw);
+            case 'pack-direction':
+                return normalizeWrapBoxPackDirection(raw);
+            case 'natural-line-length':
+                return normalizeNaturalLineLength(raw);
+            case 'orientation':
+                return raw === 'vertical' ? 'vertical' : 'horizontal';
+            default:
+                // The three booleans: a present attribute is true whatever it says.
+                return raw !== null;
         }
     }
 
     private _sync() {
         const style = this.style;
-        const vertical = this.getAttribute('orientation') === 'vertical';
-        const reverseWrap = this.hasAttribute('wrap-reverse');
-        const packEndToStart = this.getAttribute('pack-direction') === 'end-to-start';
+        const vertical = this.orientation === 'vertical';
 
         // Main axis is the packing direction; lines wrap along the cross axis.
         const direction = vertical ? 'column' : 'row';
-        const reversed = packEndToStart ? `${direction}-reverse` : direction;
-        style.flexDirection = reversed;
-        style.flexWrap = reverseWrap ? 'wrap-reverse' : 'wrap';
+        style.flexDirection = this.packDirection === 'end-to-start' ? `${direction}-reverse` : direction;
+        style.flexWrap = this.wrapReverse ? 'wrap-reverse' : 'wrap';
 
         // child-spacing is along the line (main axis), line-spacing is between
         // lines (cross axis). For a horizontal box that maps to column-gap /
-        // row-gap respectively; the mapping flips for a vertical box.
-        const childSpacing = this.childSpacing;
-        const childGap = `${childSpacing}px`;
-        const lineGap = `${this.lineSpacing}px`;
+        // row-gap respectively; the mapping flips for a vertical box. Both are
+        // resolved through their OWN unit first, which is why they can disagree.
+        const childGap = `${wrapBoxLengthToPx(this.childSpacing, this.childSpacingUnit)}px`;
+        const lineGap = `${wrapBoxLengthToPx(this.lineSpacing, this.lineSpacingUnit)}px`;
         if (vertical) {
             style.rowGap = childGap;
             style.columnGap = lineGap;
@@ -204,9 +341,9 @@ export class AdwWrapBox extends HTMLElement {
         // main-axis gap so it can never push a full line into a new one.
         style.setProperty('--adw-wrap-box-child-spacing', childGap);
 
-        const justify = normalizeJustify(this.getAttribute('justify'));
-        const justifyLastLine = this.hasAttribute('justify-last-line');
-        const align = normalizeAlign(this.getAttribute('align'));
+        const justify = this.justify;
+        const justifyLastLine = this.justifyLastLine;
+        const align = this.align;
 
         // A flex container has ONE `justify-content` and applies it to every
         // line, so it carries the COMPLETE-line rule; the final-line rule is
@@ -216,8 +353,8 @@ export class AdwWrapBox extends HTMLElement {
         // The pair is deliberately never collapsed into one attribute: flexbox
         // cannot express "every line but the last", and pretending otherwise is
         // what made `justify-last-line` a no-op in the first place.
-        const line = resolveLine(justify, justifyLastLine, align, false, 2);
-        const lastLine = resolveLine(justify, justifyLastLine, align, true, 2);
+        const line = resolveWrapBoxLine({ justify, justifyLastLine, align, lastLine: false, childrenInLine: 2 });
+        const lastLine = resolveWrapBoxLine({ justify, justifyLastLine, align, lastLine: true, childrenInLine: 2 });
         this.dataset.lineJustify = line.justify;
         this.dataset.lastLineJustify = lastLine.justify;
 
@@ -228,7 +365,25 @@ export class AdwWrapBox extends HTMLElement {
 
         // line-homogeneous makes every line take the same amount of space, which
         // flexbox approximates by stretching the lines across the cross axis.
-        style.alignContent = this.hasAttribute('line-homogeneous') ? 'stretch' : 'flex-start';
+        style.alignContent = this.lineHomogeneous ? 'stretch' : 'flex-start';
+
+        // `wrap-policy` decides whether an overflowing line squeezes its children
+        // or lets them spill. CSS defaults `flex-shrink` to 1, i.e. to
+        // ADW_WRAP_MINIMUM — the value libadwaita does NOT default to, so an
+        // unset policy has been drawing the wrong one on every wrap box. What
+        // flexbox cannot do either way is pack MORE children onto a line, since
+        // line breaking runs on hypothetical sizes; see `wrapPolicyFlexShrink`.
+        style.setProperty('--adw-wrap-box-child-shrink', String(wrapPolicyFlexShrink(this.wrapPolicy)));
+
+        // DELIBERATE DEVIATION: libadwaita's `natural-line-length` caps the box's
+        // NATURAL size request, leaving a larger allocation free to happen; CSS
+        // has no property that caps only the intrinsic contribution, so this is a
+        // max-size on the main axis and therefore caps the allocation too. It is
+        // the intended use (limiting line length inside a popover) either way.
+        const natural = wrapBoxLengthToPx(this.naturalLineLength, this.naturalLineLengthUnit);
+        const cap = natural === ADW_WRAP_BOX_NATURAL_LINE_LENGTH_UNSET ? '' : `${natural}px`;
+        style.maxWidth = vertical ? '' : cap;
+        style.maxHeight = vertical ? cap : '';
     }
 }