@adia-ai/web-components 0.6.36 → 0.6.37

package/components/number-format/number-format.class.js

@@ -0,0 +1,96 @@
+/**
+ * Non-side-effect class export for `<number-format-ui>`.
+ *
+ * Importing this file gives you the class without auto-registering the
+ * tag. Useful for test isolation, subclassing with tag-name override,
+ * or selective composition.
+ *
+ * The auto-register path stays at `@adia-ai/web-components/components/number-format`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <number-format-ui value="1234567.89"></number-format-ui>             → 1,234,567.89
+ * <number-format-ui value="1299.99" number-style="currency" currency="USD"></number-format-ui>  → $1,299.99
+ * <number-format-ui value="0.876" number-style="percent"></number-format-ui>                    → 87.6%
+ * <number-format-ui value="1234567" notation="compact"></number-format-ui>                       → 1.2M
+ *
+ * Read-only display primitive wrapping `Intl.NumberFormat`. Distinct
+ * from `<input-ui type="number">` (a form-input primitive).
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UINumberFormat extends UIElement {
+  static properties = {
+    value:                  { type: Number, default: 0,         reflect: true },
+    numberStyle:            { type: String, default: 'decimal', reflect: true, attribute: 'number-style' },
+    currency:               { type: String, default: '',        reflect: true },
+    unit:                   { type: String, default: '',        reflect: true },
+    notation:               { type: String, default: 'standard', reflect: true },
+    compactDisplay:         { type: String, default: 'short',   reflect: true, attribute: 'compact-display' },
+    minimumFractionDigits:  { type: Number, default: 0,         reflect: true, attribute: 'minimum-fraction-digits' },
+    maximumFractionDigits:  { type: Number, default: 2,         reflect: true, attribute: 'maximum-fraction-digits' },
+    locale:                 { type: String, default: '',        reflect: true },
+    signDisplay:            { type: String, default: 'auto',    reflect: true, attribute: 'sign-display' },
+  };
+
+  static template = () => null;
+
+  #resolveLocale() {
+    if (this.locale) return this.locale;
+    return this.ownerDocument?.documentElement?.lang || undefined;
+  }
+
+  #format() {
+    const v = Number(this.value);
+    if (!Number.isFinite(v)) return '';
+
+    // Validate required dependent props per style.
+    if (this.numberStyle === 'currency' && !this.currency) return '';
+    if (this.numberStyle === 'unit' && !this.unit) return '';
+
+    /** @type {Intl.NumberFormatOptions} */
+    const opts = {
+      style: this.numberStyle,
+      notation: this.notation,
+      signDisplay: this.signDisplay,
+    };
+    if (this.numberStyle === 'currency') opts.currency = this.currency;
+    if (this.numberStyle === 'unit')     opts.unit = this.unit;
+    if (this.notation === 'compact')     opts.compactDisplay = this.compactDisplay;
+    // Honor min/max fraction digits when explicitly set. The defaults
+    // (0 / 2) are reasonable for decimal+currency; compact notation
+    // typically wants 1 max but we let consumers override.
+    if (Number.isFinite(this.minimumFractionDigits)) opts.minimumFractionDigits = this.minimumFractionDigits;
+    if (Number.isFinite(this.maximumFractionDigits)) opts.maximumFractionDigits = this.maximumFractionDigits;
+
+    try {
+      return new Intl.NumberFormat(this.#resolveLocale(), opts).format(v);
+    } catch {
+      return String(v);
+    }
+  }
+
+  connected() {
+    super.connected();
+    // No special role — the rendered text is read by AT naturally; we
+    // expose the raw value via aria-label for screen-reader clarity in
+    // contexts where the formatted glyphs ("€", "M") might be parsed
+    // unpredictably by different readers.
+  }
+
+  render() {
+    const text = this.#format();
+    this.textContent = text;
+    // Mirror raw value via aria-label so screen readers can read the
+    // underlying number alongside the formatted glyphs.
+    if (text && Number.isFinite(Number(this.value))) {
+      this.setAttribute('aria-label', `${text} (raw: ${this.value})`);
+    } else {
+      this.removeAttribute('aria-label');
+    }
+  }
+}

