@kouji-ui/core 0.0.3 → 0.1.1

package/src/table/filter-params.ts

@@ -0,0 +1,90 @@
+import {
+  InjectionToken,
+  Injector,
+  Provider,
+  TemplateRef,
+  Type,
+  inject,
+  type Signal,
+} from '@angular/core';
+import type { Column, RowData } from '@tanstack/angular-table';
+import type { KjColumnApi, KjGridApi } from './grid-api';
+
+/**
+ * Context handed to every custom filter — component class or template.
+ *
+ * Mirrors AG-Grid's `IFilterParams` shape: the column being filtered, the
+ * grid + column APIs for cross-cutting actions, the current model as a
+ * reactive signal, and an imperative setter that clears the filter on
+ * `null`/`undefined`/`''`. A signal is used (rather than a callback) so
+ * filter UIs can derive bound values via `computed()` without their own
+ * change-detection plumbing.
+ *
+ * Components either accept a single required input named `params` of this
+ * shape, or call {@link injectKjFilterParams}. Templates receive the same
+ * context via `$implicit` (`let-params`).
+ */
+export interface KjFilterParams<TData extends RowData = unknown, TValue = unknown> {
+  /** The TanStack column the filter targets. */
+  readonly column: Column<TData, TValue>;
+  /** Grid-wide imperative API for cross-column actions. */
+  readonly api: KjGridApi<TData>;
+  /** Per-column imperative API. */
+  readonly columnApi: KjColumnApi<TData>;
+  /** Live filter model — reactive view of `column.getFilterValue()`. */
+  readonly model: Signal<TValue | null>;
+  /** Imperative setter. `null`, `undefined`, or `''` clear the filter. */
+  setModel(value: TValue | null | undefined): void;
+  /** True when the filter currently restricts results. */
+  isActive(): boolean;
+  /** Convenience: clear this filter. Equivalent to `setModel(null)`. */
+  clear(): void;
+}
+
+/**
+ * Anything that can render a filter UI: a standalone component class or a
+ * `TemplateRef` whose `$implicit` context is a `KjFilterParams`.
+ */
+export type KjFilterRenderer<TData extends RowData = unknown, TValue = unknown> =
+  | Type<{ params?: unknown } & object>
+  | TemplateRef<KjFilterParams<TData, TValue>>;
+
+/**
+ * Private token. Use {@link provideKjFilterParams} / {@link injectKjFilterParams}
+ * — the token itself is not exported from the package so consumers cannot
+ * bypass the helpers (and can't accidentally provide a malformed value).
+ */
+const KJ_FILTER_PARAMS = new InjectionToken<KjFilterParams>('kj.filter.params');
+
+/**
+ * Returns a `Provider` that exposes a `KjFilterParams` instance to a child
+ * injector. Used by `KjTableFilterOutlet` and the styled-wrapper's filter
+ * mounting code; user code should normally not call this directly.
+ */
+export function provideKjFilterParams<TData extends RowData, TValue>(
+  params: KjFilterParams<TData, TValue>,
+): Provider {
+  return { provide: KJ_FILTER_PARAMS, useValue: params };
+}
+
+/**
+ * Resolve the active `KjFilterParams` from the current injection context.
+ *
+ * @example
+ * ```ts
+ * @Component({ selector: 'my-filter', template: '…' })
+ * class MyFilter {
+ *   protected readonly params = injectKjFilterParams<User, string>();
+ *   protected onInput(v: string) { this.params.setModel(v || null); }
+ * }
+ * ```
+ */
+export function injectKjFilterParams<
+  TData extends RowData = unknown,
+  TValue = unknown,
+>(injector?: Injector): KjFilterParams<TData, TValue> {
+  const params = injector
+    ? injector.get(KJ_FILTER_PARAMS)
+    : inject(KJ_FILTER_PARAMS);
+  return params as KjFilterParams<TData, TValue>;
+}

package/src/table/grid-api-impl.ts

