@kouji-ui/core 0.1.1 → 0.1.2

package/src/pagination/pagination-previous.ts

@@ -1,90 +0,0 @@
-import {
-  Directive,
-  ElementRef,
-  afterNextRender,
-  computed,
-  inject,
-} from '@angular/core';
-import { KjFocusRing } from '../primitives';
-import { KjVariant, KjSize } from '../presets';
-import { KJ_PAGINATION } from './pagination.context';
-import { KJ_PAGINATION_CONFIG } from './config';
-
-/**
- * Boundary control that retreats one page. Disabled (via `aria-disabled`,
- * not the native `disabled` attribute) when the parent is on the first
- * page or the dataset is empty. Stays in the focus ring even when
- * disabled (`tabindex="0"`) — matches Button's `disabledInteractive`
- * stance so AT users discover the control and learn it is currently
- * inactive (kouji's WCAG 2.1 AAA stance).
- *
- * @example
- * ```html
- * <button kjButton kjPaginationPrevious>Previous</button>
- * ```
- *
- * @doc-category Core/Navigation
- * @doc
- * @doc-name pagination
- */
-@Directive({
-  selector: '[kjPaginationPrevious]',
-  standalone: true,
-  hostDirectives: [
-    { directive: KjVariant, inputs: ['kjVariant'] },
-    { directive: KjSize, inputs: ['kjSize'] },
-    KjFocusRing,
-  ],
-  host: {
-    '[attr.aria-label]': 'config.previousLabel',
-    '[attr.aria-disabled]': 'isDisabled() ? "true" : null',
-    '[attr.data-disabled]': 'isDisabled() ? "" : null',
-    '[attr.tabindex]': '"0"',
-    '[attr.data-pagination-action]': '"previous"',
-    '(click)': 'onClick($event)',
-  },
-})
-export class KjPaginationPrevious {
-  /** @internal */
-  readonly pagination = inject(KJ_PAGINATION);
-  /** @internal */
-  readonly config = inject(KJ_PAGINATION_CONFIG);
-  private readonly el = inject<ElementRef<HTMLElement>>(ElementRef);
-
-  /** True when the parent is on page 1 or the dataset is empty. */
-  readonly isDisabled = computed(() => this.pagination.isFirstPage());
-
-  constructor() {
-    // Capture-phase listeners fire before any consumer template-bound
-    // (click) / (keydown) handler and before native button activation,
-    // so the suppression actually prevents downstream navigation.
-    afterNextRender(() => {
-      const node = this.el.nativeElement;
-      const block = (event: Event) => {
-        if (this.isDisabled()) {
-          event.preventDefault();
-          event.stopImmediatePropagation();
-        }
-      };
-      const blockKey = (event: KeyboardEvent) => {
-        if (!this.isDisabled()) return;
-        if (event.key === 'Enter' || event.key === ' ' || event.key === 'Spacebar') {
-          event.preventDefault();
-          event.stopImmediatePropagation();
-        }
-      };
-      node.addEventListener('click', block, { capture: true });
-      node.addEventListener('keydown', blockKey, { capture: true });
-    });
-  }
-
-  /** @internal */
-  onClick(event: Event): void {
-    if (this.isDisabled()) {
-      event.preventDefault();
-      event.stopImmediatePropagation();
-      return;
-    }
-    this.pagination.goToPrevious();
-  }
-}

package/src/pagination/pagination.context.ts