package/components/number-format/number-format.css

@@ -0,0 +1,18 @@
+/* ═══════════════════════════════════════════════════════════════
+   NUMBER-FORMAT-UI — Read-only formatted numeric display.
+   ═══════════════════════════════════════════════════════════════ */
+
+@scope (number-format-ui) {
+  :where(:scope) {
+    --number-format-fg-default: inherit;
+    --number-format-font-default: inherit;
+  }
+
+  :scope {
+    display: inline;
+    color: var(--number-format-fg, var(--number-format-fg-default));
+    font-family: var(--number-format-font, var(--number-format-font-default));
+    /* Tabular figures so column-aligned numeric displays line up cleanly. */
+    font-variant-numeric: tabular-nums;
+  }
+}

package/components/number-format/number-format.d.ts

@@ -0,0 +1,68 @@
+/**
+ * `<number-format-ui>` — Display a numeric value with locale-aware formatting — currency,
+percentage, compact (1.2K / 3.4M), unit, or plain decimal. Wraps
+`Intl.NumberFormat`. Distinct from `<input-ui type="number">`
+(an INPUT primitive); this is a DISPLAY primitive — read-only, no
+form participation, no keyboard handling. Pair with `<stat-ui>` for
+KPI surfaces or use standalone inline within prose.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/number-format
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UINumberFormat extends UIElement {
+  /** When [notation="compact"], controls the compact-form length.
+`short` = "1.2M" (default); `long` = "1.2 million".
+ */
+  compactDisplay: 'short' | 'long';
+  /** ISO 4217 currency code (e.g. "USD", "EUR", "JPY"). Required when
+[number-style="currency"]; ignored otherwise.
+ */
+  currency: string;
+  /** BCP-47 locale tag for the formatter. Empty defaults to the
+document locale (`<html lang>`) then to browser default.
+ */
+  locale: string;
+  /** Maximum fractional digits (0–20). Default `2` for decimal/
+currency/percent, `1` for compact notation.
+ */
+  maximumFractionDigits: number;
+  /** Minimum fractional digits (0–20). Padded with trailing zeros.
+Useful for currency display to force ".00" suffix.
+ */
+  minimumFractionDigits: number;
+  /** `Intl.NumberFormat` `notation` option. `standard` is the
+thousands-grouped form (1,234,567); `compact` is the abbreviated
+form (1.2M); `scientific` and `engineering` are the exponent
+forms. Defaults to `standard`.
+ */
+  notation: 'standard' | 'compact' | 'scientific' | 'engineering';
+  /** `Intl.NumberFormat` `style` option. `decimal` (default) renders a
+plain number with locale-aware grouping. `currency` requires
+[currency] to be set. `percent` formats 0–1 as 0%–100%. `unit`
+requires [unit] to be set (e.g. "kilobyte", "celsius").
+ */
+  numberStyle: 'decimal' | 'currency' | 'percent' | 'unit';
+  /** `Intl.NumberFormat` `signDisplay` option. `auto` (default) shows
+"−" for negatives only; `always` shows "+" / "−"; `exceptZero`
+shows sign for non-zero only; `never` hides signs.
+ */
+  signDisplay: 'auto' | 'always' | 'exceptZero' | 'never';
+  /** `Intl.NumberFormat` unit identifier (e.g. "kilometer-per-hour",
+"celsius", "byte"). Required when [number-style="unit"]; ignored
+otherwise. See MDN's NumberFormat docs for the valid set.
+ */
+  unit: string;
+  /** The numeric value to format. Empty string or non-numeric value
+renders nothing.
+ */
+  value: number;
+}

package/components/number-format/number-format.js

