@kouji-ui/components 0.1.1

package/src/table/table-filters/text-filter.ts

@@ -0,0 +1,110 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  DestroyRef,
+  InjectionToken,
+  ViewEncapsulation,
+  computed,
+  inject,
+} from '@angular/core';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
+import { FormControl, ReactiveFormsModule } from '@angular/forms';
+import { debounceTime } from 'rxjs/operators';
+import type { Column, Table } from '@tanstack/angular-table';
+import { KjVisuallyHidden, type KjTextFilterModel } from '@kouji-ui/core';
+import { KjInputComponent } from '../../input/input';
+
+/**
+ * Context passed to every built-in filter UI. Resolves the TanStack
+ * `Column` whose filter value the input writes, and the parent `Table`
+ * for cross-column wiring (e.g. faceted unique values).
+ */
+export interface KjFilterContext<TData = unknown> {
+  readonly column: Column<TData, unknown>;
+  readonly table: Table<TData>;
+}
+
+/** DI token used to inject the `KjFilterContext` into filter components. */
+export const KJ_FILTER_CONTEXT = new InjectionToken<KjFilterContext>(
+  'kj.filter.context',
+);
+
+/** Default debounce window for the text filter, in milliseconds. */
+const DEFAULT_DEBOUNCE_MS = 300;
+
+/**
+ * Text filter UI. Renders a styled `<kj-input>` that writes the typed
+ * string to `column.setFilterValue(...)` after a 300ms debounce so
+ * keystrokes don't flood the table's filter model.
+ *
+ * Initial render seeds from `column.getFilterValue()` so the input
+ * round-trips when the filter is restored from URL/state.
+ *
+ * The input is labelled via a wrapping `<label>` carrying a visually
+ * hidden caption (`Filter by <header>`) so screen readers announce the
+ * column the filter targets.
+ *
+ * @example
+ * ```html
+ * <kj-text-filter />  <!-- KJ_FILTER_CONTEXT must be provided in the host -->
+ * ```
+ */
+@Component({
+  selector: 'kj-text-filter',
+  standalone: true,
+  imports: [ReactiveFormsModule, KjInputComponent, KjVisuallyHidden],
+  styleUrl: './filters.css',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    class: 'kj-text-filter',
+  },
+  template: `
+    <div class="kj-text-filter__label">
+      <span kjVisuallyHidden>{{ ariaLabel() }}</span>
+      <kj-input
+        class="kj-text-filter__input"
+        type="search"
+        kjSize="xs"
+        [formControl]="control"
+      />
+    </div>
+  `,
+})
+export class KjTextFilter<TData = unknown> {
+  private readonly ctx = inject<KjFilterContext<TData>>(KJ_FILTER_CONTEXT);
+  private readonly destroyRef = inject(DestroyRef);
+
+  /** Reactive form control driving the styled `<kj-input>`. */
+  protected readonly control = new FormControl<string>(
+    (() => {
+      const v = this.ctx.column.getFilterValue();
+      if (typeof v === 'string') return v;
+      if (v && typeof v === 'object' && (v as { filterType?: string }).filterType === 'text') {
+        return (v as KjTextFilterModel).filter ?? '';
+      }
+      return '';
+    })(),
+    { nonNullable: true },
+  );
+
+  /** Accessible label derived from the column header. */
+  protected readonly ariaLabel = computed(() => {
+    const header = this.ctx.column.columnDef.header;
+    const label = typeof header === 'string' ? header : this.ctx.column.id;
+    return `Filter by ${label}`;
+  });
+
+  constructor() {
+    this.control.valueChanges
+      .pipe(debounceTime(DEFAULT_DEBOUNCE_MS), takeUntilDestroyed(this.destroyRef))
+      .subscribe((value) => {
+        if (value === '') {
+          this.ctx.column.setFilterValue(undefined);
+          return;
+        }
+        const model: KjTextFilterModel = { filterType: 'text', type: 'contains', filter: value };
+        this.ctx.column.setFilterValue(model);
+      });
+  }
+}

