@gjsify/adwaita-web 0.31.0 → 0.32.0

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

@@ -7,28 +7,111 @@
 //   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) — alignment of children within each line
-//                                      (cross axis); 0 = start, 0.5 = center, 1 = end
+//   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 (incomplete) line
+//   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).
+//   mirrors GObject signal naming, including its "only on a real change" rule).
 // 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.
 
-/** Adw.JustifyMode → flexbox justify-content. */
-const JUSTIFY_MAP: Record<string, string> = {
-    none: 'flex-start',
-    fill: 'space-between',
-    spread: 'space-between',
-};
+/** `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 };
+}
+
+/**
+ * `Adw.WrapBox:child-spacing` / `:line-spacing` normalisation.
+ *
+ * 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`.
+ */
+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));
+}
+
+/** 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';
+}
+
+/**
+ * `align` as a `justify-content` keyword.
+ *
+ * C offsets the whole line block by `roundf (length_delta * align)` — a
+ * continuum. Flexbox has three main-axis positions, so the nearest one is taken;
+ * that is the renderer's approximation, not libadwaita's rule, which is why it
+ * lives here and not in the conformance table.
+ */
+function alignToJustifyContent(align: number): string {
+    if (align < 0.25) return 'flex-start';
+    if (align < 0.75) return 'center';
+    return 'flex-end';
+}
 
 export class AdwWrapBox extends HTMLElement {
     private _initialized = false;
@@ -49,7 +132,7 @@ export class AdwWrapBox extends HTMLElement {
 
     /** Spacing between children on the same line, in px (CSS column-gap). */
     get childSpacing(): number {
-        return parseFloat(this.getAttribute('child-spacing') || '0');
+        return normalizeSpacing(this.getAttribute('child-spacing'));
     }
 
     set childSpacing(value: number) {
@@ -58,7 +141,7 @@ export class AdwWrapBox extends HTMLElement {
 
     /** Spacing between lines, in px (CSS row-gap). */
     get lineSpacing(): number {
-        return parseFloat(this.getAttribute('line-spacing') || '0');
+        return normalizeSpacing(this.getAttribute('line-spacing'));
     }
 
     set lineSpacing(value: number) {
@@ -74,20 +157,20 @@ export class AdwWrapBox extends HTMLElement {
     attributeChangedCallback(name: string, old: string | null, value: string | null) {
         if (!this._initialized) return;
         this._sync();
-        if (old === value) return;
+        // 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: this.childSpacing },
-                }),
+                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: this.lineSpacing },
-                }),
+                new CustomEvent('notify::line-spacing', { bubbles: true, detail: { lineSpacing: next } }),
             );
         }
     }