@@ -0,0 +1,321 @@
+import type { WritableSignal, Signal } from '@angular/core';
+import type {
+  ColumnFiltersState,
+  ColumnOrderState,
+  ColumnPinningState,
+  ColumnSizingState,
+  ExpandedState,
+  GroupingState,
+  PaginationState,
+  RowData,
+  RowSelectionState,
+  Table,
+  VisibilityState,
+} from '@tanstack/angular-table';
+import type {
+  KjColumnApi,
+  KjColumnGroupingApi,
+  KjColumnOrderApi,
+  KjColumnPinningApi,
+  KjColumnSizingApi,
+  KjColumnVisibilityApi,
+  KjDensityApi,
+  KjExpansionApi,
+  KjFilterApi,
+  KjGlobalFilterApi,
+  KjGridApi,
+  KjGroupingApi,
+  KjPaginationApi,
+  KjRowsApi,
+  KjSelectionApi,
+  KjSortApi,
+} from './grid-api';
+import { isKjFilterModel, type KjFilterModel, type KjGridFilterModel } from './filter-models';
+import type { KjTableDensity, KjTableState } from './table.types';
+
+/**
+ * Build a `KjGridApi` + `KjColumnApi` pair bound to a directive instance.
+ * Called once from `KjTable` and cached. Methods close over the directive's
+ * private state signal and the lazy TanStack `Table` getter so every call
+ * sees the live grid.
+ */
+export function createGridApi<TData extends RowData>(opts: {
+  state: Signal<KjTableState>;
+  table: () => Table<TData>;
+  patch: <K extends keyof KjTableState>(
+    key: K,
+    updater: KjTableState[K] | ((prev: KjTableState[K]) => KjTableState[K]),
+  ) => void;
+  setStateInternal: WritableSignal<KjTableState>['update'];
+  resetState: () => void;
+  defaultState: KjTableState;
+}): { gridApi: KjGridApi<TData>; columnApi: KjColumnApi<TData> } {
+  const { state, table, patch, resetState, defaultState } = opts;
+
+  const setStateMerge = (partial: Partial<KjTableState>): void => {
+    opts.setStateInternal((s) => ({ ...s, ...partial }));
+  };
+
+  // ── KjColumnApi namespaces ────────────────────────────────────────────────
+
+  const visibility: KjColumnVisibilityApi = {
+    get: () => state().columnVisibility,
+    set: (model) => patch('columnVisibility', model),
+    isVisible: (id) => state().columnVisibility[id] !== false,
+    setVisible: (id, visible) =>
+      patch('columnVisibility', (prev: VisibilityState) => ({ ...prev, [id]: visible })),
+    setManyVisible: (ids, visible) =>
+      patch('columnVisibility', (prev: VisibilityState) => {
+        const next = { ...prev };
+        for (const id of ids) next[id] = visible;
+        return next;
+      }),
+  };
+
+  const sizing: KjColumnSizingApi = {
+    get: () => state().columnSizing,
+    set: (model) => patch('columnSizing', model),
+    width: (id) => table().getColumn(id)?.getSize() ?? 0,
+    setWidth: (id, width) =>
+      patch('columnSizing', (prev: ColumnSizingState) => ({ ...prev, [id]: width })),
+  };
+
+  const pinning: KjColumnPinningApi = {
+    get: () => state().columnPinning,
+    set: (model) => patch('columnPinning', model),
+    of: (id) => {
+      const p = state().columnPinning;
+      if ((p.left ?? []).includes(id)) return 'left';
+      if ((p.right ?? []).includes(id)) return 'right';
+      return null;
+    },
+    pin: (id, side) =>
+      patch('columnPinning', (prev: ColumnPinningState) => ({
+        left:  (prev.left  ?? []).filter((c) => c !== id).concat(side === 'left'  ? [id] : []),
+        right: (prev.right ?? []).filter((c) => c !== id).concat(side === 'right' ? [id] : []),
+      })),
+  };
+
+  const order: KjColumnOrderApi = {
+    get: () => state().columnOrder,
+    set: (o) => patch('columnOrder', o),
+    move: (id, toIndex) =>
+      patch('columnOrder', (prev: ColumnOrderState) => {
+        const base = prev.length > 0 ? prev : table().getAllLeafColumns().map((c) => c.id);
+        const without = base.filter((c) => c !== id);
+        const clamped = Math.max(0, Math.min(toIndex, without.length));
+        return [...without.slice(0, clamped), id, ...without.slice(clamped)];
+      }),
+  };
+
+  const colGrouping: KjColumnGroupingApi = {
+    is: (id) => state().grouping.includes(id),
+    set: (id, grouped) =>
+      patch('grouping', (prev: GroupingState) =>
+        grouped
+          ? prev.includes(id) ? prev : [...prev, id]
+          : prev.filter((c) => c !== id),
+      ),
+  };
+
+  const columnApi: KjColumnApi<TData> = {
+    get: (id) => table().getColumn(id) ?? null,
+    all: () => table().getAllColumns(),
+    leaves: () => table().getAllLeafColumns(),
+    visibleLeaves: () => table().getVisibleLeafColumns(),
+    visibility,
+    sizing,
+    pinning,
+    order,
+    grouping: colGrouping,
+    reset: () =>
+      setStateMerge({
+        columnVisibility: defaultState.columnVisibility,
+        columnSizing:     defaultState.columnSizing,
+        columnPinning:    defaultState.columnPinning,
+        columnOrder:      defaultState.columnOrder,
+        grouping:         defaultState.grouping,
+      }),
+  };
+
+  // ── KjGridApi namespaces ──────────────────────────────────────────────────
+
+  const rows: KjRowsApi<TData> = {
+    all: () => (table().options.data ?? []) as readonly TData[],
+    displayed: () => table().getRowModel().rows,
+    count: () => (table().options.data?.length ?? 0),
+    filteredCount: () => table().getFilteredRowModel().rows.length,
+    displayedCount: () => table().getRowModel().rows.length,
+    get: (id) => table().getRow(id, /* searchAll */ true),
+  };
+
+  const selection: KjSelectionApi<TData> = {
+    get: () => state().rowSelection,
+    set: (model) => patch('rowSelection', model),
+    rows: () => table().getSelectedRowModel().rows,
+    ids: () => Object.keys(state().rowSelection).filter((id) => state().rowSelection[id]),
+    has: () => {
+      const sel = state().rowSelection;
+      for (const key in sel) if (sel[key]) return true;
+      return false;
+    },
+    select: (id, selected = true) =>
+      patch('rowSelection', (prev: RowSelectionState) => ({ ...prev, [id]: selected })),
+    deselect: (id) =>
+      patch('rowSelection', (prev: RowSelectionState) => {
+        const next = { ...prev };
+        delete next[id];
+        return next;
+      }),
+    toggle: (id) =>
+      patch('rowSelection', (prev: RowSelectionState) => ({ ...prev, [id]: !prev[id] })),
+    all: () => {
+      const next: RowSelectionState = {};
+      for (const r of table().getFilteredRowModel().rows) next[r.id] = true;
+      patch('rowSelection', next);
+    },
+    clear: () => patch('rowSelection', {}),
+  };
+
+  const sort: KjSortApi = {
+    get: () => state().sorting,
+    set: (s) => patch('sorting', s),
+    toggle: (columnId, multi = false) => {
+      const col = table().getColumn(columnId);
+      if (!col) return;
+      col.toggleSorting(undefined, multi);
+    },
+    clear: () => patch('sorting', []),
+  };
+
+  const globalFilter: KjGlobalFilterApi = {
+    get: () => state().globalFilter,
+    set: (value) => patch('globalFilter', value),
+    clear: () => patch('globalFilter', ''),
+  };
+
+  const filter: KjFilterApi = {
+    get: (id) => state().columnFilters.find((f) => f.id === id)?.value,
+    set: (id, value) =>
+      patch('columnFilters', (prev: ColumnFiltersState) => {
+        const without = prev.filter((f) => f.id !== id);
+        return value === undefined || value === null || value === ''
+          ? without
+          : [...without, { id, value }];
+      }),
+    clear: (id) =>
+      patch('columnFilters', (prev: ColumnFiltersState) => prev.filter((f) => f.id !== id)),
+    all: () => state().columnFilters,
+    setAll: (filters) => patch('columnFilters', filters),
+    global: globalFilter,
+    clearAll: () => setStateMerge({ columnFilters: [], globalFilter: '' }),
+
+    getModelFor: (id) => {
+      const v = state().columnFilters.find((f) => f.id === id)?.value;
+      return isKjFilterModel(v) ? v : undefined;
+    },
+    setModelFor: (id, model) =>
+      patch('columnFilters', (prev: ColumnFiltersState) => {
+        const without = prev.filter((f) => f.id !== id);
+        return model == null ? without : [...without, { id, value: model }];
+      }),
+    getModel: (): KjGridFilterModel => {
+      const out: Record<string, KjFilterModel> = {};
+      for (const entry of state().columnFilters) {
+        if (isKjFilterModel(entry.value)) out[entry.id] = entry.value;
+      }
+      return out;
+    },
+    setModel: (model) =>
+      patch('columnFilters', () => {
+        if (!model) return [];
+        return Object.entries(model).map(([id, value]) => ({ id, value }));
+      }),
+  };
+
+  const pagination: KjPaginationApi = {
+    get: () => state().pagination,
+    set: (p) => patch('pagination', p),
+    pageCount: () => table().getPageCount(),
+    setPageIndex: (pageIndex) =>
+      patch('pagination', (prev: PaginationState) => ({ ...prev, pageIndex: Math.max(0, pageIndex) })),
+    setPageSize: (pageSize) =>
+      patch('pagination', () => ({ pageIndex: 0, pageSize: Math.max(1, pageSize) })),
+    next: () =>
+      patch('pagination', (prev: PaginationState) => ({
+        ...prev,
+        pageIndex: Math.min(prev.pageIndex + 1, Math.max(0, table().getPageCount() - 1)),
+      })),
+    previous: () =>
+      patch('pagination', (prev: PaginationState) => ({
+        ...prev,
+        pageIndex: Math.max(0, prev.pageIndex - 1),
+      })),
+    first: () => patch('pagination', (prev: PaginationState) => ({ ...prev, pageIndex: 0 })),
+    last: () =>
+      patch('pagination', (prev: PaginationState) => ({
+        ...prev,
+        pageIndex: Math.max(0, table().getPageCount() - 1),
+      })),
+  };
+
+  const expansion: KjExpansionApi<TData> = {
+    get: () => state().expanded,
+    set: (e) => patch('expanded', e),
+    setRow: (id, expanded) =>
+      patch('expanded', (prev: ExpandedState) => {
+        if (prev === true) {
+          const next: Record<string, boolean> = {};
+          for (const r of table().getCoreRowModel().rows) next[r.id] = true;
+          next[id] = expanded;
+          return next;
+        }
+        return { ...prev, [id]: expanded };
+      }),
+    toggle: (id) =>
+      patch('expanded', (prev: ExpandedState) => {
+        if (prev === true) {
+          const next: Record<string, boolean> = {};
+          for (const r of table().getCoreRowModel().rows) next[r.id] = true;
+          next[id] = false;
+          return next;
+        }
+        return { ...prev, [id]: !prev[id] };
+      }),
+    expandAll: () => patch('expanded', true),
+    collapseAll: () => patch('expanded', {}),
+  };
+
+  const grouping: KjGroupingApi = {
+    get: () => state().grouping,
+    set: (g) => patch('grouping', g),
+    add: (id) =>
+      patch('grouping', (prev: GroupingState) => prev.includes(id) ? prev : [...prev, id]),
+    remove: (id) =>
+      patch('grouping', (prev: GroupingState) =>
+        id === undefined ? [] : prev.filter((c) => c !== id),
+      ),
+  };
+
+  const density: KjDensityApi = {
+    get: () => state().density,
+    set: (d: KjTableDensity) => patch('density', d),
+  };
+
+  const gridApi: KjGridApi<TData> = {
+    state,
+    table,
+    rows,
+    selection,
+    sort,
+    filter,
+    pagination,
+    expansion,
+    grouping,
+    density,
+    setState: setStateMerge,
+    resetState,
+  };
+
+  return { gridApi, columnApi };
+}