@@ -1,52 +0,0 @@
-import { InjectionToken, Signal } from '@angular/core';
-
-/**
- * A single token in the windowed page list produced by the page-token
- * algorithm. Numeric tokens render as page buttons (`KjPaginationItem`);
- * the two `'ellipsis-*'` variants are rendered as a `KjPaginationEllipsis`
- * gap indicator. The two ellipsis variants are kept distinct so Angular's
- * `@for (… ; track token)` can build stable, collision-free tracks.
- */
-export type KjPageToken = number | 'ellipsis-left' | 'ellipsis-right';
-
-/**
- * Context exposed by `KjPagination` to its child directives
- * (`KjPaginationItem`, `KjPaginationPrevious`, `KjPaginationNext`,
- * `KjPaginationFirst`, `KjPaginationLast`, `KjPaginationEllipsis`,
- * `KjPaginationInfo`). Holds the page state, the algorithm output, the
- * boundary computeds, and the imperative navigation methods.
- *
- * Children are stateless reflectors of the root's state — every
- * derivation lives here so a single source of truth drives ARIA wiring,
- * `data-current` / `data-disabled` reflection, and the live-region
- * announcement.
- */
-export interface KjPaginationContext {
-  /** Current page (1-indexed). */
-  readonly page: Signal<number>;
-  /** Total number of pages. May be `0` (empty dataset). */
-  readonly totalPages: Signal<number>;
-  /** Output of the windowed page-token algorithm. */
-  readonly pages: Signal<readonly KjPageToken[]>;
-  /** True when the current page is `1` or the dataset is empty. */
-  readonly isFirstPage: Signal<boolean>;
-  /** True when the current page is `totalPages` or the dataset is empty. */
-  readonly isLastPage: Signal<boolean>;
-  /** Cascaded variant for children that did not set their own. */
-  readonly variant: Signal<string>;
-  /** Cascaded size for children that did not set their own. */
-  readonly size: Signal<string>;
-  /** Jump to a specific page (1-indexed); clamps to `[1, totalPages]`. */
-  goToPage(page: number): void;
-  /** Jump to page 1. No-op when already on page 1 / empty dataset. */
-  goToFirst(): void;
-  /** Jump to the last page. No-op when already there / empty dataset. */
-  goToLast(): void;
-  /** Advance one page. No-op when on the last page. */
-  goToNext(): void;
-  /** Retreat one page. No-op when on the first page. */
-  goToPrevious(): void;
-}
-
-/** Injection token for the root `KjPagination` directive context. */
-export const KJ_PAGINATION = new InjectionToken<KjPaginationContext>('KjPagination');

package/src/pagination/pagination.spec.ts