@@ -0,0 +1,17 @@
+/**
+ * `<number-format-ui>` — auto-registers the tag on import.
+ *
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
+ *
+ *   import { UINumberFormat } from '@adia-ai/web-components/components/number-format/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+import { defineIfFree } from '../../core/register.js';
+import { UINumberFormat } from './number-format.class.js';
+
+defineIfFree('number-format-ui', UINumberFormat);
+
+export { UINumberFormat };

package/components/number-format/number-format.yaml

@@ -0,0 +1,204 @@
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UINumberFormat
+tag: number-format-ui
+status: stable
+component: NumberFormat
+category: display
+version: 1
+description: |
+  Display a numeric value with locale-aware formatting — currency,
+  percentage, compact (1.2K / 3.4M), unit, or plain decimal. Wraps
+  `Intl.NumberFormat`. Distinct from `<input-ui type="number">`
+  (an INPUT primitive); this is a DISPLAY primitive — read-only, no
+  form participation, no keyboard handling. Pair with `<stat-ui>` for
+  KPI surfaces or use standalone inline within prose.
+props:
+  value:
+    description: |
+      The numeric value to format. Empty string or non-numeric value
+      renders nothing.
+    type: number
+    default: 0
+    reflect: true
+  numberStyle:
+    description: |
+      `Intl.NumberFormat` `style` option. `decimal` (default) renders a
+      plain number with locale-aware grouping. `currency` requires
+      [currency] to be set. `percent` formats 0–1 as 0%–100%. `unit`
+      requires [unit] to be set (e.g. "kilobyte", "celsius").
+    type: string
+    default: decimal
+    enum: [decimal, currency, percent, unit]
+    reflect: true
+    attribute: number-style
+  currency:
+    description: |
+      ISO 4217 currency code (e.g. "USD", "EUR", "JPY"). Required when
+      [number-style="currency"]; ignored otherwise.
+    type: string
+    default: ""
+    reflect: true
+  unit:
+    description: |
+      `Intl.NumberFormat` unit identifier (e.g. "kilometer-per-hour",
+      "celsius", "byte"). Required when [number-style="unit"]; ignored
+      otherwise. See MDN's NumberFormat docs for the valid set.
+    type: string
+    default: ""
+    reflect: true
+  notation:
+    description: |
+      `Intl.NumberFormat` `notation` option. `standard` is the
+      thousands-grouped form (1,234,567); `compact` is the abbreviated
+      form (1.2M); `scientific` and `engineering` are the exponent
+      forms. Defaults to `standard`.
+    type: string
+    default: standard
+    enum: [standard, compact, scientific, engineering]
+    reflect: true
+  compactDisplay:
+    description: |
+      When [notation="compact"], controls the compact-form length.
+      `short` = "1.2M" (default); `long` = "1.2 million".
+    type: string
+    default: short
+    enum: [short, long]
+    reflect: true
+    attribute: compact-display
+  minimumFractionDigits:
+    description: |
+      Minimum fractional digits (0–20). Padded with trailing zeros.
+      Useful for currency display to force ".00" suffix.
+    type: number
+    default: 0
+    reflect: true
+    attribute: minimum-fraction-digits
+  maximumFractionDigits:
+    description: |
+      Maximum fractional digits (0–20). Default `2` for decimal/
+      currency/percent, `1` for compact notation.
+    type: number
+    default: 2
+    reflect: true
+    attribute: maximum-fraction-digits
+  locale:
+    description: |
+      BCP-47 locale tag for the formatter. Empty defaults to the
+      document locale (`<html lang>`) then to browser default.
+    type: string
+    default: ""
+    reflect: true
+  signDisplay:
+    description: |
+      `Intl.NumberFormat` `signDisplay` option. `auto` (default) shows
+      "−" for negatives only; `always` shows "+" / "−"; `exceptZero`
+      shows sign for non-zero only; `never` hides signs.
+    type: string
+    default: auto
+    enum: [auto, always, exceptZero, never]
+    reflect: true
+    attribute: sign-display
+events: {}
+slots: {}
+states:
+  - name: idle
+    description: Default, displaying the formatted value.
+traits: []
+tokens: {}
+a2ui:
+  rules:
+    - rule: "Use for read-only numeric display with locale-aware formatting. For numeric INPUT use <input-ui type=number>; for KPI big-number display use <stat-ui>."
+      reason: "Display vs input vs metric separation."
+    - rule: "[number-style=currency] REQUIRES [currency] to be set to a valid ISO 4217 code. Without it the element renders nothing rather than producing malformed output."
+      reason: "Currency contract."
+    - rule: "[number-style=percent] treats the [value] as a fraction (0.5 → 50%). To display 50 as '50%' pass value=0.5 OR keep [number-style=decimal] and append '%' manually."
+      reason: "Percent semantics — Intl.NumberFormat convention."
+    - rule: "Compact notation auto-defaults maximumFractionDigits to 1. Override only when extra precision is needed (rare for compact display — defeats the purpose)."
+      reason: "Sensible defaults."
+anti_patterns:
+  - wrong: |
+      <number-format-ui value="50" number-style="percent"></number-format-ui>
+    why: |
+      Renders "5,000%" — Intl.NumberFormat percent style multiplies the
+      input by 100. value=50 means "5000%".
+    fix: |
+      <number-format-ui value="0.5" number-style="percent"></number-format-ui>
+  - wrong: |
+      <number-format-ui value="9.99" number-style="currency"></number-format-ui>
+    why: |
+      Missing [currency] code. Renders nothing rather than producing
+      malformed currency output.
+    fix: |
+      <number-format-ui value="9.99" number-style="currency" currency="USD"></number-format-ui>
+examples:
+  - name: decimal
+    description: Plain locale-grouped number — default style.
+    a2ui: |
+      [
+        {
+          "id": "n",
+          "component": "NumberFormat",
+          "value": 1234567.89
+        }
+      ]
+  - name: currency
+    description: USD currency display.
+    a2ui: |
+      [
+        {
+          "id": "n",
+          "component": "NumberFormat",
+          "value": 1299.99,
+          "numberStyle": "currency",
+          "currency": "USD"
+        }
+      ]
+  - name: percent
+    description: Fraction → percent (0.876 → 87.6%).
+    a2ui: |
+      [
+        {
+          "id": "n",
+          "component": "NumberFormat",
+          "value": 0.876,
+          "numberStyle": "percent",
+          "maximumFractionDigits": 1
+        }
+      ]
+  - name: compact
+    description: Compact-form (1.2M, 3.4K).
+    a2ui: |
+      [
+        {
+          "id": "n",
+          "component": "NumberFormat",
+          "value": 1234567,
+          "notation": "compact"
+        }
+      ]
+keywords:
+  - number-format
+  - format
+  - currency
+  - percent
+  - percentage
+  - compact
+  - number
+  - locale
+  - intl
+synonyms:
+  number:
+    - number-format
+    - format
+  currency:
+    - number-format
+    - money
+    - price
+  percent:
+    - number-format
+    - percentage
+related:
+  - stat
+  - text
+  - badge
+  - input

package/components/pagination/pagination.a2ui.json

@@ -26,14 +26,28 @@
       "type": "number",
       "default": 1
     },
+    "size": {
+      "description": "Universal size — threads through to every nested `<button-ui size=…>`\nso pagination honors the substrate's 24/30/36 px size system\n(with [density] modifier). Default `md` matches `<button-ui>`'s\ndefault; pass `size=\"sm\"` for a denser numbered row.\n",
+      "type": "string",
+      "enum": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": "md"
+    },
     "total": {
       "description": "Total number of pages.",
       "type": "number",
       "default": 1
     },
     "variant": {
-      "description": "Visual variant",
+      "description": "Visual variant — `default` (ghost buttons w/ hover bg) or `button` (1×1 bordered cells; active page filled).",
       "type": "string",
+      "enum": [
+        "default",
+        "button"
+      ],
       "default": "default"
     }
   },
@@ -44,7 +58,10 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "navigation",
-    "composes": [],
+    "composes": [
+      "button-ui",
+      "icon-ui"
+    ],
     "events": {
       "page-change": {
         "description": "Fired when a page button is clicked. detail contains { page }.",

package/components/pagination/pagination.class.js

@@ -29,8 +29,18 @@ export class UIPagination extends UIElement {
     total:    { type: Number, default: 1, reflect: true },
     siblings: { type: Number, default: 1, reflect: true },
     variant:  { type: String, default: 'default', reflect: true },
+    // Threads through to every nested <button-ui size=…> so pagination
+    // honors the universal [size] system (sm=24 / md=30 / lg=36 px with
+    // density modifier). Default `md` matches <button-ui>'s default —
+    // pagination is a button-ui composite, so the canonical size is the
+    // same. Authors who want a denser numbered row pass [size="sm"].
+    size:     { type: String, default: 'md', reflect: true },
   };
 
+  // Phosphor icons stamped by this primitive (prev/next chevrons inside
+  // the nested <button-ui>). Audited by check-required-icons.mjs.
+  static requiredIcons = ['caret-left', 'caret-right'];
+
   static template = () => null;
 
   #nav = null;
@@ -46,12 +56,15 @@ export class UIPagination extends UIElement {
 
     if (!this.#bound) {
       this.#bound = true;
-      this.#nav.addEventListener('click', this.#onClick);
+      // `press` is the canonical button-ui event — fires only when not
+      // disabled (button-ui stops native click propagation on disabled
+      // state), so we get the right gating for free.
+      this.#nav.addEventListener('press', this.#onPress);
     }
   }
 
   disconnected() {
-    this.#nav?.removeEventListener('click', this.#onClick);
+    this.#nav?.removeEventListener('press', this.#onPress);
     this.#nav = null;
     this.#bound = false;
   }
@@ -81,42 +94,70 @@ export class UIPagination extends UIElement {
 
   #buildRange(page, total, siblings) {
     const items = [];
-
-    // Prev button
     items.push({ key: 'prev', type: 'prev', value: page - 1 });
 
-    // Always show first
-    items.push({ key: 'page-1', type: 'page', value: 1 });
-
-    const start = Math.max(2, page - siblings);
-    const end = Math.min(total - 1, page + siblings);
-
-    // Left ellipsis
-    if (start > 2) {
-      items.push({ key: 'ellipsis-start', type: 'ellipsis' });
-    }
-
-    // Sibling pages
-    for (let i = start; i <= end; i++) {
-      items.push({ key: `page-${i}`, type: 'page', value: i });
-    }
-
-    // Right ellipsis
-    if (end < total - 1) {
-      items.push({ key: 'ellipsis-end', type: 'ellipsis' });
-    }
-
-    // Always show last (if more than 1 page)
-    if (total > 1) {
-      items.push({ key: `page-${total}`, type: 'page', value: total });
+    // W = constant compact-mode width (visible page cells, incl ellipses).
+    //   = 2 bookends + (2*siblings + 1 sibling window) + 2 ellipsis slots
+    // siblings=1 → W=7; siblings=2 → W=9.
+    // Holding W invariant across page positions prevents the layout from
+    // jumping when the current page advances by one — fixes the wobble
+    // where page=3 showed 6 cells but page=4 showed 7.
+    const W = 2 * siblings + 5;
+
+    if (total <= W) {
+      // Small total — show every page, never ellipsis. No need to compact
+      // when compacting wouldn't save horizontal slots.
+      for (let i = 1; i <= total; i++) {
+        items.push({ key: `page-${i}`, type: 'page', value: i });
+      }
+    } else {
+      // Compact mode. Three layouts, each yielding exactly W cells so the
+      // row width stays constant under any page advance.
+      const nearStart = page <= siblings + 3;
+      const nearEnd = page >= total - siblings - 2;
+
+      if (nearStart) {
+        // 1..(W-2), ellipsis, total. The left window expands rightward to
+        // fill the slot a left ellipsis would have used.
+        const leftEnd = W - 2;
+        for (let i = 1; i <= leftEnd; i++) {
+          items.push({ key: `page-${i}`, type: 'page', value: i });
+        }
+        items.push({ key: 'ellipsis-end', type: 'ellipsis' });
+        items.push({ key: `page-${total}`, type: 'page', value: total });
+      } else if (nearEnd) {
+        // 1, ellipsis, (total-W+3)..total. Right window expands leftward.
+        items.push({ key: 'page-1', type: 'page', value: 1 });
+        items.push({ key: 'ellipsis-start', type: 'ellipsis' });
+        const rightStart = total - W + 3;
+        for (let i = rightStart; i <= total; i++) {
+          items.push({ key: `page-${i}`, type: 'page', value: i });
+        }
+      } else {
+        // Middle. 1, ellipsis, current±siblings, ellipsis, total.
+        items.push({ key: 'page-1', type: 'page', value: 1 });
+        items.push({ key: 'ellipsis-start', type: 'ellipsis' });
+        for (let i = page - siblings; i <= page + siblings; i++) {
+          items.push({ key: `page-${i}`, type: 'page', value: i });
+        }
+        items.push({ key: 'ellipsis-end', type: 'ellipsis' });
+        items.push({ key: `page-${total}`, type: 'page', value: total });
+      }
     }
 
-    // Next button
     items.push({ key: 'next', type: 'next', value: page + 1 });
-
     return items;
   }
 
+  // The non-active button variant \u2014 `ghost` for default mode (chrome-less
+  // hover), `outline` for variant="button" mode (1\u00D71 bordered cells).
+  // Active items always use `primary` so the active-state token chain
+  // comes from button-ui's primary surface matrix (no re-implementing
+  // a separate accent fill at the pagination tier).
+  #restVariant() {
+    return this.variant === 'button' ? 'outline' : 'ghost';
+  }
+
   #createItem(item, page) {
     if (item.type === 'ellipsis') {
       const span = document.createElement('span');
@@ -125,21 +166,21 @@ export class UIPagination extends UIElement {
       return span;
     }
 
-    const btn = document.createElement('button');
-    btn.setAttribute('type', 'button');
+    const btn = document.createElement('button-ui');
+    btn.setAttribute('size', this.size);
 
     if (item.type === 'prev') {
       btn.setAttribute('data-prev', '');
+      btn.setAttribute('icon', 'caret-left');
       btn.setAttribute('aria-label', 'Previous page');
-      btn.textContent = '\u2039';
     } else if (item.type === 'next') {
       btn.setAttribute('data-next', '');
+      btn.setAttribute('icon', 'caret-right');
       btn.setAttribute('aria-label', 'Next page');
-      btn.textContent = '\u203A';
     } else {
       btn.setAttribute('data-page', '');
       btn.dataset.value = String(item.value);
-      btn.textContent = String(item.value);
+      btn.setAttribute('text', String(item.value));
       btn.setAttribute('aria-label', `Page ${item.value}`);
     }
 
@@ -150,27 +191,39 @@ export class UIPagination extends UIElement {
   #updateItem(el, item, page) {
     if (item.type === 'ellipsis') return;
 
+    // Keep size in sync \u2014 the host's [size] may change between renders.
+    el.setAttribute('size', this.size);
+
     if (item.type === 'prev') {
+      el.setAttribute('variant', this.#restVariant());
       if (page <= 1) { el.setAttribute('disabled', ''); el.setAttribute('tabindex', '-1'); }
       else { el.removeAttribute('disabled'); el.setAttribute('tabindex', '0'); }
     } else if (item.type === 'next') {
+      el.setAttribute('variant', this.#restVariant());
       if (page >= this.total) { el.setAttribute('disabled', ''); el.setAttribute('tabindex', '-1'); }
       else { el.removeAttribute('disabled'); el.setAttribute('tabindex', '0'); }
     } else {
       el.dataset.value = String(item.value);
-      el.textContent = String(item.value);
+      el.setAttribute('text', String(item.value));
       el.setAttribute('aria-label', `Page ${item.value}`);
       if (item.value === page) {
+        // Active page reads as `variant="primary"` so the filled-accent
+        // state comes from button-ui's primary surface matrix (the
+        // canonical token chain) \u2014 not a pagination-tier re-impl.
+        el.setAttribute('variant', 'primary');
         el.setAttribute('data-active', '');
         el.setAttribute('aria-current', 'page');
       } else {
+        el.setAttribute('variant', this.#restVariant());
         el.removeAttribute('data-active');
         el.removeAttribute('aria-current');
       }
     }
   }
 
-  #onClick = (e) => {
+  #onPress = (e) => {
+    // `press` fires on the <button-ui> itself, which is exactly the
+    // element carrying the data-prev / data-next / data-page marker.
     const btn = e.target.closest('[data-prev], [data-next], [data-page]');
     if (!btn || btn.hasAttribute('disabled') || !this.#nav.contains(btn)) return;