@adia-ai/web-components 0.6.35 → 0.6.37

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;
 

package/components/pagination/pagination.css

@@ -1,42 +1,24 @@
 /* ═══════════════════════════════════════════════════════════════
-   PAGINATION-N — Page navigation with numbers and prev/next.
+   PAGINATION-UI — Page navigation with prev/next + numbered cells.
+   Composes <button-ui> for every interactive cell, so chrome, size,
+   focus-ring, hover, disabled, and active (primary fill) all come
+   from button-ui's token chain. Pagination owns only:
+     - the nav-row layout (flex + gap)
+     - the ellipsis cell (a plain <span>, not interactive)
+     - one shape mode (`variant="button"` switches button-ui's
+       composed variant to `outline` for 1×1 bordered cells)
    ═══════════════════════════════════════════════════════════════ */
 
 @scope (pagination-ui) {
   :where(:scope) {
     /* ── Layout ── */
     --pagination-gap-default:          var(--a-space-1);
-    --pagination-button-size-default:  var(--a-size-sm);
-    --pagination-button-px-default:    var(--a-space-1);
-    --pagination-radius-default:       var(--a-radius-sm);
 
-    /* ── Typography ── */
-    --pagination-font-default:         var(--a-ui-size);
-
-    /* ── Colors ── */
-    --pagination-fg-default:           var(--a-fg-subtle);
-    --pagination-fg-hover-default:     var(--a-fg);
-    --pagination-fg-active-default:    var(--a-chrome-light);
-    --pagination-fg-muted-default:     var(--a-fg-muted);
-    --pagination-bg-hover-default:     var(--a-bg-muted);
-    --pagination-bg-active-default:    var(--a-accent);
-    --pagination-fg-disabled-default:  var(--a-ui-text-disabled);
-
-    /* ── Transition ── */
-    --pagination-duration-default:     var(--a-duration-fast);
-    --pagination-easing-default:       var(--a-easing);
-
-    /* ── State ── */
-    --pagination-focus-ring-default:   var(--a-focus-ring);
-
-    /* ── Nav (button variant chrome) ── */
-    --pagination-nav-bg-default:           transparent;
-    --pagination-nav-border-default:       transparent;
-    --pagination-nav-border-hover-default: transparent;
-    --pagination-nav-bg-disabled-default:  transparent;
-    --pagination-nav-border-disabled-default: transparent;
+    /* ── Ellipsis cell (the only piece pagination styles directly) ── */
+    --pagination-ellipsis-fg-default:  var(--a-fg-muted);
+    --pagination-ellipsis-font-default: var(--a-ui-size);
     text-align: start;  /* §text-align-reset — blocks inheritance from centered ancestors */
-}
+  }
 
   :scope {
     /* ── Base ── */
@@ -51,115 +33,38 @@
     gap: var(--pagination-gap, var(--pagination-gap-default));
   }
 
