@kouji-ui/core 0.0.3 → 0.1.1

package/src/pagination/config.ts

@@ -0,0 +1,82 @@
+import { InjectionToken, Provider } from '@angular/core';
+import type { KjLivePoliteness } from '../a11y/live-region';
+
+/**
+ * Configuration shape for the Pagination directive family. Exposes preset
+ * lists, default sliding-window sizes, and the (mostly i18n-facing) label
+ * functions and templates the directives reflect into the DOM.
+ */
+export interface KjPaginationConfig {
+  variants: string[];
+  sizes: string[];
+  defaults: {
+    variant: string;
+    size: string;
+    siblingCount: number;
+    boundaryCount: number;
+  };
+  /** `aria-label` on the root `<nav>` host element. */
+  navigationLabel: string;
+  /** `aria-label` on `KjPaginationPrevious` host. */
+  previousLabel: string;
+  /** `aria-label` on `KjPaginationNext` host. */
+  nextLabel: string;
+  /** `aria-label` on `KjPaginationFirst` host. */
+  firstLabel: string;
+  /** `aria-label` on `KjPaginationLast` host. */
+  lastLabel: string;
+  /** Visually-hidden text for the gap indicator's AT readout. */
+  ellipsisLabel: string;
+  /** Computes the per-item `aria-label` from `(page, totalPages)`. */
+  pageItemLabel: (page: number, totalPages: number) => string;
+  /** Renders the visible "Page N of M" text in `KjPaginationInfo`. */
+  infoTemplate: (page: number, totalPages: number) => string;
+  /** Live-region announcement template for page changes. */
+  pageChangeAnnouncement: (page: number, totalPages: number) => string;
+  /** ARIA politeness for the page-change live region. */
+  pageChangeAnnouncementPoliteness: KjLivePoliteness;
+}
+
+/**
+ * Default Pagination presets shipped by kouji-ui. Exported so consumers can
+ * spread when extending: `[...KJ_PAGINATION_DEFAULTS.variants, 'brand']`.
+ */
+export const KJ_PAGINATION_DEFAULTS: KjPaginationConfig = {
+  variants: ['default', 'outline', 'ghost'],
+  sizes: ['xs', 'sm', 'md', 'lg'],
+  defaults: { variant: 'default', size: 'md', siblingCount: 1, boundaryCount: 1 },
+  navigationLabel: 'Pagination',
+  previousLabel: 'Previous page',
+  nextLabel: 'Next page',
+  firstLabel: 'First page',
+  lastLabel: 'Last page',
+  ellipsisLabel: 'More pages',
+  pageItemLabel: (page) => `Page ${page}`,
+  infoTemplate: (page, totalPages) => `Page ${page} of ${totalPages}`,
+  pageChangeAnnouncement: (page, totalPages) => `Page ${page} of ${totalPages}`,
+  pageChangeAnnouncementPoliteness: 'polite',
+};
+
+/**
+ * DI token for the active Pagination presets. Default factory yields
+ * `KJ_PAGINATION_DEFAULTS`. Override via `provideKjPagination(…)` at the
+ * application or component scope.
+ */
+export const KJ_PAGINATION_CONFIG = new InjectionToken<KjPaginationConfig>(
+  'kj.pagination.config',
+  { factory: () => KJ_PAGINATION_DEFAULTS },
+);
+
+/**
+ * Configures the Pagination presets / labels for the enclosing injector.
+ * Shallow-merges over the defaults — pass only the fields you want to
+ * override.
+ */
+export function provideKjPagination(config: Partial<KjPaginationConfig>): Provider[] {
+  return [
+    {
+      provide: KJ_PAGINATION_CONFIG,
+      useValue: { ...KJ_PAGINATION_DEFAULTS, ...config },
+    },
+  ];
+}

package/src/pagination/index.ts

@@ -0,0 +1,19 @@
+export { KjPagination } from './pagination';
+export { KjPaginationItem } from './pagination-item';
+export { KjPaginationPrevious } from './pagination-previous';
+export { KjPaginationNext } from './pagination-next';
+export { KjPaginationFirst } from './pagination-first';
+export { KjPaginationLast } from './pagination-last';
+export { KjPaginationEllipsis } from './pagination-ellipsis';
+export { KjPaginationInfo } from './pagination-info';
+export {
+  KJ_PAGINATION,
+  type KjPaginationContext,
+  type KjPageToken,
+} from './pagination.context';
+export {
+  KJ_PAGINATION_CONFIG,
+  KJ_PAGINATION_DEFAULTS,
+  provideKjPagination,
+  type KjPaginationConfig,
+} from './config';