@@ -1,388 +0,0 @@
-import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
-import { fireEvent, render } from '@testing-library/angular';
-import { describe, expect, it, vi } from 'vitest';
-import { KjPagination } from './pagination';
-import { KjPaginationItem } from './pagination-item';
-import { KjPaginationPrevious } from './pagination-previous';
-import { KjPaginationNext } from './pagination-next';
-import { KjPaginationFirst } from './pagination-first';
-import { KjPaginationLast } from './pagination-last';
-import { KjPaginationEllipsis } from './pagination-ellipsis';
-import { KjPaginationInfo } from './pagination-info';
-import { computePageTokens } from './page-tokens';
-
-const imports = [
-  KjPagination,
-  KjPaginationItem,
-  KjPaginationPrevious,
-  KjPaginationNext,
-  KjPaginationFirst,
-  KjPaginationLast,
-  KjPaginationEllipsis,
-  KjPaginationInfo,
-];
-
-@Component({
-  standalone: true,
-  imports,
-  changeDetection: ChangeDetectionStrategy.Eager,
-  template: `
-    <nav kjPagination [(kjPage)]="page" [kjTotalPages]="totalPages()" #p="kjPagination">
-      <button kjPaginationFirst>«</button>
-      <button kjPaginationPrevious>‹</button>
-      @for (token of p.pages(); track token) {
-        @if (token === 'ellipsis-left' || token === 'ellipsis-right') {
-          <span kjPaginationEllipsis>…</span>
-        } @else {
-          <button kjPaginationItem [kjPage]="token">{{ token }}</button>
-        }
-      }
-      <button kjPaginationNext>›</button>
-      <button kjPaginationLast>»</button>
-      <span kjPaginationInfo></span>
-    </nav>
-  `,
-})
-class PaginationHost {
-  readonly page = signal(1);
-  readonly totalPages = signal(10);
-}
-
-@Component({
-  standalone: true,
-  imports,
-  changeDetection: ChangeDetectionStrategy.Eager,
-  template: `
-    <nav kjPagination [(kjPage)]="page" [kjTotalPages]="totalPages()" #p="kjPagination">
-      @for (token of p.pages(); track token) {
-        @if (token !== 'ellipsis-left' && token !== 'ellipsis-right') {
-          <button kjPaginationItem [kjPage]="token">{{ token }}</button>
-        }
-      }
-    </nav>
-  `,
-})
-class SmallPaginationHost {
-  readonly page = signal(1);
-  readonly totalPages = signal(3);
-}
-
-describe('computePageTokens (algorithm)', () => {
-  describe('edge cases', () => {
-    it('returns [] when total <= 0', () => {
-      expect(computePageTokens(1, 0, 1, 1)).toEqual([]);
-      expect(computePageTokens(1, -5, 1, 1)).toEqual([]);
-    });
-
-    it('renders all pages with no ellipses when total fits in the window', () => {
-      // boundary*2 + siblings*2 + 3 = 1*2 + 1*2 + 3 = 7 — total <= 7 fits.
-      expect(computePageTokens(1, 1, 1, 1)).toEqual([1]);
-      expect(computePageTokens(2, 5, 1, 1)).toEqual([1, 2, 3, 4, 5]);
-      expect(computePageTokens(4, 7, 1, 1)).toEqual([1, 2, 3, 4, 5, 6, 7]);
-    });
-  });
-
-  describe('large datasets — current near start', () => {
-    it('total=10, current=1: only right ellipsis (sibling window collapses to filler)', () => {
-      // With current=1 and siblings=1, the sibling window would span [0,2]
-      // but is clamped at the boundary anchor (page 1) — only `2` is added
-      // by the !showLeftEllipsis filler branch. The right ellipsis bridges
-      // to the right boundary.
-      expect(computePageTokens(1, 10, 1, 1)).toEqual([1, 2, 'ellipsis-right', 10]);
-    });
-
-    it('total=10, current=2: only right ellipsis', () => {
-      expect(computePageTokens(2, 10, 1, 1)).toEqual([1, 2, 3, 'ellipsis-right', 10]);
-    });
-
-    it('total=10, current=3: only right ellipsis', () => {
-      expect(computePageTokens(3, 10, 1, 1)).toEqual([1, 2, 3, 4, 'ellipsis-right', 10]);
-    });
-  });
-
-  describe('large datasets — current near end', () => {
-    it('total=10, current=10: only left ellipsis (sibling window clamps at boundary)', () => {
-      // Mirror of the current=1 case — the sibling window is clamped at
-      // the right boundary anchor, leaving the !showRightEllipsis filler
-      // branch to push `9` and the left ellipsis to bridge.
-      expect(computePageTokens(10, 10, 1, 1)).toEqual([1, 'ellipsis-left', 9, 10]);
-    });
-
-    it('total=10, current=9: only left ellipsis', () => {
-      expect(computePageTokens(9, 10, 1, 1)).toEqual([1, 'ellipsis-left', 8, 9, 10]);
-    });
-
-    it('total=10, current=8: only left ellipsis', () => {
-      expect(computePageTokens(8, 10, 1, 1)).toEqual([1, 'ellipsis-left', 7, 8, 9, 10]);
-    });
-  });
-
-  describe('large datasets — current in the middle', () => {
-    it('total=10, current=5: both ellipses', () => {
-      expect(computePageTokens(5, 10, 1, 1)).toEqual([
-        1,
-        'ellipsis-left',
-        4,
-        5,
-        6,
-        'ellipsis-right',
-        10,
-      ]);
-    });
-
-    it('total=20, current=10, siblings=2, boundary=2: both ellipses', () => {
-      expect(computePageTokens(10, 20, 2, 2)).toEqual([
-        1,
-        2,
-        'ellipsis-left',
-        8,
-        9,
-        10,
-        11,
-        12,
-        'ellipsis-right',
-        19,
-        20,
-      ]);
-    });
-  });
-
-  describe('off-by-one sweep across totals 7–11', () => {
-    it.each([7, 8, 9, 10, 11])(
-      'total=%i: every current 1..total produces a stable, well-formed token list',
-      (total) => {
-        for (let current = 1; current <= total; current++) {
-          const tokens = computePageTokens(current, total, 1, 1);
-          // Always starts with 1 when boundary>=1.
-          expect(tokens[0]).toBe(1);
-          // Always ends with total when boundary>=1.
-          expect(tokens[tokens.length - 1]).toBe(total);
-          // The current page number always appears as a numeric token.
-          expect(tokens.includes(current)).toBe(true);
-          // Numeric tokens are strictly ascending.
-          const numerics = tokens.filter((t): t is number => typeof t === 'number');
-          for (let i = 1; i < numerics.length; i++) {
-            expect(numerics[i]).toBeGreaterThan(numerics[i - 1]);
-          }
-        }
-      },
-    );
-  });
-
-  describe('degenerate inputs', () => {
-    it('siblings=0, boundary=0, total=10, current=5: collapses to current only', () => {
-      // No boundary anchors, no sibling neighbors — just the current with
-      // ellipses bridging on each side.
-      const tokens = computePageTokens(5, 10, 0, 0);
-      expect(tokens).toContain(5);
-      // No `1` or `10` because boundary=0.
-      expect(tokens.includes(1)).toBe(false);
-      expect(tokens.includes(10)).toBe(false);
-    });
-  });
-});
-
-describe('KjPagination — directive integration', () => {
-  describe('host wiring', () => {
-    it('hosts <nav> with aria-label="Pagination" by default', async () => {
-      const { container } = await render(PaginationHost);
-      const nav = container.querySelector('[kjPagination]')!;
-      expect(nav.tagName).toBe('NAV');
-      expect(nav).toHaveAttribute('aria-label', 'Pagination');
-    });
-
-    it('reflects current page and total via data attributes', async () => {
-      const { container } = await render(PaginationHost);
-      const nav = container.querySelector('[kjPagination]')!;
-      expect(nav).toHaveAttribute('data-page', '1');
-      expect(nav).toHaveAttribute('data-total-pages', '10');
-    });
-  });
-
-  describe('aria-current on the active item', () => {
-    it('marks the current page item with aria-current="page" and data-current="true"', async () => {
-      const { container, fixture } = await render(PaginationHost);
-      // Initial page = 1.
-      const items = container.querySelectorAll<HTMLElement>('[kjPaginationItem]');
-      const first = Array.from(items).find((b) => b.textContent?.trim() === '1')!;
-      expect(first).toHaveAttribute('aria-current', 'page');
-      expect(first).toHaveAttribute('data-current', 'true');
-
-      // Move to page 3. With totalPages=10, siblings=1, boundary=1, current=3
-      // the window is [1, 2, 3, 4, 'ellipsis-right', 10] — page 3 is rendered.
-      (fixture.componentInstance as PaginationHost).page.set(3);
-      fixture.detectChanges();
-      const updated = container.querySelectorAll<HTMLElement>('[kjPaginationItem]');
-      const three = Array.from(updated).find((b) => b.textContent?.trim() === '3')!;
-      expect(three).toHaveAttribute('aria-current', 'page');
-      expect(three).toHaveAttribute('data-current', 'true');
-      // The previously-current item is no longer aria-current.
-      const one = Array.from(updated).find((b) => b.textContent?.trim() === '1')!;
-      expect(one).not.toHaveAttribute('aria-current');
-      expect(one).toHaveAttribute('data-current', 'false');
-    });
-
-    it('stamps a configured aria-label on each item', async () => {
-      const { container } = await render(PaginationHost);
-      const items = container.querySelectorAll<HTMLElement>('[kjPaginationItem]');
-      const first = Array.from(items).find((b) => b.textContent?.trim() === '1')!;
-      expect(first).toHaveAttribute('aria-label', 'Page 1');
-    });
-  });
-
-  describe('boundary controls — disabled state at edges, focus-preserving', () => {
-    it('Previous and First are aria-disabled on page 1, but stay focusable (tabindex="0")', async () => {
-      const { container } = await render(PaginationHost);
-      const prev = container.querySelector<HTMLElement>('[kjPaginationPrevious]')!;
-      const first = container.querySelector<HTMLElement>('[kjPaginationFirst]')!;
-      expect(prev).toHaveAttribute('aria-disabled', 'true');
-      expect(prev).toHaveAttribute('tabindex', '0');
-      expect(first).toHaveAttribute('aria-disabled', 'true');
-      expect(first).toHaveAttribute('tabindex', '0');
-      // Native disabled is NOT used.
-      expect(prev).not.toHaveAttribute('disabled');
-      expect(first).not.toHaveAttribute('disabled');
-    });
-
-    it('Next and Last are aria-disabled on the last page, but stay focusable', async () => {
-      const { fixture, container } = await render(PaginationHost);
-      (fixture.componentInstance as PaginationHost).page.set(10);
-      fixture.detectChanges();
-      const next = container.querySelector<HTMLElement>('[kjPaginationNext]')!;
-      const last = container.querySelector<HTMLElement>('[kjPaginationLast]')!;
-      expect(next).toHaveAttribute('aria-disabled', 'true');
-      expect(next).toHaveAttribute('tabindex', '0');
-      expect(last).toHaveAttribute('aria-disabled', 'true');
-      expect(last).toHaveAttribute('tabindex', '0');
-    });
-
-    it('Previous click is suppressed at the first-page boundary (capture-phase)', async () => {
-      const { fixture, container } = await render(PaginationHost);
-      const host = fixture.componentInstance as PaginationHost;
-      const prev = container.querySelector<HTMLElement>('[kjPaginationPrevious]')!;
-      fireEvent.click(prev);
-      fixture.detectChanges();
-      expect(host.page()).toBe(1);
-    });
-
-    it('Next click is suppressed at the last-page boundary', async () => {
-      const { fixture, container } = await render(PaginationHost);
-      const host = fixture.componentInstance as PaginationHost;
-      host.page.set(10);
-      fixture.detectChanges();
-      const next = container.querySelector<HTMLElement>('[kjPaginationNext]')!;
-      fireEvent.click(next);
-      fixture.detectChanges();
-      expect(host.page()).toBe(10);
-    });
-
-    it('Next click advances the page when not at the boundary', async () => {
-      const { fixture, container } = await render(PaginationHost);
-      const host = fixture.componentInstance as PaginationHost;
-      host.page.set(3);
-      fixture.detectChanges();
-      const next = container.querySelector<HTMLElement>('[kjPaginationNext]')!;
-      fireEvent.click(next);
-      fixture.detectChanges();
-      expect(host.page()).toBe(4);
-    });
-
-    it('First / Last jump to the corresponding boundary', async () => {
-      const { fixture, container } = await render(PaginationHost);
-      const host = fixture.componentInstance as PaginationHost;
-      host.page.set(5);
-      fixture.detectChanges();
-      const last = container.querySelector<HTMLElement>('[kjPaginationLast]')!;
-      fireEvent.click(last);
-      fixture.detectChanges();
-      expect(host.page()).toBe(10);
-      const first = container.querySelector<HTMLElement>('[kjPaginationFirst]')!;
-      fireEvent.click(first);
-      fixture.detectChanges();
-      expect(host.page()).toBe(1);
-    });
-  });
-
-  describe('kjPage two-way model', () => {
-    it('clicking a page item updates the consumer signal', async () => {
-      const { fixture, container } = await render(PaginationHost);
-      const host = fixture.componentInstance as PaginationHost;
-      const items = container.querySelectorAll<HTMLElement>('[kjPaginationItem]');
-      const two = Array.from(items).find((b) => b.textContent?.trim() === '2')!;
-      fireEvent.click(two);
-      fixture.detectChanges();
-      expect(host.page()).toBe(2);
-    });
-
-    it('writing the consumer signal flows to the directive (current item updates)', async () => {
-      const { fixture, container } = await render(PaginationHost);
-      (fixture.componentInstance as PaginationHost).page.set(2);
-      fixture.detectChanges();
-      const items = container.querySelectorAll<HTMLElement>('[kjPaginationItem]');
-      const two = Array.from(items).find((b) => b.textContent?.trim() === '2')!;
-      expect(two).toHaveAttribute('aria-current', 'page');
-    });
-
-    it('out-of-range writes are clamped and a warning is issued', async () => {
-      const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
-      const { fixture } = await render(PaginationHost);
-      const host = fixture.componentInstance as PaginationHost;
-      host.page.set(99);
-      fixture.detectChanges();
-      // Two ticks — the clamp effect re-runs on the second.
-      await Promise.resolve();
-      fixture.detectChanges();
-      expect(host.page()).toBe(10);
-      expect(warn).toHaveBeenCalled();
-      warn.mockRestore();
-    });
-  });
-
-  describe('live-region announcement', () => {
-    it('appends a polite, atomic, visually-hidden live region inside the nav', async () => {
-      const { container } = await render(PaginationHost);
-      // afterNextRender is asynchronous in jsdom — wait a tick.
-      await new Promise<void>((resolve) => setTimeout(resolve, 0));
-      const nav = container.querySelector('[kjPagination]')!;
-      const region = nav.querySelector('[data-kj-pagination-live]') as HTMLElement | null;
-      expect(region).toBeTruthy();
-      expect(region!).toHaveAttribute('aria-live', 'polite');
-      expect(region!).toHaveAttribute('aria-atomic', 'true');
-      expect(region!.getAttribute('style') ?? '').toContain('clip:rect(0,0,0,0)');
-    });
-
-    it('writes the configured announcement template on page change', async () => {
-      const { fixture, container } = await render(PaginationHost);
-      const host = fixture.componentInstance as PaginationHost;
-      // Wait for the live region to attach.
-      await new Promise<void>((resolve) => setTimeout(resolve, 0));
-      host.page.set(4);
-      fixture.detectChanges();
-      // The directive uses queueMicrotask to clear-then-set; flush it.
-      await Promise.resolve();
-      await new Promise<void>((resolve) => queueMicrotask(() => resolve()));
-      const region = container.querySelector('[data-kj-pagination-live]') as HTMLElement;
-      expect(region.textContent).toBe('Page 4 of 10');
-    });
-  });
-
-  describe('small dataset', () => {
-    it('renders every page with no ellipses', async () => {
-      const { container } = await render(SmallPaginationHost);
-      const items = container.querySelectorAll<HTMLElement>('[kjPaginationItem]');
-      expect(items).toHaveLength(3);
-      const ellipses = container.querySelectorAll('[kjPaginationEllipsis]');
-      expect(ellipses).toHaveLength(0);
-    });
-  });
-
-  describe('info directive', () => {
-    it('renders the "Page N of M" string into an empty host', async () => {
-      const { container, fixture } = await render(PaginationHost);
-      await new Promise<void>((resolve) => setTimeout(resolve, 0));
-      fixture.detectChanges();
-      const info = container.querySelector('[kjPaginationInfo]')!;
-      expect(info.textContent).toContain('Page 1 of 10');
-    });
-  });
-});