@kouji-ui/components 0.1.1

package/src/pagination/pagination.css

@@ -0,0 +1,146 @@
+/* ─────────────────────────────────────────────────────────────
+   .kj-pagination — component-layer tokens + structural CSS
+   The directive family reflects state via `data-current` /
+   `data-disabled` / `aria-current` / `aria-disabled` /
+   `data-pagination-action` — every selector here keys off those.
+   ──────────────────────────────────────────────────────────── */
+
+@layer kj.component {
+  .kj-pagination {
+    /* component knobs — themes/users can override any of these */
+    --kj-pagination-gap:                  var(--kj-space-xs);
+    --kj-pagination-item-size:            2.75rem; /* 44px — WCAG 2.5.5 */
+    --kj-pagination-item-radius:          var(--kj-radius-field);
+    --kj-pagination-item-bg:              transparent;
+    --kj-pagination-item-bg-hover:        var(--kj-bg-surface);
+    --kj-pagination-item-bg-current:      var(--kj-bg-primary);
+    --kj-pagination-item-fg:              var(--kj-fg-default);
+    --kj-pagination-item-fg-current:      var(--kj-fg-on-primary);
+    --kj-pagination-item-border-color:    var(--kj-border-default);
+    --kj-pagination-item-border-width:    var(--kj-border);
+    --kj-pagination-item-font:            var(--kj-font-sans);
+    --kj-pagination-item-font-size:       var(--kj-text-sm);
+    --kj-pagination-ellipsis-color:       var(--kj-fg-default);
+    --kj-pagination-info-color:           var(--kj-fg-default);
+
+    display: inline-flex;
+    align-items: center;
+    flex-wrap: wrap;
+    gap: var(--kj-pagination-gap);
+    color: var(--kj-fg-default);
+  }
+
+  /* Numeric items + boundary controls share the same visual chrome —
+     the `.kj-pagination-action` class names map to Previous / Next /
+     First / Last so consumers can target them individually if needed. */
+  .kj-pagination-item,
+  .kj-pagination-action {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    min-width: var(--kj-pagination-item-size);
+    min-height: var(--kj-pagination-item-size);
+    padding: 0 var(--kj-space-sm);
+    background: var(--kj-pagination-item-bg);
+    color: var(--kj-pagination-item-fg);
+    border: var(--kj-pagination-item-border-width) solid var(--kj-pagination-item-border-color);
+    border-radius: var(--kj-pagination-item-radius);
+    font: var(--kj-pagination-item-font-size) / 1.2 var(--kj-pagination-item-font);
+    cursor: pointer;
+    user-select: none;
+    transition: var(--kj-transition);
+  }
+
+  .kj-pagination-item:hover,
+  .kj-pagination-action:hover {
+    background: var(--kj-pagination-item-bg-hover);
+  }
+
+  .kj-pagination-item:focus-visible,
+  .kj-pagination-action:focus-visible {
+    outline: 2px solid var(--kj-fg-primary);
+    outline-offset: 2px;
+  }
+
+  /* Active page — keep the touch target intact (don't shrink the active
+     state). The directive reflects `aria-current="page"` and
+     `data-current="true"`; we key off `aria-current` for AT correctness. */
+  .kj-pagination-item[aria-current='page'] {
+    background: var(--kj-pagination-item-bg-current);
+    color: var(--kj-pagination-item-fg-current);
+    border-color: var(--kj-pagination-item-bg-current);
+    cursor: default;
+  }
+  .kj-pagination-item[aria-current='page']:hover {
+    background: var(--kj-pagination-item-bg-current);
+  }
+
+  /* Disabled — `aria-disabled="true"` rather than the native attribute,
+     so the control stays focusable (kouji's WCAG 2.1 AAA stance). */
+  .kj-pagination-item[aria-disabled='true'],
+  .kj-pagination-action[aria-disabled='true'] {
+    opacity: 0.45;
+    cursor: not-allowed;
+  }
+  .kj-pagination-item[aria-disabled='true']:hover,
+  .kj-pagination-action[aria-disabled='true']:hover {
+    background: var(--kj-pagination-item-bg);
+  }
+
+  /* Ellipsis is non-interactive — no hover, no border, no touch target. */
+  .kj-pagination-ellipsis {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    min-width: var(--kj-pagination-item-size);
+    min-height: var(--kj-pagination-item-size);
+    color: var(--kj-pagination-ellipsis-color);
+    user-select: none;
+  }
+
+  /* Info span — AT-readable, visible. */
+  .kj-pagination-info {
+    display: inline-flex;
+    align-items: center;
+    padding: 0 var(--kj-space-sm);
+    color: var(--kj-pagination-info-color);
+    font: var(--kj-pagination-item-font-size) / 1.2 var(--kj-pagination-item-font);
+  }
+
+  /* ── Variants ──────────────────────────────────────────────── */
+  /* The root cascades `data-variant` to children via the context; each
+     child's KjVariant host directive reflects its own. We target the
+     children directly so the wrapper variant flows through. */
+
+  .kj-pagination-item[data-variant='outline'],
+  .kj-pagination-action[data-variant='outline'] {
+    --kj-pagination-item-bg: transparent;
+    --kj-pagination-item-border-color: var(--kj-border-default);
+  }
+
+  .kj-pagination-item[data-variant='ghost'],
+  .kj-pagination-action[data-variant='ghost'] {
+    --kj-pagination-item-bg: transparent;
+    --kj-pagination-item-border-color: transparent;
+  }
+
+  /* ── Sizes ─────────────────────────────────────────────────── */
+  .kj-pagination-item[data-size='xs'],
+  .kj-pagination-action[data-size='xs'] {
+    min-width: 1.5rem;
+    min-height: 1.5rem;
+    --kj-pagination-item-font-size: 0.75rem;
+  }
+  .kj-pagination-item[data-size='sm'],
+  .kj-pagination-action[data-size='sm'] {
+    min-width: 2rem;
+    min-height: 2rem;
+    --kj-pagination-item-font-size: 0.8125rem;
+  }
+  .kj-pagination-item[data-size='lg'],
+  .kj-pagination-action[data-size='lg'] {
+    min-width: 3rem;
+    min-height: 3rem;
+    --kj-pagination-item-font-size: 1rem;
+  }
+}