package/src/pagination/page-tokens.ts

@@ -0,0 +1,78 @@
+import type { KjPageToken } from './pagination.context';
+
+/**
+ * Computes the windowed list of page tokens for a paginator.
+ *
+ * Given a `current` page (1-indexed), a `total` count, the `siblings`
+ * count (pages adjacent to `current` on each side), and the `boundary`
+ * count (pages anchored at the start and end), produces the array of
+ * stable tokens that drives the rendered list — for example
+ * `[1, 'ellipsis-left', 4, 5, 6, 'ellipsis-right', 10]`.
+ *
+ * Edge cases handled:
+ *
+ * - `total <= 0` → returns `[]` (the empty-dataset state).
+ * - `boundary*2 + siblings*2 + 3 >= total` → no ellipses, every page
+ *   number rendered (small datasets).
+ * - `current` near `1` → only the right ellipsis appears; the left
+ *   sibling window meets the boundary directly.
+ * - `current` near `total` → mirror case; only the left ellipsis appears.
+ * - `current` in the middle → both ellipses appear.
+ * - Degenerate `siblings = 0` and/or `boundary = 0` are valid; the
+ *   sibling window collapses to `[current]` and the boundary anchors
+ *   disappear, with ellipses bridging whatever gap remains.
+ *
+ * @internal
+ */
+export function computePageTokens(
+  current: number,
+  total: number,
+  siblings: number,
+  boundary: number,
+): readonly KjPageToken[] {
+  if (total <= 0) return [];
+
+  const safeBoundary = Math.max(0, boundary);
+  const safeSiblings = Math.max(0, siblings);
+  const safeCurrent = Math.min(Math.max(1, current), total);
+
+  // Total pages renderable without ellipses:
+  // boundary + 1 (left ellipsis or filler) + (siblings*2 + 1) + 1 (right ellipsis) + boundary
+  const totalNumbers = safeBoundary * 2 + safeSiblings * 2 + 3;
+
+  if (totalNumbers >= total) {
+    // No ellipses needed — render every page.
+    return Array.from({ length: total }, (_, i) => i + 1);
+  }
+
+  const leftSiblingIndex = Math.max(safeCurrent - safeSiblings, safeBoundary + 2);
+  const rightSiblingIndex = Math.min(safeCurrent + safeSiblings, total - safeBoundary - 1);
+  const showLeftEllipsis = leftSiblingIndex > safeBoundary + 2;
+  const showRightEllipsis = rightSiblingIndex < total - safeBoundary - 1;
+
+  const tokens: KjPageToken[] = [];
+
+  // Left boundary anchor.
+  for (let i = 1; i <= safeBoundary; i++) tokens.push(i);
+
+  if (!showLeftEllipsis) {
+    // Sibling window meets the boundary — fill the gap with numbers.
+    for (let i = safeBoundary + 1; i < leftSiblingIndex; i++) tokens.push(i);
+  } else {
+    tokens.push('ellipsis-left');
+  }
+
+  // Sibling window.
+  for (let i = leftSiblingIndex; i <= rightSiblingIndex; i++) tokens.push(i);
+
+  if (!showRightEllipsis) {
+    for (let i = rightSiblingIndex + 1; i < total - safeBoundary + 1; i++) tokens.push(i);
+  } else {
+    tokens.push('ellipsis-right');
+  }
+
+  // Right boundary anchor.
+  for (let i = total - safeBoundary + 1; i <= total; i++) tokens.push(i);
+
+  return tokens;
+}

package/src/pagination/pagination-ellipsis.ts