-  /* ── All buttons ── */
-  [slot="nav"] button {
-    box-sizing: border-box;
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
-    min-width: var(--pagination-button-size, var(--pagination-button-size-default));
-    height: var(--pagination-button-size, var(--pagination-button-size-default));
-    padding: 0 var(--pagination-button-px, var(--pagination-button-px-default));
-    border: none;
-    background: none;
-    border-radius: var(--pagination-radius, var(--pagination-radius-default));
-    font: inherit;
-    font-size: var(--pagination-font, var(--pagination-font-default));
-    color: var(--pagination-fg, var(--pagination-fg-default));
-    cursor: pointer;
-    user-select: none;
-    line-height: 1;
-    transition:
-      background var(--pagination-duration, var(--pagination-duration-default)) var(--pagination-easing, var(--pagination-easing-default)),
-      border-color var(--pagination-duration, var(--pagination-duration-default)) var(--pagination-easing, var(--pagination-easing-default)),
-      color var(--pagination-duration, var(--pagination-duration-default)) var(--pagination-easing, var(--pagination-easing-default)),
-      box-shadow var(--pagination-duration, var(--pagination-duration-default)) var(--pagination-easing, var(--pagination-easing-default));
-  }
-
-  [slot="nav"] button:not([disabled]):hover {
-    background: var(--pagination-bg-hover, var(--pagination-bg-hover-default));
-    color: var(--pagination-fg-hover, var(--pagination-fg-hover-default));
-  }
-
-  /* ── Active page ── */
-  [slot="nav"] button[data-active] {
-    background: var(--pagination-bg-active, var(--pagination-bg-active-default));
-    color: var(--pagination-fg-active, var(--pagination-fg-active-default));
-  }
-
-  [slot="nav"] button[data-active]:hover {
-    background: var(--pagination-bg-active, var(--pagination-bg-active-default));
-    color: var(--pagination-fg-active, var(--pagination-fg-active-default));
+  /* ── Nested button-ui sizing handoff ──
+     button-ui resolves height + min-width from `--a-size` (= 24/30/36 px
+     at sm/md/lg per the universal size system). We set --a-icon-size for
+     prev/next so the caret reads at typographic optical-size pairing
+     with the page-number labels (0.875em ≈ 14px at 16px base). */
+  [slot="nav"] button-ui {
+    --a-icon-size: 0.875em;
   }
 
-  /* ── Disabled (prev/next at boundaries) ── */
-  [slot="nav"] button[disabled] {
-    color: var(--pagination-fg-disabled, var(--pagination-fg-disabled-default));
-    cursor: not-allowed;
-    pointer-events: none;
-  }
-
-  /* ── Ellipsis ── */
+  /* ── Ellipsis (plain text span — not interactive) ── */
   [slot="nav"] [data-ellipsis] {
     box-sizing: border-box;
     display: inline-flex;
     align-items: center;
     justify-content: center;
-    min-width: var(--pagination-button-size, var(--pagination-button-size-default));
-    height: var(--pagination-button-size, var(--pagination-button-size-default));
-    color: var(--pagination-fg-muted, var(--pagination-fg-muted-default));
-    font-size: var(--pagination-font, var(--pagination-font-default));
+    /* Match the height of the nested button-ui so the row baseline aligns */
+    min-width: var(--a-size);
+    height: var(--a-size);
+    color: var(--pagination-ellipsis-fg, var(--pagination-ellipsis-fg-default));
+    font-size: var(--pagination-ellipsis-font, var(--pagination-ellipsis-font-default));
     pointer-events: none;
     user-select: none;
     line-height: 1;
   }
 
-  /* ── Focus visible ── */
-  [slot="nav"] button:focus-visible {
-    outline: none;
-    box-shadow: var(--pagination-focus-ring, var(--pagination-focus-ring-default));
-  }
-
-  /* ═══════════════════════════════════════════════════════════
-     VARIANT: button — square 1:1 aspect-ratio page buttons
-     ═══════════════════════════════════════════════════════════ */
-
-  :scope[variant="button"] {
-    --pagination-nav-bg-default:              var(--a-bg);
-    --pagination-nav-border-default:          var(--a-border-subtle);
-    --pagination-nav-border-hover-default:    var(--a-border);
-    --pagination-nav-bg-disabled-default:     var(--a-bg);
-    --pagination-nav-border-disabled-default: var(--a-border-subtle);
-  }
-
-  :scope[variant="button"] [slot="nav"] button {
-    width: var(--pagination-button-size, var(--pagination-button-size-default));
-    min-width: var(--pagination-button-size, var(--pagination-button-size-default));
-    height: var(--pagination-button-size, var(--pagination-button-size-default));
-    padding: 0;
+  /* ── variant="button" — square 1:1 cells via outline button-ui ──
+     The class JS swaps each non-active button-ui from `variant="ghost"`
+     to `variant="outline"` in this mode. CSS only nudges the inactive
+     buttons to be square (button-ui's default min-width = height, but
+     ghost-mode buttons can collapse below that — outline buttons keep
+     aspect-ratio 1 here for the bordered-cell look). */
+  :scope[variant="button"] [slot="nav"] button-ui {
     aspect-ratio: 1;
-    border: 1px solid var(--pagination-nav-border, var(--pagination-nav-border-default));
-    border-radius: var(--pagination-radius, var(--pagination-radius-default));
-    background: var(--pagination-nav-bg, var(--pagination-nav-bg-default));
-  }
-
-  :scope[variant="button"] [slot="nav"] button:not([disabled]):hover {
-    border-color: var(--pagination-nav-border-hover, var(--pagination-nav-border-hover-default));
-    background: var(--pagination-bg-hover, var(--pagination-bg-hover-default));
-  }
-
-  :scope[variant="button"] [slot="nav"] button[data-active] {
-    border-color: transparent;
-    background: var(--pagination-bg-active, var(--pagination-bg-active-default));
-    color: var(--pagination-fg-active, var(--pagination-fg-active-default));
-  }
-
-  :scope[variant="button"] [slot="nav"] button[data-active]:hover {
-    background: var(--pagination-bg-active, var(--pagination-bg-active-default));
-  }
-
-  :scope[variant="button"] [slot="nav"] button[disabled] {
-    border-color: var(--pagination-nav-border-disabled, var(--pagination-nav-border-disabled-default));
-    background: var(--pagination-nav-bg-disabled, var(--pagination-nav-bg-disabled-default));
   }
 }

package/components/pagination/pagination.d.ts

@@ -24,10 +24,16 @@ export class UIPagination extends UIElement {
   page: number;
   /** Number of page buttons to show on each side of the current page. */
   siblings: number;
+  /** Universal size — threads through to every nested `<button-ui size=…>`
+so pagination honors the substrate's 24/30/36 px size system
+(with [density] modifier). Default `md` matches `<button-ui>`'s
+default; pass `size="sm"` for a denser numbered row.
+ */
+  size: 'sm' | 'md' | 'lg';
   /** Total number of pages. */
   total: number;
-  /** Visual variant */
-  variant: string;
+  /** Visual variant — `default` (ghost buttons w/ hover bg) or `button` (1×1 bordered cells; active page filled). */
+  variant: 'default' | 'button';
 
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,

package/components/pagination/pagination.test.js

@@ -0,0 +1,195 @@
+/**
+ * pagination-ui — regression guards for the v0.6.36 native-primitive
+ * leak fix and the universal [size] system threading.
+ *
+ * Before the fix, every page / prev / next item was a raw <button>,
+ * and pagination hardcoded `--a-size-sm` for its button cells (no
+ * [size] prop, no threading to the substrate's 24/30/36 px size
+ * system). After the fix, every item is a <button-ui> whose `size`
+ * attribute mirrors the host's, and active items render as
+ * `variant="primary"` so the filled-accent state comes from
+ * button-ui's primary surface matrix.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import '../../core/element.js';
+import './pagination.js';
+import '../button/button.js';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const CLASS_JS = readFileSync(resolve(HERE, 'pagination.class.js'), 'utf8');
+
+const tick = () => new Promise((r) => queueMicrotask(r));
+
+function mount(html) {
+  const wrap = document.createElement('div');
+  wrap.innerHTML = html;
+  document.body.appendChild(wrap);
+  return wrap.firstElementChild;
+}
+
+beforeEach(() => { document.body.innerHTML = ''; });
+
+// ── Source-grep contract guards ─────────────────────────────────────
+
+describe('pagination-ui — no native <button> leak', () => {
+  it('class.js creates <button-ui> elements (not raw <button>)', () => {
+    expect(CLASS_JS).toMatch(/createElement\(['"]button-ui['"]\)/);
+    // Negative — guard against accidental revert to raw <button>.
+    expect(CLASS_JS).not.toMatch(/createElement\(['"]button['"]\)/);
+  });
+
+  it('declares caret-left + caret-right in static requiredIcons', () => {
+    expect(CLASS_JS).toMatch(/static\s+requiredIcons\s*=\s*\[[^\]]*['"]caret-left['"]/);
+    expect(CLASS_JS).toMatch(/static\s+requiredIcons\s*=\s*\[[^\]]*['"]caret-right['"]/);
+  });
+
+  it('declares size prop in static properties (universal [size] thread-through)', () => {
+    expect(CLASS_JS).toMatch(/static\s+properties\s*=[\s\S]*?size:\s*\{\s*type:\s*String/);
+  });
+});
+
+// ── DOM contract guards ─────────────────────────────────────────────
+
+describe('pagination-ui — DOM composition', () => {
+  it('stamps <button-ui> for every page / prev / next cell', async () => {
+    const el = mount('<pagination-ui page="3" total="10"></pagination-ui>');
+    await tick();
+    const buttons = el.querySelectorAll('button-ui');
+    expect(buttons.length).toBeGreaterThan(0);
+    // No raw <button> children — confirms the native-leak is closed at runtime.
+    expect(el.querySelectorAll(':scope button:not(button-ui)').length).toBe(0);
+  });
+
+  it('threads size attribute through to every nested button-ui', async () => {
+    const el = mount('<pagination-ui page="2" total="5" size="lg"></pagination-ui>');
+    await tick();
+    const buttons = el.querySelectorAll('button-ui');
+    expect(buttons.length).toBeGreaterThan(0);
+    for (const btn of buttons) {
+      expect(btn.getAttribute('size')).toBe('lg');
+    }
+  });
+
+  it('defaults to size="md" (aligned with button-ui default)', async () => {
+    const el = mount('<pagination-ui page="2" total="5"></pagination-ui>');
+    await tick();
+    const buttons = el.querySelectorAll('button-ui');
+    expect(buttons.length).toBeGreaterThan(0);
+    for (const btn of buttons) {
+      expect(btn.getAttribute('size')).toBe('md');
+    }
+  });
+
+  it('renders the active page as variant="primary" (button-ui token chain)', async () => {
+    const el = mount('<pagination-ui page="3" total="10"></pagination-ui>');
+    await tick();
+    const active = el.querySelector('button-ui[data-active]');
+    expect(active).toBeTruthy();
+    expect(active.getAttribute('variant')).toBe('primary');
+    expect(active.getAttribute('aria-current')).toBe('page');
+  });
+
+  it('renders prev / next as ghost (default variant) or outline (button variant)', async () => {
+    const elDefault = mount('<pagination-ui page="3" total="10"></pagination-ui>');
+    await tick();
+    expect(elDefault.querySelector('button-ui[data-prev]').getAttribute('variant')).toBe('ghost');
+    expect(elDefault.querySelector('button-ui[data-next]').getAttribute('variant')).toBe('ghost');
+
+    const elButton = mount('<pagination-ui page="3" total="10" variant="button"></pagination-ui>');
+    await tick();
+    expect(elButton.querySelector('button-ui[data-prev]').getAttribute('variant')).toBe('outline');
+    expect(elButton.querySelector('button-ui[data-next]').getAttribute('variant')).toBe('outline');
+  });
+
+  it('uses icon="caret-left" / "caret-right" on prev / next (not glyph text)', async () => {
+    const el = mount('<pagination-ui page="3" total="10"></pagination-ui>');
+    await tick();
+    expect(el.querySelector('button-ui[data-prev]').getAttribute('icon')).toBe('caret-left');
+    expect(el.querySelector('button-ui[data-next]').getAttribute('icon')).toBe('caret-right');
+  });
+});
+
+// ── Width invariance: compact-mode cell count is constant across pages ──
+//
+// Compact width W = 2*siblings + 5 (= 7 at siblings=1). When the current
+// page advances by one, the row's visible cell count must NOT change —
+// otherwise the layout wobbles. For total ≤ W, we show every page and
+// skip compact mode entirely (no point compressing if it doesn't save
+// slots — also wobble-free since every page just highlights a different
+// constant-width row).
+
+describe('pagination-ui — compact-mode width invariance', () => {
+  function pageValues(el) {
+    return [...el.querySelectorAll('button-ui[data-page]')].map((b) => Number(b.dataset.value));
+  }
+  function cellCount(el) {
+    return el.querySelectorAll('button-ui[data-page], [data-ellipsis]').length;
+  }
+  function hasEllipsis(el) {
+    return el.querySelectorAll('[data-ellipsis]').length > 0;
+  }
+
+  it('total=5 siblings=1 → never compacts (shows 1-5 every page)', async () => {
+    for (const page of [1, 2, 3, 4, 5]) {
+      const el = mount(`<pagination-ui page="${page}" total="5" siblings="1"></pagination-ui>`);
+      await tick();
+      expect(pageValues(el)).toEqual([1, 2, 3, 4, 5]);
+      expect(hasEllipsis(el)).toBe(false);
+    }
+  });
+
+  it('total=10 siblings=1 → exactly 7 cells on every page (no wobble)', async () => {
+    for (const page of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]) {
+      const el = mount(`<pagination-ui page="${page}" total="10" siblings="1"></pagination-ui>`);
+      await tick();
+      expect(cellCount(el)).toBe(7);
+    }
+  });
+
+  it('total=10 page=3 siblings=1 → near-start: [1,2,3,4,5,…,10]', async () => {
+    const el = mount('<pagination-ui page="3" total="10" siblings="1"></pagination-ui>');
+    await tick();
+    expect(pageValues(el)).toEqual([1, 2, 3, 4, 5, 10]);
+    expect(el.querySelectorAll('[data-ellipsis]').length).toBe(1);
+  });
+
+  it('total=10 page=4 siblings=1 → still near-start: [1,2,3,4,5,…,10] (same as page=3)', async () => {
+    const el = mount('<pagination-ui page="4" total="10" siblings="1"></pagination-ui>');
+    await tick();
+    expect(pageValues(el)).toEqual([1, 2, 3, 4, 5, 10]);
+    expect(el.querySelectorAll('[data-ellipsis]').length).toBe(1);
+  });
+
+  it('total=10 page=5 siblings=1 → middle: [1,…,4,5,6,…,10]', async () => {
+    const el = mount('<pagination-ui page="5" total="10" siblings="1"></pagination-ui>');
+    await tick();
+    expect(pageValues(el)).toEqual([1, 4, 5, 6, 10]);
+    expect(el.querySelectorAll('[data-ellipsis]').length).toBe(2);
+  });
+
+  it('total=10 page=7 siblings=1 → near-end: [1,…,6,7,8,9,10]', async () => {
+    const el = mount('<pagination-ui page="7" total="10" siblings="1"></pagination-ui>');
+    await tick();
+    expect(pageValues(el)).toEqual([1, 6, 7, 8, 9, 10]);
+    expect(el.querySelectorAll('[data-ellipsis]').length).toBe(1);
+  });
+
+  it('total=20 page=10 siblings=1 → middle: [1,…,9,10,11,…,20]', async () => {
+    const el = mount('<pagination-ui page="10" total="20" siblings="1"></pagination-ui>');
+    await tick();
+    expect(pageValues(el)).toEqual([1, 9, 10, 11, 20]);
+    expect(el.querySelectorAll('[data-ellipsis]').length).toBe(2);
+  });
+
+  it('total=20 siblings=2 → exactly 9 cells on every page', async () => {
+    for (const page of [1, 5, 10, 15, 20]) {
+      const el = mount(`<pagination-ui page="${page}" total="20" siblings="2"></pagination-ui>`);
+      await tick();
+      expect(cellCount(el)).toBe(9);
+    }
+  });
+});

package/components/pagination/pagination.yaml

@@ -13,6 +13,11 @@ description: >-
   range is automatically truncated for high page counts. Use below tables,
   card grids, or list views; for cursor-based pagination use a custom
   load-more <button-ui> instead.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - button-ui  # every page / prev / next slot is a <button-ui> stamp
+  - icon-ui    # caret-left / caret-right inside prev/next via button-ui[icon=…]
 props:
   page:
     description: Current active page number.
@@ -27,9 +32,25 @@ props:
     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
     default: default
+    enum:
+      - default
+      - button
+  size:
+    description: |
+      Universal size — threads through to every nested `<button-ui size=…>`
+      so pagination honors the substrate's 24/30/36 px size system
+      (with [density] modifier). Default `md` matches `<button-ui>`'s
+      default; pass `size="sm"` for a denser numbered row.
+    type: string
+    default: md
+    reflect: true
+    enum:
+      - sm
+      - md
+      - lg
 events:
   page-change:
     description: Fired when a page button is clicked. detail contains { page }.