package/src/pagination/pagination.playground.ts

@@ -0,0 +1,107 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import {
+  KjPaginationComponent,
+  KjPaginationItemComponent,
+  KjPaginationPreviousComponent,
+  KjPaginationNextComponent,
+  KjPaginationFirstComponent,
+  KjPaginationLastComponent,
+  KjPaginationEllipsisComponent,
+} from './pagination';
+import type { PlaygroundFile } from '@kouji-ui/components/playground-types';
+
+/**
+ * Playground state — module-scope signals. Knobs let the user re-size the
+ * dataset, scrub the current page, and tune the ellipsis windowing controls.
+ */
+const page = signal<number>(3);
+const totalPages = signal<number>(10);
+const siblingCount = signal<number>(1);
+const boundaryCount = signal<number>(1);
+const variant = signal<'default' | 'outline' | 'ghost'>('default');
+const size = signal<'sm' | 'md' | 'lg'>('md');
+
+@Component({
+  selector: 'kj-pagination-playground',
+  standalone: true,
+  imports: [
+    KjPaginationComponent,
+    KjPaginationItemComponent,
+    KjPaginationPreviousComponent,
+    KjPaginationNextComponent,
+    KjPaginationFirstComponent,
+    KjPaginationLastComponent,
+    KjPaginationEllipsisComponent,
+  ],
+  template: `
+    <kj-pagination
+      [(kjPage)]="page"
+      [kjTotalPages]="totalPages()"
+      [kjSiblingCount]="siblingCount()"
+      [kjBoundaryCount]="boundaryCount()"
+      [kjVariant]="variant()"
+      [kjSize]="size()"
+      #p="kjPagination"
+    >
+      <kj-pagination-first>«</kj-pagination-first>
+      <kj-pagination-previous>‹</kj-pagination-previous>
+      @for (token of p.pages(); track token) {
+        @if (token === 'ellipsis-left' || token === 'ellipsis-right') {
+          <kj-pagination-ellipsis>…</kj-pagination-ellipsis>
+        } @else {
+          <kj-pagination-item [kjPage]="token">{{ token }}</kj-pagination-item>
+        }
+      }
+      <kj-pagination-next>›</kj-pagination-next>
+      <kj-pagination-last>»</kj-pagination-last>
+    </kj-pagination>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjPaginationPlaygroundDemo {
+  protected readonly page = page;
+  protected readonly totalPages = totalPages;
+  protected readonly siblingCount = siblingCount;
+  protected readonly boundaryCount = boundaryCount;
+  protected readonly variant = variant;
+  protected readonly size = size;
+}
+
+export const PLAYGROUND: PlaygroundFile = {
+  component: KjPaginationPlaygroundDemo,
+  state: {
+    page: page as unknown as ReturnType<typeof signal>,
+    totalPages: totalPages as unknown as ReturnType<typeof signal>,
+    siblingCount: siblingCount as unknown as ReturnType<typeof signal>,
+    boundaryCount: boundaryCount as unknown as ReturnType<typeof signal>,
+    variant: variant as unknown as ReturnType<typeof signal>,
+    size: size as unknown as ReturnType<typeof signal>,
+  },
+  controls: [
+    { kind: 'number', name: 'page', label: 'page', min: 1 },
+    { kind: 'number', name: 'totalPages', label: 'total pages', min: 1, max: 100 },
+    { kind: 'number', name: 'siblingCount', label: 'sibling count', min: 0, max: 5 },
+    { kind: 'number', name: 'boundaryCount', label: 'boundary count', min: 0, max: 5 },
+    { kind: 'chips', name: 'variant', label: 'variant', options: ['default', 'outline', 'ghost'] },
+    { kind: 'chips', name: 'size', label: 'size', options: ['sm', 'md', 'lg'] },
+  ],
+  snippet: (values) => {
+    const s = values as {
+      page: number;
+      totalPages: number;
+      siblingCount: number;
+      boundaryCount: number;
+      variant: string;
+      size: string;
+    };
+    const attrs: string[] = [
+      `[(kjPage)]="page"`,
+      `[kjTotalPages]="${s.totalPages}"`,
+      `[kjSiblingCount]="${s.siblingCount}"`,
+      `[kjBoundaryCount]="${s.boundaryCount}"`,
+      `kjVariant="${s.variant}"`,
+      `kjSize="${s.size}"`,
+    ];
+    return `<kj-pagination\n  ${attrs.join('\n  ')}\n  #p="kjPagination"\n>\n  <kj-pagination-first>«</kj-pagination-first>\n  <kj-pagination-previous>‹</kj-pagination-previous>\n  @for (token of p.pages(); track token) {\n    @if (token === 'ellipsis-left' || token === 'ellipsis-right') {\n      <kj-pagination-ellipsis>…</kj-pagination-ellipsis>\n    } @else {\n      <kj-pagination-item [kjPage]="token">{{ token }}</kj-pagination-item>\n    }\n  }\n  <kj-pagination-next>›</kj-pagination-next>\n  <kj-pagination-last>»</kj-pagination-last>\n</kj-pagination>`;
+  },
+};