@@ -0,0 +1,69 @@
+import {
+  Directive,
+  ElementRef,
+  afterNextRender,
+  inject,
+} from '@angular/core';
+import { KJ_PAGINATION_CONFIG } from './config';
+
+/** Inline style equivalent to `KjVisuallyHidden` — used for the AT label child span. */
+const KJ_VISUALLY_HIDDEN_STYLE =
+  'position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border-width:0';
+
+/**
+ * Gap indicator within a `KjPagination`. Apply to a `<span>`. The visible
+ * `…` glyph is decorative and marked `aria-hidden="true"`; the directive
+ * appends a visually-hidden child span carrying the configured ellipsis
+ * label (default `"More pages"`) so AT users hear a meaningful readout
+ * (WCAG 1.3.1 — the ellipsis carries information, so it must have a
+ * text equivalent).
+ *
+ * The host span itself is **not** `aria-hidden`; only the glyph wrapper
+ * inside it is. This way the visually-hidden label survives in the AT
+ * tree.
+ *
+ * @example
+ * ```html
+ * <span kjPaginationEllipsis>…</span>
+ * ```
+ *
+ * @doc-category Core/Navigation
+ * @doc
+ * @doc-name pagination
+ */
+@Directive({
+  selector: '[kjPaginationEllipsis]',
+  standalone: true,
+  host: {
+    '[attr.data-pagination-ellipsis]': '""',
+  },
+})
+export class KjPaginationEllipsis {
+  /** @internal */
+  readonly config = inject(KJ_PAGINATION_CONFIG);
+  private readonly el = inject<ElementRef<HTMLElement>>(ElementRef);
+
+  constructor() {
+    afterNextRender(() => {
+      if (typeof document === 'undefined') return;
+
+      const host = this.el.nativeElement;
+
+      // Wrap any existing visible glyph children in a `aria-hidden="true"`
+      // span so the glyph is hidden from AT but visible to sighted users.
+      const glyphWrapper = document.createElement('span');
+      glyphWrapper.setAttribute('aria-hidden', 'true');
+      // Move existing children into the glyph wrapper.
+      while (host.firstChild) {
+        glyphWrapper.appendChild(host.firstChild);
+      }
+      host.appendChild(glyphWrapper);
+
+      // Append the visually-hidden AT label.
+      const label = document.createElement('span');
+      label.setAttribute('style', KJ_VISUALLY_HIDDEN_STYLE);
+      label.textContent = this.config.ellipsisLabel;
+      host.appendChild(label);
+    });
+  }
+}

package/src/pagination/pagination-first.ts

@@ -0,0 +1,84 @@
+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 jumps to page 1. Disabled when the parent is
+ * already on the first page or the dataset is empty; remains focusable
+ * (`tabindex="0"`) so AT users can still discover the control.
+ *
+ * @example
+ * ```html
+ * <button kjButton kjPaginationFirst>«</button>
+ * ```
+ *
+ * @doc-category Core/Navigation
+ * @doc
+ * @doc-name pagination
+ */
+@Directive({
+  selector: '[kjPaginationFirst]',
+  standalone: true,
+  hostDirectives: [
+    { directive: KjVariant, inputs: ['kjVariant'] },
+    { directive: KjSize, inputs: ['kjSize'] },
+    KjFocusRing,
+  ],
+  host: {
+    '[attr.aria-label]': 'config.firstLabel',
+    '[attr.aria-disabled]': 'isDisabled() ? "true" : null',
+    '[attr.data-disabled]': 'isDisabled() ? "" : null',
+    '[attr.tabindex]': '"0"',
+    '[attr.data-pagination-action]': '"first"',
+    '(click)': 'onClick($event)',
+  },
+})
+export class KjPaginationFirst {
+  /** @internal */
+  readonly pagination = inject(KJ_PAGINATION);
+  /** @internal */
+  readonly config = inject(KJ_PAGINATION_CONFIG);
+  private readonly el = inject<ElementRef<HTMLElement>>(ElementRef);
+
+  /** True when on page 1 or the dataset is empty. */
+  readonly isDisabled = computed(() => this.pagination.isFirstPage());
+
+  constructor() {
+    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.goToFirst();
+  }
+}

package/src/pagination/pagination-info.ts