@@ -107,7 +190,8 @@ export class AdwWrapBox extends HTMLElement {
         // 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 childGap = `${this.childSpacing}px`;
+        const childSpacing = this.childSpacing;
+        const childGap = `${childSpacing}px`;
         const lineGap = `${this.lineSpacing}px`;
         if (vertical) {
             style.rowGap = childGap;
@@ -116,19 +200,31 @@ export class AdwWrapBox extends HTMLElement {
             style.columnGap = childGap;
             style.rowGap = lineGap;
         }
-
-        // justify-content stretches each complete line along the main axis; the
-        // last (incomplete) line is only stretched when justify-last-line is set.
-        const justify = this.getAttribute('justify') ?? 'none';
-        style.justifyContent = JUSTIFY_MAP[justify] ?? 'flex-start';
-
-        // align (0..1) positions children within each line on the cross axis.
-        // It is only honoured when the line is not justified.
-        const align = Math.max(0, Math.min(1, parseFloat(this.getAttribute('align') || '0')));
-        let crossAlign = 'flex-start';
-        if (align >= 0.75) crossAlign = 'flex-end';
-        else if (align >= 0.25) crossAlign = 'center';
-        style.alignItems = crossAlign;
+        // Read back by the last-line filler, which has to cancel exactly one
+        // 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'));
+
+        // 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
+        // published beside it for the stylesheet, which reaches that line through
+        // the only two selectors CSS offers — `:only-child` (a box with one child
+        // has one line, and it is the last) and the generated `::after` filler.
+        // 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);
+        this.dataset.lineJustify = line.justify;
+        this.dataset.lastLineJustify = lastLine.justify;
+
+        // SPREAD widens the gaps; FILL grows the children (stylesheet) and leaves
+        // the gaps alone; NONE offsets the whole line block by `align` — along
+        // the MAIN axis, never the cross one.
+        style.justifyContent = line.growGaps ? 'space-between' : alignToJustifyContent(line.align);
 
         // line-homogeneous makes every line take the same amount of space, which
         // flexbox approximates by stretching the lines across the cross axis.

package/src/elements/view-switcher-dom.ts

@@ -0,0 +1,108 @@
+// The DOM half of the view-switcher family — what `@gjsify/adwaita-core` cannot
+// decide because it is genuinely per-renderer.
+//
+// Everything that decides WHAT a switcher shows (the button-visibility rule, the
+// `image-missing` fallback, the badge label + screen-reader description, the
+// mnemonic-stripped label, the tooltip, the reveal gate, the two index spaces)
+// lives in `@gjsify/adwaita-core` and is pinned by the conformance vectors.
+// What is left, and lives here, is how a derived model becomes nodes: an icon
+// NAME turned into a CSS mask class, an indicator span, and a `setTimeout`
+// wrapped in the scheduler seam the core takes for the drag-hover dwell.
+//
+// Shared by all three switcher elements because it was three copies before:
+// `<adw-view-switcher>`, `<adw-inline-view-switcher>` and
+// `<adw-view-switcher-bar>` each built their own icon span and their own page
+// parsing, and the copies had already drifted (a titleless page rendered `''` in
+// one and `page-<index>` in another).
+//
+// Reference: refs/libadwaita/src/adw-view-switcher.c
+// Reference: refs/libadwaita/src/adw-indicator-bin.c
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Modifications: Implemented for @gjsify/adwaita-web Web Components.
+
+import { viewSwitcherIconName } from '@gjsify/adwaita-core';
+import type { AdwViewSwitcherPageInit, ViewSwitcherScheduler, ViewSwitcherTimerHandle } from '@gjsify/adwaita-core';
+
+import { type AdwIcon, createAdwIcon } from './adw-icon.js';
+
+/**
+ * The browser's timer behind the core's scheduler seam.
+ *
+ * One shared instance rather than one per element: it holds no state, and the
+ * seam exists so the CORE stays free of a global timer, not so each element
+ * invents its own.
+ */
+export const domViewSwitcherScheduler: ViewSwitcherScheduler = {
+    schedule(callback: () => void, ms: number): ViewSwitcherTimerHandle {
+        return setTimeout(callback, ms);
+    },
+    cancel(handle: ViewSwitcherTimerHandle): void {
+        clearTimeout(handle as ReturnType<typeof setTimeout>);
+    },
+};
+
+/**
+ * Build a switcher button's icon node, carrying its own position class.
+ *
+ * The core resolves NULL/empty to `image-missing` (which the stylesheet carries
+ * a real glyph for); the `-symbolic` strip and the CSS-token guard are
+ * `normalizeIconName`'s, applied by `<adw-icon>` — that strip is this package's
+ * own mask-class convention and has no counterpart in C, where the name reaches
+ * `GtkImage` untouched.
+ */
+export function createSwitcherIcon(iconName: string, extra: string): AdwIcon {
+    return createAdwIcon(viewSwitcherIconName(iconName), extra);
+}
+
+/** Repaint an existing switcher icon from a page's declared name. */
+export function applySwitcherIcon(icon: AdwIcon, iconName: string): void {
+    icon.iconName = viewSwitcherIconName(iconName);
+}
+
+/**
+ * Read a declared page element into the core's page init.
+ *
+ * `getAttribute` returns `null` for an absent attribute, which is EXACTLY C's
+ * NULL — so the values are passed through unchanged rather than defaulted to
+ * `''`. That `?? ''` is what made the button-visibility rule unimplementable in
+ * the old code: once an absent title has become the empty string, "the page has
+ * no title" is no longer expressible.
+ */
+export function readSwitcherPage(element: Element): AdwViewSwitcherPageInit {
+    const badge = Number.parseInt(element.getAttribute('badge-number') ?? '', 10);
+    return {
+        // A page with no `name` is the page named '' — the same choice
+        // `<adw-view-stack>` made, and for the same reason: C stores the name
+        // verbatim (adw-view-stack.c:1170) and an invented `page-<index>` is
+        // addressable by a name the author never wrote.
+        name: element.getAttribute('name') ?? '',
+        title: element.getAttribute('title'),
+        iconName: element.getAttribute('icon-name'),
+        // `hidden` is the DOM spelling of AdwViewStackPage:visible.
+        visible: !element.hasAttribute('hidden'),
+        useUnderline: element.hasAttribute('use-underline'),
+        badgeNumber: Number.isNaN(badge) ? 0 : badge,
+        needsAttention: element.hasAttribute('needs-attention'),
+    };
+}
+
+/**
+ * Paint `AdwIndicatorBin`'s badge/dot onto a span: the badge text when there is
+ * one, a bare dot when only `needs-attention` is set, nothing otherwise
+ * (adw-indicator-bin.c:58-68 + the `.needs-attention` style class).
+ */
+export function applyIndicator(indicator: HTMLElement, badgeLabel: string, needsAttention: boolean): void {
+    indicator.textContent = badgeLabel;
+    indicator.classList.toggle('needs-attention', needsAttention && badgeLabel.length === 0);
+    indicator.hidden = badgeLabel.length === 0 && !needsAttention;
+}
+
+/**
+ * Mirror the derived screen-reader description onto the element, REMOVING the
+ * attribute when there is none — `update_description_cb` resets the accessible
+ * property rather than setting it to `""` (adw-view-switcher-button.c:104-113).
+ */
+export function applyDescription(element: HTMLElement, description: string): void {
+    if (description) element.setAttribute('aria-description', description);
+    else element.removeAttribute('aria-description');
+}