package/src/pagination/pagination.spec.ts

@@ -0,0 +1,202 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { describe, expect, test, beforeEach } from 'vitest';
+import {
+  KjPaginationComponent,
+  KjPaginationItemComponent,
+  KjPaginationPreviousComponent,
+  KjPaginationNextComponent,
+  KjPaginationFirstComponent,
+  KjPaginationLastComponent,
+  KjPaginationEllipsisComponent,
+  KjPaginationInfoComponent,
+  KjPaginationDefaultComponent,
+} from './pagination';
+
+const imports = [
+  KjPaginationComponent,
+  KjPaginationItemComponent,
+  KjPaginationPreviousComponent,
+  KjPaginationNextComponent,
+  KjPaginationFirstComponent,
+  KjPaginationLastComponent,
+  KjPaginationEllipsisComponent,
+  KjPaginationInfoComponent,
+  KjPaginationDefaultComponent,
+];
+
+@Component({
+  standalone: true,
+  imports,
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-pagination [(kjPage)]="page" [kjTotalPages]="totalPages()" #p="kjPagination">
+      <kj-pagination-first>«</kj-pagination-first>
+      <kj-pagination-previous>‹</kj-pagination-previous>
+      @for (token of p.pages(); track token) {
+        @if (token === 'ellipsis-left' || token === 'ellipsis-right') {
+          <kj-pagination-ellipsis>…</kj-pagination-ellipsis>
+        } @else {
+          <kj-pagination-item [kjPage]="token">{{ token }}</kj-pagination-item>
+        }
+      }
+      <kj-pagination-next>›</kj-pagination-next>
+      <kj-pagination-last>»</kj-pagination-last>
+      <kj-pagination-info />
+    </kj-pagination>
+  `,
+})
+class HostComponent {
+  readonly page = signal(1);
+  readonly totalPages = signal(10);
+}
+
+@Component({
+  standalone: true,
+  imports,
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: ` <kj-pagination-default [(kjPage)]="page" [kjTotalPages]="totalPages()" /> `,
+})
+class DefaultHost {
+  readonly page = signal(1);
+  readonly totalPages = signal(10);
+}
+
+describe('KjPaginationComponent (wrapper)', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({ imports: [HostComponent, DefaultHost] });
+  });
+
+  test('renders the projected children — root nav, item buttons, boundary controls, info', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const root: HTMLElement = fixture.nativeElement;
+
+    const nav = root.querySelector('kj-pagination');
+    expect(nav).not.toBeNull();
+    expect(nav!.getAttribute('aria-label')).toBe('Pagination');
+
+    // Numeric items render as <button kjPaginationItem class="kj-pagination-item">.
+    const items = root.querySelectorAll<HTMLButtonElement>('button.kj-pagination-item');
+    expect(items.length).toBeGreaterThan(0);
+
+    // Boundary controls — one per role.
+    expect(
+      root.querySelector('button.kj-pagination-action--first[data-pagination-action="first"]'),
+    ).not.toBeNull();
+    expect(
+      root.querySelector(
+        'button.kj-pagination-action--previous[data-pagination-action="previous"]',
+      ),
+    ).not.toBeNull();
+    expect(
+      root.querySelector('button.kj-pagination-action--next[data-pagination-action="next"]'),
+    ).not.toBeNull();
+    expect(
+      root.querySelector('button.kj-pagination-action--last[data-pagination-action="last"]'),
+    ).not.toBeNull();
+
+    // Info span attribute set by directive.
+    const info = root.querySelector('kj-pagination-info');
+    expect(info).not.toBeNull();
+    expect(info!.hasAttribute('data-pagination-info')).toBe(true);
+  });
+
+  test('aliased inputs forward to the host directive — kjPage, kjTotalPages reflected as data-*', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const root: HTMLElement = fixture.nativeElement;
+    const nav = root.querySelector('kj-pagination')!;
+
+    expect(nav.getAttribute('data-page')).toBe('1');
+    expect(nav.getAttribute('data-total-pages')).toBe('10');
+
+    fixture.componentInstance.page.set(4);
+    fixture.detectChanges();
+
+    expect(nav.getAttribute('data-page')).toBe('4');
+  });
+
+  test('current page button reflects aria-current="page"', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.page.set(3);
+    fixture.detectChanges();
+
+    const root: HTMLElement = fixture.nativeElement;
+    const items = root.querySelectorAll<HTMLButtonElement>('button.kj-pagination-item');
+    const current = Array.from(items).find((b) => b.getAttribute('aria-current') === 'page');
+    expect(current).toBeDefined();
+    expect(current!.textContent?.trim()).toBe('3');
+
+    // Only one current button at a time.
+    const allCurrent = Array.from(items).filter((b) => b.getAttribute('aria-current') === 'page');
+    expect(allCurrent.length).toBe(1);
+  });
+
+  test('boundaries: First / Previous disabled on page 1; Next / Last disabled on last page', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+
+    const root: HTMLElement = fixture.nativeElement;
+    const first = root.querySelector('button.kj-pagination-action--first')!;
+    const prev = root.querySelector('button.kj-pagination-action--previous')!;
+    const next = root.querySelector('button.kj-pagination-action--next')!;
+    const last = root.querySelector('button.kj-pagination-action--last')!;
+
+    // On page 1.
+    expect(first.getAttribute('aria-disabled')).toBe('true');
+    expect(prev.getAttribute('aria-disabled')).toBe('true');
+    expect(next.getAttribute('aria-disabled')).toBeNull();
+    expect(last.getAttribute('aria-disabled')).toBeNull();
+
+    // Jump to the last page.
+    fixture.componentInstance.page.set(10);
+    fixture.detectChanges();
+
+    expect(first.getAttribute('aria-disabled')).toBeNull();
+    expect(prev.getAttribute('aria-disabled')).toBeNull();
+    expect(next.getAttribute('aria-disabled')).toBe('true');
+    expect(last.getAttribute('aria-disabled')).toBe('true');
+  });
+
+  test('clicking a numeric item updates the bound page model', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const root: HTMLElement = fixture.nativeElement;
+
+    const items = root.querySelectorAll<HTMLButtonElement>('button.kj-pagination-item');
+    // Click "2".
+    const two = Array.from(items).find((b) => b.textContent?.trim() === '2');
+    expect(two).toBeDefined();
+    two!.click();
+    fixture.detectChanges();
+
+    expect(fixture.componentInstance.page()).toBe(2);
+  });
+
+  test('clicking a disabled boundary control is a no-op', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const root: HTMLElement = fixture.nativeElement;
+
+    const prev = root.querySelector<HTMLButtonElement>('button.kj-pagination-action--previous')!;
+    expect(prev.getAttribute('aria-disabled')).toBe('true');
+    prev.click();
+    fixture.detectChanges();
+
+    expect(fixture.componentInstance.page()).toBe(1);
+  });
+
+  test('kj-pagination-default renders the canonical layout from kjPage + kjTotalPages alone', () => {
+    const fixture = TestBed.createComponent(DefaultHost);
+    fixture.detectChanges();
+    const root: HTMLElement = fixture.nativeElement;
+
+    // Auto-renders First, Previous, page items, Next, Last.
+    expect(root.querySelector('button.kj-pagination-action--first')).not.toBeNull();
+    expect(root.querySelector('button.kj-pagination-action--previous')).not.toBeNull();
+    expect(root.querySelector('button.kj-pagination-action--next')).not.toBeNull();
+    expect(root.querySelector('button.kj-pagination-action--last')).not.toBeNull();
+    expect(root.querySelectorAll('button.kj-pagination-item').length).toBeGreaterThan(0);
+  });
+});