@@ -0,0 +1,70 @@
+import {
+  Directive,
+  ElementRef,
+  afterNextRender,
+  effect,
+  inject,
+  signal,
+} from '@angular/core';
+import { KJ_PAGINATION } from './pagination.context';
+import { KJ_PAGINATION_CONFIG } from './config';
+
+/**
+ * Renders the localised "Page N of M" status string. Apply to a
+ * `<span>` (or any inline element) inside a `KjPagination`. The directive
+ * sets `textContent` reactively on every page or total-pages change,
+ * **only when the host is empty** at attach time — when the consumer
+ * projects their own content (`<span kjPaginationInfo>Showing page {{ page }}</span>`),
+ * the directive yields and the consumer's binding wins.
+ *
+ * The info span is AT-readable (no `aria-hidden`); AT users hear
+ * "Pagination, Page 2 of 10" when they enter the navigation landmark.
+ *
+ * @example
+ * ```html
+ * <span kjPaginationInfo></span>
+ * ```
+ *
+ * @doc-category Core/Navigation
+ * @doc
+ * @doc-name pagination
+ */
+@Directive({
+  selector: '[kjPaginationInfo]',
+  standalone: true,
+  host: {
+    '[attr.data-pagination-info]': '""',
+  },
+})
+export class KjPaginationInfo {
+  /** @internal */
+  readonly pagination = inject(KJ_PAGINATION);
+  /** @internal */
+  readonly config = inject(KJ_PAGINATION_CONFIG);
+  private readonly el = inject<ElementRef<HTMLElement>>(ElementRef);
+
+  /** Latched true on first render; gates the `textContent` mutation. */
+  private readonly attached = signal(false);
+  /** Latched true if the consumer projected their own content. */
+  private consumerOwnsContent = false;
+
+  constructor() {
+    afterNextRender(() => {
+      const host = this.el.nativeElement;
+      this.consumerOwnsContent = host.childNodes.length > 0;
+      this.attached.set(true);
+    });
+
+    // Effect lives in injection context (constructor). It is reactive on
+    // `attached`, `page`, and `totalPages`; the body is a no-op until the
+    // host is attached and the consumer-content latch has been determined.
+    effect(() => {
+      if (!this.attached()) return;
+      if (this.consumerOwnsContent) return;
+      this.el.nativeElement.textContent = this.config.infoTemplate(
+        this.pagination.page(),
+        this.pagination.totalPages(),
+      );
+    });
+  }
+}

package/src/pagination/pagination-item.ts

@@ -0,0 +1,81 @@
+import { Directive, computed, inject, input } from '@angular/core';
+import { KjFocusRing } from '../primitives';
+import { KjVariant, KjSize } from '../presets';
+import { KJ_PAGINATION } from './pagination.context';
+import { KJ_PAGINATION_CONFIG } from './config';
+
+/**
+ * Per-page button within a `KjPagination`. Apply to `<button>` (in-page
+ * state) or `<a>` (routing variant). Reflects `aria-current="page"` /
+ * `data-current="true"` when the item's `kjPage` matches the parent's
+ * current page; the directive is tag-agnostic.
+ *
+ * Click on an enabled item calls the parent's `goToPage(kjPage())`. The
+ * directive does not call `preventDefault()` — when the host is an `<a>`
+ * with `routerLink`, the route change is the navigation and the model
+ * write either follows from the URL-driven binding or from this click.
+ *
+ * @example
+ * ```html
+ * <button kjButton kjPaginationItem [kjPage]="3">3</button>
+ * ```
+ *
+ * @doc-category Core/Navigation
+ * @doc
+ * @doc-name pagination
+ */
+@Directive({
+  selector: '[kjPaginationItem]',
+  standalone: true,
+  hostDirectives: [
+    { directive: KjVariant, inputs: ['kjVariant'] },
+    { directive: KjSize, inputs: ['kjSize'] },
+    KjFocusRing,
+  ],
+  host: {
+    '[attr.aria-current]': 'isCurrent() ? "page" : null',
+    '[attr.data-current]': 'isCurrent() ? "true" : "false"',
+    '[attr.aria-disabled]': 'kjDisabled() ? "true" : null',
+    '[attr.data-disabled]': 'kjDisabled() ? "" : null',
+    '[attr.aria-label]': 'ariaLabel()',
+    '(click)': 'onClick($event)',
+  },
+})
+export class KjPaginationItem {
+  /** @internal */
+  readonly pagination = inject(KJ_PAGINATION);
+  private readonly config = inject(KJ_PAGINATION_CONFIG);
+
+  /**
+   * Page number this item navigates to (1-indexed). Required — the
+   * directive cannot reflect `aria-current` or wire its click without
+   * knowing which page it represents.
+   */
+  readonly kjPage = input.required<number>();
+
+  /**
+   * Per-item disabled state. Composes the boundary-style disabled bundle
+   * (capture-phase click suppression) so consumer-driven "this page is
+   * loading and cannot be re-clicked" affordances work consistently with
+   * Previous / Next / First / Last.
+   */
+  readonly kjDisabled = input<boolean>(false);
+
+  /** Whether this item represents the currently active page. */
+  readonly isCurrent = computed(() => this.pagination.page() === this.kjPage());
+
+  /** Computed `aria-label` string. */
+  readonly ariaLabel = computed(() =>
+    this.config.pageItemLabel(this.kjPage(), this.pagination.totalPages()),
+  );
+
+  /** @internal */
+  onClick(event: Event): void {
+    if (this.kjDisabled()) {
+      event.preventDefault();
+      event.stopImmediatePropagation();
+      return;
+    }
+    this.pagination.goToPage(this.kjPage());
+  }
+}

