@kouji-ui/core 0.1.1 → 0.1.2

package/src/pagination/config.ts

@@ -1,82 +0,0 @@
-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

@@ -1,19 +0,0 @@
-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

@@ -1,78 +0,0 @@
-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

@@ -1,69 +0,0 @@
-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

@@ -1,84 +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 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

@@ -1,70 +0,0 @@
-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

@@ -1,81 +0,0 @@
-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

@@ -1,85 +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 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

@@ -1,86 +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 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();
-  }
-}