package/src/table/table-pagination.spec.ts

@@ -0,0 +1,118 @@
+import { Component, signal, viewChild, ChangeDetectionStrategy } from '@angular/core';
+import { fireEvent, render } from '@testing-library/angular';
+import { describe, expect, it } from 'vitest';
+import { KjTable, kjColumn } from '@kouji-ui/core';
+import { KjTablePaginationComponent } from './table-pagination';
+
+interface Row {
+  id: string;
+  name: string;
+}
+
+function makeRows(n: number): Row[] {
+  return Array.from({ length: n }, (_, i) => ({ id: String(i + 1), name: `Row ${i + 1}` }));
+}
+
+// KJ_TABLE is provided on the element hosting the `kjTable` directive. The
+// pagination component must therefore be projected *inside* that element so
+// it can inject the token via element-injector inheritance. We park it in a
+// dedicated `<td>` so the markup remains valid `<table>` content.
+@Component({
+  standalone: true,
+  imports: [KjTable, KjTablePaginationComponent],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <table [kjTable]="cols" [kjTableData]="data()" #t="kjTable">
+      <tbody>
+        <tr>
+          <td>
+            <kj-table-pagination [kjPageSizes]="pageSizes()" [kjShowSummary]="showSummary()" />
+          </td>
+        </tr>
+      </tbody>
+    </table>
+  `,
+})
+class Host {
+  protected readonly data = signal<Row[]>(makeRows(25));
+  protected readonly cols = [kjColumn<Row>({ accessorKey: 'name', header: 'Name' })];
+  protected readonly pageSizes = signal<readonly number[]>([10, 25, 50]);
+  protected readonly showSummary = signal(true);
+  readonly tableRef = viewChild.required(KjTable);
+
+  setShowSummary(v: boolean): void {
+    this.showSummary.set(v);
+  }
+}
+
+describe('KjTablePaginationComponent', () => {
+  it('renders summary "Showing 1–10 of 25" when pageIndex=0, pageSize=10, total=25', async () => {
+    const { fixture, getByText } = await render(Host);
+    fixture.componentInstance.tableRef().setState({ pagination: { pageIndex: 0, pageSize: 10 } });
+    fixture.detectChanges();
+    expect(getByText(/Showing 1.10 of 25/)).toBeInTheDocument();
+  });
+
+  it('changing the page-size <kj-select> calls setPageSize on the table', async () => {
+    const { fixture, container } = await render(Host);
+    fixture.componentInstance.tableRef().setState({ pagination: { pageIndex: 0, pageSize: 10 } });
+    fixture.detectChanges();
+
+    // Open the kj-select trigger.
+    const trigger = container.querySelector('kj-select button') as HTMLButtonElement;
+    fireEvent.click(trigger);
+    fixture.detectChanges();
+
+    // Options are portalled to document.body via kj-select-content. Pick the
+    // one whose visible text is "25" and click it.
+    const options = Array.from(document.querySelectorAll('[role="option"]')) as HTMLElement[];
+    const opt25 = options.find((o) => o.textContent?.trim() === '25');
+    expect(opt25).toBeDefined();
+    fireEvent.click(opt25!);
+    fixture.detectChanges();
+
+    expect(fixture.componentInstance.tableRef().state.pagination().pageSize).toBe(25);
+  });
+
+  it('clicking Next moves pageIndex forward', async () => {
+    const { fixture, getByLabelText } = await render(Host);
+    fixture.componentInstance.tableRef().setState({ pagination: { pageIndex: 0, pageSize: 10 } });
+    fixture.detectChanges();
+
+    fireEvent.click(getByLabelText('Next page'));
+    fixture.detectChanges();
+
+    expect(fixture.componentInstance.tableRef().state.pagination().pageIndex).toBe(1);
+  });
+
+  it('Previous button is disabled on page 0', async () => {
+    const { fixture, getByLabelText } = await render(Host);
+    fixture.componentInstance.tableRef().setState({ pagination: { pageIndex: 0, pageSize: 10 } });
+    fixture.detectChanges();
+
+    const prev = getByLabelText('Previous page') as HTMLButtonElement;
+    expect(prev.getAttribute('aria-disabled')).toBe('true');
+  });
+
+  it('Last jumps to final page, First returns to page 0', async () => {
+    const { fixture, getByLabelText } = await render(Host);
+    fixture.componentInstance.tableRef().setState({ pagination: { pageIndex: 0, pageSize: 10 } });
+    fixture.detectChanges();
+
+    fireEvent.click(getByLabelText('Last page'));
+    fixture.detectChanges();
+    expect(fixture.componentInstance.tableRef().state.pagination().pageIndex).toBe(2);
+
+    fireEvent.click(getByLabelText('First page'));
+    fixture.detectChanges();
+    expect(fixture.componentInstance.tableRef().state.pagination().pageIndex).toBe(0);
+  });
+
+  it('summary is hidden when [kjShowSummary]="false"', async () => {
+    const { fixture, queryByText } = await render(Host);
+    fixture.componentInstance.tableRef().setState({ pagination: { pageIndex: 0, pageSize: 10 } });
+    fixture.componentInstance.setShowSummary(false);
+    fixture.detectChanges();
+    expect(queryByText(/Showing /)).toBeNull();
+  });
+});

package/src/table/table-pagination.ts

@@ -0,0 +1,191 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  ViewEncapsulation,
+  computed,
+  inject,
+  input,
+} from '@angular/core';
+import { KJ_TABLE, KjTable } from '@kouji-ui/core';
+import {
+  KjPaginationComponent,
+  KjPaginationFirstComponent,
+  KjPaginationPreviousComponent,
+  KjPaginationNextComponent,
+  KjPaginationLastComponent,
+} from '../pagination';
+import { KjSelectComponent, KjOptionComponent } from '../select';
+
+/**
+ * Pagination footer for `<kj-table>`. Reads the active TanStack table
+ * instance via `KJ_TABLE` and writes through its mutation API
+ * (`setPageIndex`, `setPageSize`). Composes `<kj-pagination>` for the
+ * navigation row (First / Previous / Next / Last) and `<kj-select>` for the
+ * page-size control, plus a "Showing X–Y of Z" `aria-live` summary.
+ *
+ * Index translation: `KjPagination` is 1-indexed (page 1..N) whereas
+ * TanStack's `pageIndex` is 0-indexed. The component translates at the
+ * boundary — `kjPage` bound to `pageIndex() + 1`, and `(kjPageChange)`
+ * writes `next - 1` back to `setPageIndex`. `kjTotalPages` is clamped to a
+ * minimum of `1` to satisfy the pagination directive's clamp invariant when
+ * the dataset is empty (zero rows still yields one empty page).
+ *
+ * Project into a `<kj-table>` (or any element hosting the `KjTable`
+ * directive) so the component can resolve the shared table state.
+ *
+ * @example
+ * ```html
+ * <kj-table [kjData]="rows()" [kjColumns]="cols">
+ *   <kj-table-pagination [kjPageSizes]="[10, 25, 50]" />
+ * </kj-table>
+ * ```
+ *
+ * @doc-category Components/Data
+ * @doc
+ * @doc-name table-pagination
+ * @doc-description Page-size selector, First/Prev/Next/Last nav, and "Showing N–M of total" summary bound to the parent table.
+ */
+@Component({
+  selector: 'kj-table-pagination',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [
+    KjPaginationComponent,
+    KjPaginationFirstComponent,
+    KjPaginationPreviousComponent,
+    KjPaginationNextComponent,
+    KjPaginationLastComponent,
+    KjSelectComponent,
+    KjOptionComponent,
+  ],
+  host: {
+    class: 'kj-table-pagination',
+    '[attr.data-size]': "kjSize() === 'md' ? null : kjSize()",
+  },
+  styles: [`
+    /* Three-column footer:
+       [ page-size ]   [ Showing N–M of T ]   [ « ‹ — › » ]
+       The nav row uses justify-content: space-between so the prev/next
+       cluster doesn't bunch against the boundary buttons — the row reads
+       as separate jump-to-edge and step-by-one controls. */
+    .kj-table-pagination {
+      display: flex;
+      align-items: center;
+      gap: var(--kj-space-md);
+      padding: var(--kj-space-sm) var(--kj-space-md);
+      border-top: 1px solid var(--kj-border-default);
+      background: var(--kj-bg-surface);
+      font-size: var(--kj-text-sm);
+      color: var(--kj-fg-default);
+    }
+    .kj-table-pagination__page-size {
+      display: inline-flex;
+      align-items: center;
+      gap: var(--kj-space-xs);
+      color: var(--kj-fg-muted);
+      white-space: nowrap;
+    }
+    .kj-table-pagination__summary {
+      flex: 1 1 auto;
+      text-align: center;
+      color: var(--kj-fg-muted);
+      white-space: nowrap;
+    }
+    /* The nav row carries the four boundary/step buttons. space-between
+       splits them into two visual clusters — «‹ on one side, ›» on the
+       other — when the row is given a fixed width. */
+    .kj-table-pagination__nav {
+      display: inline-flex;
+      align-items: center;
+      gap: var(--kj-space-xs);
+      justify-content: space-between;
+      min-width: 8rem;
+    }
+  `],
+  template: `
+    <div class="kj-table-pagination__page-size">
+      <span class="kj-table-pagination__page-size-label">Rows per page</span>
+      <kj-select
+        class="kj-table-pagination__select"
+        [kjSize]="kjSize()"
+        [value]="pageSize()"
+        (valueChange)="onPageSizeChange($event)"
+      >
+        @for (size of kjPageSizes(); track size) {
+          <kj-option [value]="size">{{ size }}</kj-option>
+        }
+      </kj-select>
+    </div>
+
+    @if (kjShowSummary()) {
+      <span class="kj-table-pagination__summary" aria-live="polite">
+        Showing {{ summary().start }}–{{ summary().end }} of {{ summary().total }}
+      </span>
+    }
+
+    <kj-pagination
+      class="kj-table-pagination__nav"
+      [kjSize]="kjSize()"
+      [kjPage]="page1Indexed()"
+      [kjTotalPages]="totalPages()"
+      (kjPageChange)="onPageChange($event)"
+    >
+      <kj-pagination-first [kjSize]="kjSize()">«</kj-pagination-first>
+      <kj-pagination-previous [kjSize]="kjSize()">‹</kj-pagination-previous>
+      <kj-pagination-next [kjSize]="kjSize()">›</kj-pagination-next>
+      <kj-pagination-last [kjSize]="kjSize()">»</kj-pagination-last>
+    </kj-pagination>
+  `,
+  encapsulation: ViewEncapsulation.None,
+})
+export class KjTablePaginationComponent {
+  /** Available page sizes for the selector. */
+  readonly kjPageSizes = input<readonly number[]>([10, 25, 50, 100]);
+  /** Show the "Showing N–M of total" summary. Default `true`. */
+  readonly kjShowSummary = input<boolean>(true);
+  /** Size tier — matches the rest of the design system. `xs` for dense
+   *  footers, `lg` for touch-first. Forwarded to both the page-size select
+   *  and the nav buttons so the row stays visually consistent. */
+  readonly kjSize = input<'xs' | 'sm' | 'md' | 'lg'>('md');
+
+  protected readonly tableCtx = inject(KJ_TABLE) as KjTable<unknown>;
+
+  protected readonly pageSize = computed(() => this.tableCtx.state.pagination().pageSize);
+  protected readonly pageIndex = computed(() => this.tableCtx.state.pagination().pageIndex);
+
+  /** TanStack `pageIndex` (0-indexed) translated to `KjPagination`'s 1-indexed model. */
+  protected readonly page1Indexed = computed(() => this.pageIndex() + 1);
+
+  /**
+   * Total pages reported by TanStack, clamped to a minimum of 1. The
+   * pagination directive treats `kjTotalPages <= 0` as "no pages" and locks
+   * `kjPage` to 1 — passing 1 here avoids the clamp on empty datasets.
+   */
+  protected readonly totalPages = computed(() =>
+    Math.max(1, this.tableCtx.table().getPageCount()),
+  );
+
+  protected readonly summary = computed(() => {
+    const t = this.tableCtx.table();
+    const total = t.getRowCount();
+    const size = this.pageSize();
+    const idx = this.pageIndex();
+    if (total === 0) return { start: 0, end: 0, total: 0 };
+    const start = idx * size + 1;
+    const end = Math.min(start + size - 1, total);
+    return { start, end, total };
+  });
+
+  /** Receive 1-indexed page from `KjPagination` and translate to 0-indexed `setPageIndex`. */
+  protected onPageChange(next1Indexed: number): void {
+    const next = next1Indexed - 1;
+    if (next === this.pageIndex()) return;
+    this.tableCtx.table().setPageIndex(next);
+  }
+
+  protected onPageSizeChange(value: unknown): void {
+    const next = Number(value);
+    if (!Number.isFinite(next) || next === this.pageSize()) return;
+    this.tableCtx.table().setPageSize(next);
+  }
+}

package/src/table/table-side-panel.spec.ts

@@ -0,0 +1,170 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { render, fireEvent } from '@testing-library/angular';
+import { afterEach, describe, expect, it } from 'vitest';
+import { KjTable, kjColumn } from '@kouji-ui/core';
+import { KjTableSidePanelComponent } from './table-side-panel';
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  role: string;
+}
+
+const COLS = [
+  kjColumn<User>({ accessorKey: 'name', header: 'Name', id: 'name' }),
+  kjColumn<User>({ accessorKey: 'email', header: 'Email', id: 'email' }),
+  kjColumn<User>({ accessorKey: 'role', header: 'Role', id: 'role' }),
+];
+
+@Component({
+  standalone: true,
+  imports: [KjTable, KjTableSidePanelComponent],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <table [kjTable]="cols" [kjTableData]="data()">
+      <kj-table-side-panel [(kjOpen)]="open" [kjTitle]="title()" />
+    </table>
+  `,
+})
+class Host {
+  readonly data = signal<User[]>([
+    { id: '1', name: 'Ada', email: 'a@x', role: 'admin' },
+    { id: '2', name: 'Linus', email: 'l@x', role: 'user' },
+  ]);
+  readonly cols = COLS;
+  readonly open = signal(false);
+  readonly title = signal('Columns');
+}
+
+/** Drawer is portaled — query the body, not the host fixture. */
+function getDrawer(): HTMLElement | null {
+  return document.body.querySelector<HTMLElement>('kj-drawer');
+}
+
+function getDrawerOrThrow(): HTMLElement {
+  const el = getDrawer();
+  if (!el) throw new Error('drawer not rendered');
+  return el;
+}
+
+function cleanupOverlays(): void {
+  document.body
+    .querySelectorAll('kj-drawer-shell, kj-overlay-wrapper, .kj-overlay-container')
+    .forEach((el) => el.remove());
+  document.body.querySelectorAll('kj-drawer').forEach((el) => el.remove());
+  document.documentElement.style.overflow = '';
+  document.documentElement.style.paddingRight = '';
+}
+
+describe('KjTableSidePanelComponent', () => {
+  afterEach(() => {
+    cleanupOverlays();
+  });
+
+  it('mounts no drawer DOM when kjOpen=false; mounts a portaled drawer when true', async () => {
+    const { fixture } = await render(Host);
+    expect(getDrawer()).toBeNull();
+
+    fixture.componentInstance.open.set(true);
+    fixture.detectChanges();
+    await fixture.whenStable();
+
+    const drawer = getDrawerOrThrow();
+    expect(drawer.getAttribute('data-kj-side')).toBe('right');
+  });
+
+  it('lists every leaf column from the table', async () => {
+    const { fixture } = await render(Host);
+    fixture.componentInstance.open.set(true);
+    fixture.detectChanges();
+    await fixture.whenStable();
+
+    const drawer = getDrawerOrThrow();
+    expect(drawer.textContent).toContain('Name');
+    expect(drawer.textContent).toContain('Email');
+    expect(drawer.textContent).toContain('Role');
+
+    const checkboxes = drawer.querySelectorAll('input[type="checkbox"]');
+    expect(checkboxes.length).toBe(3);
+  });
+
+  it('toggling a column checkbox flips column visibility', async () => {
+    const { fixture } = await render(Host);
+    fixture.componentInstance.open.set(true);
+    fixture.detectChanges();
+    await fixture.whenStable();
+
+    const drawer = getDrawerOrThrow();
+    const emailCheckbox = drawer.querySelectorAll('input[type="checkbox"]')[1] as HTMLInputElement;
+    expect(emailCheckbox.checked).toBe(true);
+
+    fireEvent.click(emailCheckbox);
+    fixture.detectChanges();
+    await fixture.whenStable();
+
+    const after = getDrawerOrThrow().querySelectorAll(
+      'input[type="checkbox"]',
+    )[1] as HTMLInputElement;
+    expect(after.checked).toBe(false);
+  });
+
+  it('clicking "Pin left" pushes the column id into columnPinning.left', async () => {
+    const { fixture } = await render(Host);
+    fixture.componentInstance.open.set(true);
+    fixture.detectChanges();
+    await fixture.whenStable();
+
+    const drawer = getDrawerOrThrow();
+    const pinLeftBtn = drawer.querySelectorAll(
+      'button[data-action="pin-left"]',
+    )[0] as HTMLButtonElement;
+    fireEvent.click(pinLeftBtn);
+    fixture.detectChanges();
+    await fixture.whenStable();
+
+    const after = getDrawerOrThrow().querySelectorAll(
+      'button[data-action="pin-left"]',
+    )[0] as HTMLButtonElement;
+    expect(after.getAttribute('aria-pressed')).toBe('true');
+  });
+
+  it('clicking "Group by" pushes the column id into grouping', async () => {
+    const { fixture } = await render(Host);
+    fixture.componentInstance.open.set(true);
+    fixture.detectChanges();
+    await fixture.whenStable();
+
+    const findRoleGroupBtn = (): HTMLButtonElement => {
+      const drawer = getDrawerOrThrow();
+      const rows = Array.from(drawer.querySelectorAll('.kj-table-side-panel-row'));
+      const roleRow = rows.find((r) => r.textContent?.includes('Role'));
+      if (!roleRow) throw new Error('Role row missing');
+      return roleRow.querySelector('button[data-action="group"]') as HTMLButtonElement;
+    };
+
+    fireEvent.click(findRoleGroupBtn());
+    fixture.detectChanges();
+    await fixture.whenStable();
+
+    expect(findRoleGroupBtn().getAttribute('aria-pressed')).toBe('true');
+  });
+
+  it('renders the kjTitle in the drawer header', async () => {
+    const { fixture } = await render(Host);
+    fixture.componentInstance.title.set('Pick your columns');
+    fixture.componentInstance.open.set(true);
+    fixture.detectChanges();
+    await fixture.whenStable();
+
+    const drawer = getDrawerOrThrow();
+    const title = drawer.querySelector('.kj-drawer-title') as HTMLElement;
+    expect(title).toBeTruthy();
+    expect(title.textContent).toBe('Pick your columns');
+    // The host element of the content component (parent of `<kj-drawer>`)
+    // carries the accessible name via `aria-label`.
+    const content = document.body.querySelector('kj-table-side-panel-content') as HTMLElement;
+    expect(content).toBeTruthy();
+    expect(content.getAttribute('aria-label')).toBe('Pick your columns');
+  });
+});