@kouji-ui/components 0.1.1

package/src/table/table-toolbar.ts

@@ -0,0 +1,244 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  Directive,
+  ViewEncapsulation,
+  computed,
+  inject,
+  output,
+} from '@angular/core';
+import { KJ_TABLE, KjTable } from '@kouji-ui/core';
+import { KjInputComponent } from '../input/input';
+import { KjButtonComponent } from '../button/button';
+import { KjButtonGroupComponent } from '../button-group/button-group';
+import { KjCheckboxComponent } from '../checkbox/checkbox';
+import {
+  KjDropdownMenuTrigger,
+  KjDropdownMenuContent,
+  KjDropdownMenuItem,
+  KjDropdownMenuSeparator,
+} from '@kouji-ui/core';
+
+/** Density value emitted by the density toggle group. */
+export type KjTableDensity = 'compact' | 'standard' | 'comfortable';
+
+/** Export format requested via the toolbar's export menu. */
+export type KjTableExportFormat = 'csv' | 'json' | 'clipboard';
+
+/**
+ * Marker directive for bulk-action content projected into
+ * `<kj-table-toolbar>`. Bulk content is only rendered when the host
+ * table has any selected rows.
+ *
+ * @example
+ * ```html
+ * <kj-table-toolbar>
+ *   <kj-button kjVariant="destructive" kjBulkAction>Delete</kj-button>
+ * </kj-table-toolbar>
+ * ```
+ */
+@Directive({
+  selector: '[kjBulkAction]',
+  standalone: true,
+})
+export class KjBulkAction {}
+
+/**
+ * Toolbar chrome for `<kj-table>`. Composes:
+ *
+ * - **Quick filter input** — bound to `KjTable.globalFilter()`; typing writes
+ *   `setState({ globalFilter })`.
+ * - **Density toggle group** — three segmented buttons (compact / standard /
+ *   comfortable) bound to `KjTable.density()`.
+ * - **Column visibility menu** — dropdown listing every leaf column with a
+ *   checkbox; toggling writes `setState({ columnVisibility })`.
+ * - **Export menu** — dropdown with CSV / JSON / Clipboard items. Items emit
+ *   the `(export)` output; the parent table wires the actual export utility
+ *   in Phase C.
+ * - **Bulk-action slot** — `<ng-content select="[kjBulkAction]">` shown only
+ *   when at least one row is selected.
+ *
+ * The toolbar must sit inside a `<kj-table>` (or any element hosting
+ * the `KJ_TABLE` token) so it can resolve the table instance via DI.
+ *
+ * @doc-category Components/Data
+ * @doc
+ * @doc-name table-toolbar
+ * @doc-description Toolbar chrome above the data table — quick filter, density, column visibility, export, and bulk-action slot.
+ */
+@Component({
+  selector: 'kj-table-toolbar',
+  standalone: true,
+  imports: [
+    KjInputComponent,
+    KjButtonComponent,
+    KjButtonGroupComponent,
+    KjCheckboxComponent,
+    KjDropdownMenuTrigger,
+    KjDropdownMenuContent,
+    KjDropdownMenuItem,
+    KjDropdownMenuSeparator,
+  ],
+  template: `
+    <div class="kj-table-toolbar__filter">
+      <span class="kj-visually-hidden">Quick filter</span>
+      <kj-input
+        type="search"
+        placeholder="Filter rows..."
+        [value]="globalFilter()"
+        (input)="onFilter($event)"
+      />
+    </div>
+
+    <kj-button-group
+      class="kj-table-toolbar__density"
+      kjAriaLabel="Row density"
+    >
+      <kj-button
+        kjVariant="outline"
+        kjSize="sm"
+        [kjPressed]="density() === 'compact'"
+        kjAriaLabel="Compact density"
+        (click)="setDensity('compact')"
+      >Compact</kj-button>
+      <kj-button
+        kjVariant="outline"
+        kjSize="sm"
+        [kjPressed]="density() === 'standard'"
+        kjAriaLabel="Standard density"
+        (click)="setDensity('standard')"
+      >Standard</kj-button>
+      <kj-button
+        kjVariant="outline"
+        kjSize="sm"
+        [kjPressed]="density() === 'comfortable'"
+        kjAriaLabel="Comfortable density"
+        (click)="setDensity('comfortable')"
+      >Comfortable</kj-button>
+    </kj-button-group>
+
+    <kj-button
+      kjDropdownMenuTrigger
+      #colTrigger="kjDropdownMenuTrigger"
+      kjVariant="outline"
+      kjSize="sm"
+    >Columns</kj-button>
+    <kj-dropdown-menu-content [kjFor]="colTrigger">
+      @for (col of leafColumns(); track col.id) {
+        <div kjDropdownMenuItem role="menuitemcheckbox" [attr.aria-checked]="isVisible(col.id)">
+          <kj-checkbox
+            [checked]="isVisible(col.id)"
+            (checkedChange)="setColumnVisible(col.id, $event)"
+          >{{ columnLabel(col) }}</kj-checkbox>
+        </div>
+      }
+    </kj-dropdown-menu-content>
+
+    <kj-button
+      kjDropdownMenuTrigger
+      #expTrigger="kjDropdownMenuTrigger"
+      kjVariant="outline"
+      kjSize="sm"
+    >Export</kj-button>
+    <kj-dropdown-menu-content [kjFor]="expTrigger">
+      <button kjDropdownMenuItem type="button" (click)="emitExport('csv')">Export as CSV</button>
+      <button kjDropdownMenuItem type="button" (click)="emitExport('json')">Export as JSON</button>
+      <hr kjDropdownMenuSeparator />
+      <button kjDropdownMenuItem type="button" (click)="emitExport('clipboard')">Copy to clipboard</button>
+    </kj-dropdown-menu-content>
+
+    @if (hasSelection()) {
+      <div class="kj-table-toolbar__bulk" role="group" aria-label="Bulk actions">
+        <ng-content select="[kjBulkAction]" />
+      </div>
+    }
+  `,
+  styles: [`
+    :host {
+      display: flex;
+      /* Stay on a single row even when a bulk-action slot appears — wrapping
+         would push the table down. The filter shrinks to make room. */
+      flex-wrap: nowrap;
+      align-items: center;
+      gap: var(--kj-base-space-md, 0.75rem);
+      padding: var(--kj-base-space-md, 0.75rem);
+    }
+    .kj-table-toolbar__filter { flex: 1 1 16rem; min-width: 6rem; display: flex; align-items: center; }
+    .kj-table-toolbar__filter .kj-input { width: 100%; }
+    .kj-table-toolbar__filter .kj-visually-hidden {
+      position: absolute;
+      width: 1px; height: 1px;
+      padding: 0; margin: -1px;
+      overflow: hidden;
+      clip: rect(0, 0, 0, 0);
+      white-space: nowrap;
+      border: 0;
+    }
+    .kj-table-toolbar__bulk {
+      display: flex;
+      gap: var(--kj-base-space-sm, 0.5rem);
+      margin-inline-start: auto;
+    }
+  `],
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    'class': 'kj-table-toolbar',
+    'role': 'toolbar',
+    'aria-label': 'Data table toolbar',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjTableToolbarComponent {
+  /** The host table — resolved through `KJ_TABLE` injected from any ancestor. */
+  protected readonly table = inject<KjTable<unknown>>(KJ_TABLE);
+
+  /** Emits when the user picks an export format from the toolbar's export menu. */
+  readonly export = output<KjTableExportFormat>();
+
+  protected readonly globalFilter = this.table.state.globalFilter;
+  protected readonly density = this.table.state.density;
+
+  /** All leaf columns from the TanStack table instance. Recomputes when columns change. */
+  protected readonly leafColumns = computed(() => {
+    const t = this.table.table();
+    return t.getAllLeafColumns();
+  });
+
+  /** True when the host table has at least one selected row. */
+  protected readonly hasSelection = computed(() => {
+    const sel = this.table.state.rowSelection();
+    for (const key in sel) {
+      if (sel[key]) return true;
+    }
+    return false;
+  });
+
+  protected onFilter(event: Event): void {
+    const value = (event.target as HTMLInputElement).value;
+    this.table.setState({ globalFilter: value });
+  }
+
+  protected setDensity(value: KjTableDensity): void {
+    this.table.setState({ density: value });
+  }
+
+  protected isVisible(columnId: string): boolean {
+    const map = this.table.state.columnVisibility();
+    // TanStack convention: a column is visible unless explicitly false.
+    return map[columnId] !== false;
+  }
+
+  protected setColumnVisible(columnId: string, visible: boolean): void {
+    const next = { ...this.table.state.columnVisibility(), [columnId]: visible };
+    this.table.setState({ columnVisibility: next });
+  }
+
+  protected columnLabel(col: { id: string; columnDef: { header?: unknown } }): string {
+    const header = col.columnDef.header;
+    return typeof header === 'string' ? header : col.id;
+  }
+
+  protected emitExport(format: KjTableExportFormat): void {
+    this.export.emit(format);
+  }
+}

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

@@ -0,0 +1,103 @@
+import { Component, signal, viewChild, ChangeDetectionStrategy } from '@angular/core';
+import { render } from '@testing-library/angular';
+import { beforeAll, describe, expect, it, vi } from 'vitest';
+import { KjTableVirtual } from './table-virtual';
+
+// jsdom does not implement layout or ResizeObserver; virtual-core uses both
+// (ResizeObserver for the scroll rect, plus reads `offsetWidth/offsetHeight`
+// on the scroll element). Stub them with deterministic values so the
+// virtualizer "sees" a 200px tall viewport.
+class StubResizeObserver {
+  observe(): void {}
+  unobserve(): void {}
+  disconnect(): void {}
+}
+
+beforeAll(() => {
+  vi.stubGlobal('ResizeObserver', StubResizeObserver);
+  // virtual-core's `observeElementRect` reads `element.offsetWidth` /
+  // `element.offsetHeight` (see node_modules/@tanstack/virtual-core/.../index.js
+  // `getRect`). jsdom returns 0 for both, so force a 400×200 viewport via
+  // prototype getters.
+  Object.defineProperty(HTMLElement.prototype, 'offsetWidth', {
+    configurable: true,
+    get(): number {
+      return 400;
+    },
+  });
+  Object.defineProperty(HTMLElement.prototype, 'offsetHeight', {
+    configurable: true,
+    get(): number {
+      return 200;
+    },
+  });
+});
+
+@Component({
+  standalone: true,
+  imports: [KjTableVirtual],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <div
+      kjTableVirtual
+      [kjCount]="count()"
+      [kjEstimateSize]="estimate()"
+      [kjOverscan]="overscan()"
+      style="height: 200px; overflow: auto;"
+      #v="kjTableVirtual"
+    >
+      <div [style.height.px]="v.totalSize()"></div>
+    </div>
+  `,
+})
+class Host {
+  protected readonly count = signal(100);
+  protected readonly estimate = signal(20);
+  protected readonly overscan = signal(5);
+  readonly virt = viewChild.required(KjTableVirtual);
+
+  setCount(n: number): void {
+    this.count.set(n);
+  }
+}
+
+describe('KjTableVirtual', () => {
+  it('mounts the virtualizer and exposes virtualRows() as an array', async () => {
+    const { fixture } = await render(Host);
+    await fixture.whenStable();
+    fixture.detectChanges();
+    const virt = fixture.componentInstance.virt();
+    expect(Array.isArray(virt.virtualRows())).toBe(true);
+  });
+
+  it('windows the rows to roughly viewport / estimateSize + overscan', async () => {
+    const { fixture } = await render(Host);
+    await fixture.whenStable();
+    fixture.detectChanges();
+    const virt = fixture.componentInstance.virt();
+    const rows = virt.virtualRows();
+    // Viewport 200px / 20px row = 10 visible. With 5 overscan above + below
+    // we expect ≤ ~20 items, and certainly far fewer than the full 100.
+    expect(rows.length).toBeGreaterThan(0);
+    expect(rows.length).toBeLessThan(30);
+    expect(rows.length).toBeLessThan(100);
+  });
+
+  it('paddingTop starts at 0 and paddingBottom is positive when count > visible window', async () => {
+    const { fixture } = await render(Host);
+    await fixture.whenStable();
+    fixture.detectChanges();
+    const virt = fixture.componentInstance.virt();
+    expect(virt.paddingTop()).toBe(0);
+    expect(virt.paddingBottom()).toBeGreaterThan(0);
+  });
+
+  it('totalSize equals count * estimateSize before any measurement', async () => {
+    const { fixture } = await render(Host);
+    await fixture.whenStable();
+    fixture.detectChanges();
+    const virt = fixture.componentInstance.virt();
+    // 100 rows × 20px = 2000px
+    expect(virt.totalSize()).toBe(100 * 20);
+  });
+});

package/src/table/table-virtual.ts

@@ -0,0 +1,180 @@
+import {
+  DestroyRef,
+  Directive,
+  ElementRef,
+  afterNextRender,
+  effect,
+  inject,
+  input,
+  signal,
+} from '@angular/core';
+import {
+  Virtualizer,
+  elementScroll,
+  observeElementOffset,
+  observeElementRect,
+  type VirtualItem,
+} from '@tanstack/virtual-core';
+
+/**
+ * Mounts a `@tanstack/virtual-core` `Virtualizer` on the host element (the
+ * scroll container — typically a wrapper around the table or a tbody-level
+ * scroll viewport) and exposes the windowed row list plus top/bottom spacer
+ * sizes as signals.
+ *
+ * Consumers (the styled `<kj-table>` root) read `virtualRows()`,
+ * `paddingTop()`, `paddingBottom()` and `totalSize()` to render only the
+ * visible window of rows and reserve scrollback/scrollahead space with
+ * spacer elements.
+ *
+ * The virtualizer is mounted after the first render so the host element is
+ * laid out before `observeElementRect` / `observeElementOffset` attach. The
+ * teardown returned by `_didMount()` is wired through `DestroyRef`.
+ *
+ * @example
+ * ```html
+ * <div
+ *   KjTableVirtual
+ *   [kjCount]="rows().length"
+ *   [kjEstimateSize]="36"
+ *   [kjOverscan]="8"
+ *   class="kj-table-virtual-scroll"
+ *   #v="KjTableVirtual"
+ * >
+ *   <div [style.height.px]="v.totalSize()">
+ *     <div [style.transform]="'translateY(' + v.paddingTop() + 'px)'">
+ *       @for (vr of v.virtualRows(); track vr.key) {
+ *         <!-- render row at index vr.index -->
+ *       }
+ *     </div>
+ *   </div>
+ * </div>
+ * ```
+ *
+ * @doc-category Components/Data
+ * @doc
+ * @doc-name table-virtual
+ * @doc-description Row virtualization adapter on @tanstack/virtual-core. Exposes virtualRows / paddingTop / paddingBottom / totalSize signals for the styled data table.
+ */
+@Directive({
+  selector: '[kjTableVirtual]',
+  standalone: true,
+  exportAs: 'kjTableVirtual',
+})
+export class KjTableVirtual {
+  /** Total number of rows in the underlying dataset. */
+  readonly kjCount = input.required<number>();
+  /** Estimated px height of a single row, used before measurement. */
+  readonly kjEstimateSize = input<number>(36);
+  /** Extra rows rendered above and below the visible window. */
+  readonly kjOverscan = input<number>(5);
+
+  private readonly host = inject(ElementRef<HTMLElement>).nativeElement as HTMLElement;
+  private readonly destroyRef = inject(DestroyRef);
+
+  private virtualizer: Virtualizer<HTMLElement, HTMLElement> | null = null;
+
+  // Writable backing signals; exposed read-only via `asReadonly()` below.
+  private readonly _virtualRows = signal<VirtualItem[]>([]);
+  private readonly _totalSize = signal<number>(0);
+  private readonly _paddingTop = signal<number>(0);
+  private readonly _paddingBottom = signal<number>(0);
+
+  /** Windowed `VirtualItem`s currently visible (plus overscan). */
+  readonly virtualRows = this._virtualRows.asReadonly();
+  /** Total px size of the virtual content (used to size the inner spacer). */
+  readonly totalSize = this._totalSize.asReadonly();
+  /** Top spacer height in px (offset of the first virtual row). */
+  readonly paddingTop = this._paddingTop.asReadonly();
+  /** Bottom spacer height in px (totalSize − end of last virtual row). */
+  readonly paddingBottom = this._paddingBottom.asReadonly();
+
+  constructor() {
+    afterNextRender(() => this.mount());
+
+    // Re-apply options when inputs change. The first run is a no-op because
+    // `virtualizer` is null until `mount()` runs after the first render.
+    effect(() => {
+      const count = this.kjCount();
+      const estimate = this.kjEstimateSize();
+      const overscan = this.kjOverscan();
+      const v = this.virtualizer;
+      if (!v) return;
+      v.setOptions({
+        ...v.options,
+        count,
+        estimateSize: () => estimate,
+        overscan,
+      });
+      this.sync();
+    });
+  }
+
+  private mount(): void {
+    // The virtualizer needs the actual SCROLLABLE ancestor — not the `<tbody>`
+    // host, which doesn't scroll in a normal table. We deterministically pick
+    // the wrapper's `.kj-table-body` (always present, always the scroller in
+    // our table structure) rather than probing computed `overflow-y` at mount
+    // time — `getComputedStyle` occasionally returns the pre-flex-applied
+    // values from `afterNextRender`, which made the walk miss the scroller
+    // and fall back to the 0-height tbody, breaking virtualization entirely.
+    // The computed-style walk stays as a secondary fallback for consumers who
+    // ever embed `KjTableVirtual` outside a `kj-table`.
+    const scrollEl =
+      this.host.closest('.kj-table-body') as HTMLElement | null
+      ?? this.findScrollAncestor()
+      ?? this.host;
+    const v = new Virtualizer<HTMLElement, HTMLElement>({
+      count: this.kjCount(),
+      getScrollElement: () => scrollEl,
+      estimateSize: () => this.kjEstimateSize(),
+      overscan: this.kjOverscan(),
+      scrollToFn: elementScroll,
+      observeElementOffset,
+      observeElementRect,
+      onChange: () => this.sync(),
+    });
+    this.virtualizer = v;
+    const teardown = v._didMount();
+    this.destroyRef.onDestroy(() => {
+      teardown();
+      this.virtualizer = null;
+    });
+    this.sync();
+  }
+
+  /**
+   * Walk the ancestor chain looking for the first element whose computed
+   * `overflow-y` is `auto` or `scroll`. Returns `null` if none found (the
+   * caller falls back to the host element).
+   */
+  private findScrollAncestor(): HTMLElement | null {
+    let el: HTMLElement | null = this.host.parentElement;
+    while (el && el !== document.body) {
+      const style = getComputedStyle(el);
+      const oy = style.overflowY;
+      if (oy === 'auto' || oy === 'scroll') return el;
+      el = el.parentElement;
+    }
+    return null;
+  }
+
+  private sync(): void {
+    const v = this.virtualizer;
+    if (!v) return;
+    v._willUpdate();
+    const items = v.getVirtualItems();
+    const total = v.getTotalSize();
+    this._virtualRows.set(items);
+    this._totalSize.set(total);
+    if (items.length === 0) {
+      this._paddingTop.set(0);
+      this._paddingBottom.set(0);
+      return;
+    }
+    const first = items[0]!;
+    const last = items[items.length - 1]!;
+    this._paddingTop.set(first.start);
+    this._paddingBottom.set(Math.max(0, total - (last.start + last.size)));
+  }
+}