package/src/table/grid-api.spec.ts

@@ -0,0 +1,178 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { render } from '@testing-library/angular';
+import { describe, expect, it } from 'vitest';
+import { KjTable } from './table';
+import { kjColumn } from './column-helpers';
+
+interface User {
+  id: string;
+  name: string;
+  age: number;
+}
+
+@Component({
+  standalone: true,
+  imports: [KjTable],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `<table
+    [kjTable]="cols"
+    [kjTableData]="data()"
+    [kjGetRowId]="getId"
+    #t="kjTable"
+  ></table>`,
+})
+class Host {
+  protected readonly cols = [
+    kjColumn<User>({ accessorKey: 'name', header: 'Name' }),
+    kjColumn<User>({ accessorKey: 'age', header: 'Age', filterFn: 'equals' }),
+  ];
+  protected readonly data = signal<User[]>([
+    { id: '1', name: 'Alice', age: 30 },
+    { id: '2', name: 'Bob', age: 25 },
+    { id: '3', name: 'Carol', age: 40 },
+  ]);
+  protected readonly getId = (row: User) => row.id;
+}
+
+async function getDir() {
+  const r = await render(Host);
+  return r.fixture.debugElement.children[0].injector.get(KjTable<User>);
+}
+
+describe('KjGridApi (regrouped)', () => {
+  it('rows: count / displayedCount / filteredCount', async () => {
+    const { rows } = (await getDir()).gridApi;
+    expect(rows.count()).toBe(3);
+    expect(rows.displayedCount()).toBe(3);
+    expect(rows.filteredCount()).toBe(3);
+  });
+
+  it('selection: select/deselect/toggle/all/clear', async () => {
+    const { selection } = (await getDir()).gridApi;
+    expect(selection.has()).toBe(false);
+
+    selection.select('1');
+    expect(selection.has()).toBe(true);
+    expect(selection.ids()).toEqual(['1']);
+
+    selection.toggle('2');
+    expect([...selection.ids()].sort()).toEqual(['1', '2']);
+
+    selection.deselect('1');
+    expect(selection.ids()).toEqual(['2']);
+
+    selection.all();
+    expect([...selection.ids()].sort()).toEqual(['1', '2', '3']);
+
+    selection.clear();
+    expect(selection.has()).toBe(false);
+  });
+
+  it('sort: set / clear', async () => {
+    const { sort } = (await getDir()).gridApi;
+    sort.set([{ id: 'name', desc: true }]);
+    expect(sort.get()).toEqual([{ id: 'name', desc: true }]);
+    sort.clear();
+    expect(sort.get()).toEqual([]);
+  });
+
+  it('filter: column set/clear, global, clearAll', async () => {
+    const { filter, rows } = (await getDir()).gridApi;
+    filter.set('age', 30);
+    expect(filter.get('age')).toBe(30);
+    expect(rows.filteredCount()).toBe(1);
+    filter.clear('age');
+    expect(filter.get('age')).toBeUndefined();
+    expect(rows.filteredCount()).toBe(3);
+
+    filter.global.set('al');
+    expect(filter.global.get()).toBe('al');
+    filter.clearAll();
+    expect(filter.global.get()).toBe('');
+    expect(filter.all()).toEqual([]);
+  });
+
+  it('pagination: next/previous/first/last + setPageSize resets index', async () => {
+    const { pagination } = (await getDir()).gridApi;
+    pagination.setPageSize(1);
+    expect(pagination.pageCount()).toBe(3);
+    pagination.next();
+    expect(pagination.get().pageIndex).toBe(1);
+    pagination.last();
+    expect(pagination.get().pageIndex).toBe(2);
+    pagination.previous();
+    expect(pagination.get().pageIndex).toBe(1);
+    pagination.first();
+    expect(pagination.get().pageIndex).toBe(0);
+    pagination.setPageSize(2);
+    expect(pagination.get()).toEqual({ pageIndex: 0, pageSize: 2 });
+  });
+
+  it('density: get/set', async () => {
+    const { density } = (await getDir()).gridApi;
+    expect(density.get()).toBe('standard');
+    density.set('compact');
+    expect(density.get()).toBe('compact');
+  });
+
+  it('grouping: add / remove / set', async () => {
+    const { grouping } = (await getDir()).gridApi;
+    grouping.add('name');
+    expect(grouping.get()).toEqual(['name']);
+    grouping.add('name'); // no-op
+    expect(grouping.get()).toEqual(['name']);
+    grouping.remove('name');
+    expect(grouping.get()).toEqual([]);
+    grouping.set(['name', 'age']);
+    grouping.remove();
+    expect(grouping.get()).toEqual([]);
+  });
+});
+
+describe('KjColumnApi (regrouped)', () => {
+  it('visibility: setVisible / setManyVisible / isVisible', async () => {
+    const { visibility } = (await getDir()).columnApi;
+    expect(visibility.isVisible('name')).toBe(true);
+    visibility.setVisible('name', false);
+    expect(visibility.isVisible('name')).toBe(false);
+    visibility.setManyVisible(['name', 'age'], true);
+    expect(visibility.isVisible('name')).toBe(true);
+    expect(visibility.isVisible('age')).toBe(true);
+  });
+
+  it('pinning: pin / of', async () => {
+    const { pinning } = (await getDir()).columnApi;
+    expect(pinning.of('name')).toBeNull();
+    pinning.pin('name', 'left');
+    expect(pinning.of('name')).toBe('left');
+    pinning.pin('name', 'right');
+    expect(pinning.of('name')).toBe('right');
+    pinning.pin('name', null);
+    expect(pinning.of('name')).toBeNull();
+  });
+
+  it('order: move', async () => {
+    const { order } = (await getDir()).columnApi;
+    order.move('age', 0);
+    expect(order.get()[0]).toBe('age');
+  });
+
+  it('grouping (per-column): is / set', async () => {
+    const { grouping } = (await getDir()).columnApi;
+    grouping.set('name', true);
+    expect(grouping.is('name')).toBe(true);
+    grouping.set('name', false);
+    expect(grouping.is('name')).toBe(false);
+  });
+
+  it('reset() clears every column-level slice', async () => {
+    const colApi = (await getDir()).columnApi;
+    colApi.pinning.pin('name', 'left');
+    colApi.visibility.setVisible('age', false);
+    colApi.grouping.set('name', true);
+    colApi.reset();
+    expect(colApi.pinning.of('name')).toBeNull();
+    expect(colApi.visibility.isVisible('age')).toBe(true);
+    expect(colApi.grouping.is('name')).toBe(false);
+  });
+});