package/src/pagination/pagination-last.ts

@@ -0,0 +1,85 @@
+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 jumps to the last page. Mirror of
+ * {@link KjPaginationFirst}: disabled when the parent is already on the
+ * last page or the dataset is empty; remains focusable (`tabindex="0"`)
+ * even when disabled.
+ *
+ * @example
+ * ```html
+ * <button kjButton kjPaginationLast>»</button>
+ * ```
+ *
+ * @doc-category Core/Navigation
+ * @doc
+ * @doc-name pagination
+ */
+@Directive({
+  selector: '[kjPaginationLast]',
+  standalone: true,
+  hostDirectives: [
+    { directive: KjVariant, inputs: ['kjVariant'] },
+    { directive: KjSize, inputs: ['kjSize'] },
+    KjFocusRing,
+  ],
+  host: {
+    '[attr.aria-label]': 'config.lastLabel',
+    '[attr.aria-disabled]': 'isDisabled() ? "true" : null',
+    '[attr.data-disabled]': 'isDisabled() ? "" : null',
+    '[attr.tabindex]': '"0"',
+    '[attr.data-pagination-action]': '"last"',
+    '(click)': 'onClick($event)',
+  },
+})
+export class KjPaginationLast {
+  /** @internal */
+  readonly pagination = inject(KJ_PAGINATION);
+  /** @internal */
+  readonly config = inject(KJ_PAGINATION_CONFIG);
+  private readonly el = inject<ElementRef<HTMLElement>>(ElementRef);
+
+  /** True when on the last page or the dataset is empty. */
+  readonly isDisabled = computed(() => this.pagination.isLastPage());
+
+  constructor() {
+    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.goToLast();
+  }
+}

package/src/pagination/pagination-next.ts

@@ -0,0 +1,86 @@
+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 advances one page. Mirror of
+ * {@link KjPaginationPrevious}: disabled (via `aria-disabled`, not the
+ * native `disabled` attribute) when the parent is on the last page or
+ * the dataset is empty; remains in the focus ring (`tabindex="0"`) even
+ * when disabled.
+ *
+ * @example
+ * ```html
+ * <button kjButton kjPaginationNext>Next</button>
+ * ```
+ *
+ * @doc-category Core/Navigation
+ * @doc
+ * @doc-name pagination
+ */
+@Directive({
+  selector: '[kjPaginationNext]',
+  standalone: true,
+  hostDirectives: [
+    { directive: KjVariant, inputs: ['kjVariant'] },
+    { directive: KjSize, inputs: ['kjSize'] },
+    KjFocusRing,
+  ],
+  host: {
+    '[attr.aria-label]': 'config.nextLabel',
+    '[attr.aria-disabled]': 'isDisabled() ? "true" : null',
+    '[attr.data-disabled]': 'isDisabled() ? "" : null',
+    '[attr.tabindex]': '"0"',
+    '[attr.data-pagination-action]': '"next"',
+    '(click)': 'onClick($event)',
+  },
+})
+export class KjPaginationNext {
+  /** @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 the last page or the dataset is empty. */
+  readonly isDisabled = computed(() => this.pagination.isLastPage());
+
+  constructor() {
+    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.goToNext();
+  }
+}