@kouji-ui/core 0.0.3 → 0.1.1

package/src/table/column-helpers.ts

@@ -0,0 +1,68 @@
+import type { ColumnDef, FilterFn, RowData } from '@tanstack/angular-table';
+import {
+  kjDateFilterFn,
+  kjNumberFilterFn,
+  kjSetFilterFn,
+  kjTextFilterFn,
+} from './filter-fns';
+import type { KjColumnDef, KjColumnMeta, KjColumnType } from './table.types';
+
+const KJ_KEYS = [
+  'kjType', 'kjEditable', 'kjFilterable', 'kjPin', 'kjGroup', 'kjAgg',
+  'kjEditor', 'kjFilterUi', 'kjSelectOptions', 'kjExportable', 'kjPersist',
+] as const;
+
+/** Auto-wired matcher per `kjType`. Picked up only when the column def
+ *  doesn't already supply its own `filterFn`. */
+const DEFAULT_FILTER_FNS: Readonly<Record<KjColumnType, FilterFn<unknown>>> = {
+  text:    kjTextFilterFn   as unknown as FilterFn<unknown>,
+  number:  kjNumberFilterFn as unknown as FilterFn<unknown>,
+  date:    kjDateFilterFn   as unknown as FilterFn<unknown>,
+  select:  kjSetFilterFn    as unknown as FilterFn<unknown>,
+  boolean: kjSetFilterFn    as unknown as FilterFn<unknown>,
+};
+
+/** Strip leading 'kj' and lowercase first char. */
+function unprefix(k: string): keyof KjColumnMeta {
+  return (k.slice(2, 3).toLowerCase() + k.slice(3)) as keyof KjColumnMeta;
+}
+
+/**
+ * Define a column for `<kj-data-table>`. Pass-through for every TanStack
+ * `ColumnDef` field; kj-specific top-level knobs (`kjType`, `kjEditable`,
+ * `kjPin`, …) are hoisted into `meta.kj` for the wrapper to read.
+ */
+export function kjColumn<TData extends RowData>(def: KjColumnDef<TData>): ColumnDef<TData> {
+  const kjMeta: Partial<KjColumnMeta<TData>> = {};
+  const rest: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(def)) {
+    if ((KJ_KEYS as readonly string[]).includes(k)) {
+      if (v !== undefined) kjMeta[unprefix(k)] = v as never;
+    } else {
+      rest[k] = v;
+    }
+  }
+  const existingMeta = (rest['meta'] ?? {}) as Record<string, unknown>;
+  const meta = Object.keys(kjMeta).length === 0
+    ? existingMeta
+    : { ...existingMeta, kj: kjMeta };
+
+  // Auto-wire `filterFn` from `kjType` so columns built with `kjColumn({ ... })`
+  // actually understand the structured `KjFilterModel` the built-in filter UIs
+  // write. User-supplied `filterFn` always wins.
+  if (rest['filterFn'] === undefined && kjMeta.type) {
+    const fn = DEFAULT_FILTER_FNS[kjMeta.type as KjColumnType];
+    if (fn) rest['filterFn'] = fn as unknown as FilterFn<TData>;
+  }
+
+  return { ...rest, meta } as unknown as ColumnDef<TData>;
+}
+
+/** Define a column group (header grouping). Children are `kjColumn()` defs. */
+export function kjColumnGroup<TData extends RowData>(def: {
+  id?: string;
+  header: ColumnDef<TData>['header'];
+  columns: ColumnDef<TData>[];
+}): ColumnDef<TData> {
+  return def as unknown as ColumnDef<TData>;
+}

package/src/table/filter-fns.ts

@@ -0,0 +1,230 @@
+import type { Row } from '@tanstack/angular-table';
+import {
+  isKjFilterModel,
+  type KjDateFilterModel,
+  type KjFilterModel,
+  type KjMultiConditionFilterModel,
+  type KjNumberFilterModel,
+  type KjSetFilterModel,
+  type KjTextFilterModel,
+} from './filter-models';
+
+/**
+ * TanStack `filterFn` for {@link KjTextFilterModel}. Accepts the model as
+ * the filter value and dispatches on `model.type`. Tolerates a bare
+ * string (legacy "contains" raw value) so users migrating filters one at
+ * a time don't have to flip every column simultaneously.
+ *
+ * Usage:
+ * ```ts
+ * kjColumn<User>({ accessorKey: 'name', filterFn: kjTextFilterFn })
+ * ```
+ */
+export function kjTextFilterFn<TData>(
+  row: Row<TData>,
+  columnId: string,
+  filterValue: unknown,
+): boolean {
+  if (filterValue == null || filterValue === '') return true;
+
+  // Legacy raw-string compatibility — treated as `contains`.
+  if (typeof filterValue === 'string') {
+    return contains(read(row, columnId), filterValue, /* caseSensitive */ false);
+  }
+
+  if (!isKjFilterModel(filterValue) || filterValue.filterType !== 'text') return true;
+  const model = filterValue as KjTextFilterModel;
+  const cell  = read(row, columnId);
+  const cs    = model.caseSensitive === true;
+
+  switch (model.type) {
+    case 'blank':    return cell == null || cell === '';
+    case 'notBlank': return cell != null && cell !== '';
+    case 'equals':       return text(cell, cs) === text(model.filter ?? '', cs);
+    case 'notEquals':    return text(cell, cs) !== text(model.filter ?? '', cs);
+    case 'contains':     return contains(cell, model.filter ?? '', cs);
+    case 'notContains':  return !contains(cell, model.filter ?? '', cs);
+    case 'startsWith':   return text(cell, cs).startsWith(text(model.filter ?? '', cs));
+    case 'endsWith':     return text(cell, cs).endsWith(text(model.filter ?? '', cs));
+  }
+}
+
+/**
+ * TanStack `filterFn` for {@link KjNumberFilterModel}. Tolerates a bare
+ * `[min, max]` tuple as legacy raw value (treated as `inRange`).
+ */
+export function kjNumberFilterFn<TData>(
+  row: Row<TData>,
+  columnId: string,
+  filterValue: unknown,
+): boolean {
+  if (filterValue == null) return true;
+
+  // Legacy `[min, max]` tuple → inRange.
+  if (Array.isArray(filterValue)) {
+    const [min, max] = filterValue as [number | undefined, number | undefined];
+    return inNumberRange(Number(read(row, columnId)), min, max);
+  }
+
+  if (!isKjFilterModel(filterValue) || filterValue.filterType !== 'number') return true;
+  const model = filterValue as KjNumberFilterModel;
+  const cell  = Number(read(row, columnId));
+
+  if (model.type === 'blank')    return Number.isNaN(cell);
+  if (model.type === 'notBlank') return !Number.isNaN(cell);
+
+  // `inRange` is the one operator where a missing `filter` is still
+  // meaningful — it just leaves the lower bound open. Every other operator
+  // needs an explicit `filter`, so we treat its absence as "no filter".
+  if (model.type === 'inRange') {
+    if (model.filter == null && model.filterTo == null) return true;
+    return inNumberRange(cell, model.filter, model.filterTo);
+  }
+
+  const value = model.filter;
+  if (value == null) return true;
+
+  switch (model.type) {
+    case 'equals':              return cell === value;
+    case 'notEquals':           return cell !== value;
+    case 'greaterThan':         return cell  >  value;
+    case 'greaterThanOrEqual':  return cell  >= value;
+    case 'lessThan':            return cell  <  value;
+    case 'lessThanOrEqual':     return cell  <= value;
+  }
+  return true;
+}
+
+/**
+ * TanStack `filterFn` for {@link KjDateFilterModel}. Compares ISO date
+ * strings as calendar dates (no time component, no TZ math). Tolerates a
+ * `[from, to]` tuple of ISO strings as legacy raw value.
+ */
+export function kjDateFilterFn<TData>(
+  row: Row<TData>,
+  columnId: string,
+  filterValue: unknown,
+): boolean {
+  if (filterValue == null) return true;
+
+  if (Array.isArray(filterValue)) {
+    const [from, to] = filterValue as [string | undefined, string | undefined];
+    return inIsoRange(isoOf(read(row, columnId)), from, to);
+  }
+
+  if (!isKjFilterModel(filterValue) || filterValue.filterType !== 'date') return true;
+  const model = filterValue as KjDateFilterModel;
+  const cell  = isoOf(read(row, columnId));
+
+  if (model.type === 'blank')    return !cell;
+  if (model.type === 'notBlank') return !!cell;
+  if (!cell) return false;
+
+  switch (model.type) {
+    case 'equals':       return cell === model.dateFrom;
+    case 'notEquals':    return cell !== model.dateFrom;
+    case 'greaterThan':  return !!model.dateFrom && cell  > model.dateFrom;
+    case 'lessThan':     return !!model.dateFrom && cell  < model.dateFrom;
+    case 'inRange':      return inIsoRange(cell, model.dateFrom, model.dateTo);
+  }
+}
+
+/**
+ * TanStack `filterFn` for {@link KjSetFilterModel}. The row passes if the
+ * cell's stringified value matches any selected entry. Tolerates a bare
+ * (non-array) value as legacy raw equality.
+ */
+export function kjSetFilterFn<TData>(
+  row: Row<TData>,
+  columnId: string,
+  filterValue: unknown,
+): boolean {
+  if (filterValue == null) return true;
+
+  if (!isKjFilterModel(filterValue)) {
+    return Object.is(read(row, columnId), filterValue);
+  }
+
+  if (filterValue.filterType !== 'set') return true;
+  const model = filterValue as KjSetFilterModel;
+  if (model.values.length === 0) return true;
+  const cell = read(row, columnId);
+  return model.values.some((v) => Object.is(v, cell));
+}
+
+/**
+ * TanStack `filterFn` for {@link KjMultiConditionFilterModel}.
+ * Recursively delegates each condition to the matching helper based on
+ * `condition.filterType`.
+ */
+export function kjMultiFilterFn<TData>(
+  row: Row<TData>,
+  columnId: string,
+  filterValue: unknown,
+): boolean {
+  if (!isKjFilterModel(filterValue) || filterValue.filterType !== 'multi') return true;
+  const model = filterValue as KjMultiConditionFilterModel;
+  const reduce = model.operator === 'AND'
+    ? model.conditions.every.bind(model.conditions)
+    : model.conditions.some.bind(model.conditions);
+  return reduce((c) => evaluate(row, columnId, c));
+}
+
+/** Dispatch a single model against the correct typed helper. */
+function evaluate<TData>(
+  row: Row<TData>,
+  columnId: string,
+  model: KjFilterModel,
+): boolean {
+  switch (model.filterType) {
+    case 'text':   return kjTextFilterFn(row, columnId, model);
+    case 'number': return kjNumberFilterFn(row, columnId, model);
+    case 'date':   return kjDateFilterFn(row, columnId, model);
+    case 'set':    return kjSetFilterFn(row, columnId, model);
+    case 'multi':  return kjMultiFilterFn(row, columnId, model);
+  }
+}
+
+// ── primitives ─────────────────────────────────────────────────────────────
+
+function read<TData>(row: Row<TData>, columnId: string): unknown {
+  return row.getValue(columnId);
+}
+function text(value: unknown, caseSensitive: boolean): string {
+  const s = value == null ? '' : String(value);
+  return caseSensitive ? s : s.toLowerCase();
+}
+function contains(cell: unknown, needle: string, caseSensitive: boolean): boolean {
+  return text(cell, caseSensitive).includes(text(needle, caseSensitive));
+}
+function inNumberRange(
+  cell: number,
+  min: number | undefined,
+  max: number | undefined,
+): boolean {
+  if (Number.isNaN(cell)) return false;
+  if (min !== undefined && cell < min) return false;
+  if (max !== undefined && cell > max) return false;
+  return true;
+}
+function inIsoRange(
+  cell: string | undefined,
+  from: string | undefined,
+  to: string | undefined,
+): boolean {
+  if (!cell) return false;
+  if (from && cell < from) return false;
+  if (to   && cell > to)   return false;
+  return true;
+}
+function isoOf(value: unknown): string | undefined {
+  if (!value) return undefined;
+  if (value instanceof Date) {
+    const y = value.getFullYear();
+    const m = String(value.getMonth() + 1).padStart(2, '0');
+    const d = String(value.getDate()).padStart(2, '0');
+    return `${y}-${m}-${d}`;
+  }
+  if (typeof value === 'string') return value.slice(0, 10);
+  return undefined;
+}

package/src/table/filter-models.spec.ts

@@ -0,0 +1,240 @@
+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';
+import {
+  kjTextFilterFn,
+  kjNumberFilterFn,
+  kjDateFilterFn,
+  kjSetFilterFn,
+  kjMultiFilterFn,
+} from './filter-fns';
+import type {
+  KjDateFilterModel,
+  KjMultiConditionFilterModel,
+  KjNumberFilterModel,
+  KjSetFilterModel,
+  KjTextFilterModel,
+} from './filter-models';
+
+interface Row {
+  id: string;
+  name: string;
+  age: number;
+  joined: string;
+  role: string;
+}
+
+@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<Row>({ accessorKey: 'name', header: 'Name', filterFn: kjTextFilterFn }),
+    kjColumn<Row>({ accessorKey: 'age', header: 'Age', filterFn: kjNumberFilterFn }),
+    kjColumn<Row>({ accessorKey: 'joined', header: 'Joined', filterFn: kjDateFilterFn }),
+    kjColumn<Row>({ accessorKey: 'role', header: 'Role', filterFn: kjSetFilterFn }),
+  ];
+  protected readonly data = signal<Row[]>([
+    { id: '1', name: 'Alice', age: 30, joined: '2024-01-15', role: 'admin' },
+    { id: '2', name: 'Bob', age: 25, joined: '2024-06-01', role: 'editor' },
+    { id: '3', name: 'Carol', age: 40, joined: '2025-02-10', role: 'viewer' },
+    { id: '4', name: 'Dave', age: 35, joined: '2025-08-22', role: 'editor' },
+  ]);
+  protected readonly getId = (row: Row) => row.id;
+}
+
+async function getDir() {
+  const r = await render(Host);
+  return r.fixture.debugElement.children[0].injector.get(KjTable<Row>);
+}
+
+describe('text filter model', () => {
+  it('contains', async () => {
+    const { gridApi } = await getDir();
+    gridApi.filter.set('name', {
+      filterType: 'text',
+      type: 'contains',
+      filter: 'al',
+    } as KjTextFilterModel);
+    expect(gridApi.rows.filteredCount()).toBe(1); // Alice
+  });
+
+  it('startsWith / endsWith', async () => {
+    const { gridApi } = await getDir();
+    gridApi.filter.set('name', { filterType: 'text', type: 'startsWith', filter: 'B' });
+    expect(gridApi.rows.filteredCount()).toBe(1);
+    gridApi.filter.set('name', { filterType: 'text', type: 'endsWith', filter: 'l' });
+    expect(gridApi.rows.filteredCount()).toBe(1); // Carol
+  });
+
+  it('blank / notBlank', async () => {
+    const { gridApi } = await getDir();
+    gridApi.filter.set('name', { filterType: 'text', type: 'notBlank' });
+    expect(gridApi.rows.filteredCount()).toBe(4);
+    gridApi.filter.set('name', { filterType: 'text', type: 'blank' });
+    expect(gridApi.rows.filteredCount()).toBe(0);
+  });
+});
+
+describe('number filter model', () => {
+  it('equals / notEquals', async () => {
+    const { gridApi } = await getDir();
+    gridApi.filter.set('age', { filterType: 'number', type: 'equals', filter: 30 });
+    expect(gridApi.rows.filteredCount()).toBe(1);
+    gridApi.filter.set('age', { filterType: 'number', type: 'notEquals', filter: 30 });
+    expect(gridApi.rows.filteredCount()).toBe(3);
+  });
+
+  it('inRange', async () => {
+    const { gridApi } = await getDir();
+    const model: KjNumberFilterModel = {
+      filterType: 'number',
+      type: 'inRange',
+      filter: 28,
+      filterTo: 36,
+    };
+    gridApi.filter.set('age', model);
+    expect(gridApi.rows.filteredCount()).toBe(2); // 30, 35
+  });
+
+  it('greaterThan / lessThanOrEqual', async () => {
+    const { gridApi } = await getDir();
+    gridApi.filter.set('age', { filterType: 'number', type: 'greaterThan', filter: 30 });
+    expect(gridApi.rows.filteredCount()).toBe(2);
+    gridApi.filter.set('age', { filterType: 'number', type: 'lessThanOrEqual', filter: 30 });
+    expect(gridApi.rows.filteredCount()).toBe(2);
+  });
+});
+
+describe('date filter model', () => {
+  it('inRange', async () => {
+    const { gridApi } = await getDir();
+    const model: KjDateFilterModel = {
+      filterType: 'date',
+      type: 'inRange',
+      dateFrom: '2024-01-01',
+      dateTo: '2024-12-31',
+    };
+    gridApi.filter.set('joined', model);
+    expect(gridApi.rows.filteredCount()).toBe(2);
+  });
+
+  it('greaterThan / lessThan', async () => {
+    const { gridApi } = await getDir();
+    gridApi.filter.set('joined', {
+      filterType: 'date',
+      type: 'greaterThan',
+      dateFrom: '2025-01-01',
+    });
+    expect(gridApi.rows.filteredCount()).toBe(2);
+    gridApi.filter.set('joined', { filterType: 'date', type: 'lessThan', dateFrom: '2024-06-01' });
+    expect(gridApi.rows.filteredCount()).toBe(1);
+  });
+});
+
+describe('set filter model', () => {
+  it('matches any of the listed values', async () => {
+    const { gridApi } = await getDir();
+    const model: KjSetFilterModel = { filterType: 'set', values: ['admin', 'editor'] };
+    gridApi.filter.set('role', model);
+    expect(gridApi.rows.filteredCount()).toBe(3);
+  });
+
+  it('empty values = no filter', async () => {
+    const { gridApi } = await getDir();
+    gridApi.filter.set('role', { filterType: 'set', values: [] });
+    expect(gridApi.rows.filteredCount()).toBe(4);
+  });
+});
+
+describe('multi-condition filter (AND/OR)', () => {
+  it('AND', async () => {
+    const { gridApi } = await getDir();
+    const model: KjMultiConditionFilterModel = {
+      filterType: 'multi',
+      operator: 'AND',
+      conditions: [
+        { filterType: 'number', type: 'greaterThan', filter: 28 },
+        { filterType: 'number', type: 'lessThan', filter: 36 },
+      ],
+    };
+    // Apply against age column — kjMultiFilterFn dispatches by inner filterType.
+    // Use direct fn invocation here because TanStack columns only have one filterFn at a time.
+    const passed = gridApi.rows
+      .all()
+      .filter((r) =>
+        kjMultiFilterFn(
+          { getValue: () => r.age } as unknown as Parameters<typeof kjMultiFilterFn>[0],
+          'age',
+          model,
+        ),
+      );
+    expect(passed.length).toBe(2);
+  });
+
+  it('OR', async () => {
+    const { gridApi } = await getDir();
+    const model: KjMultiConditionFilterModel = {
+      filterType: 'multi',
+      operator: 'OR',
+      conditions: [
+        { filterType: 'number', type: 'lessThan', filter: 26 },
+        { filterType: 'number', type: 'greaterThan', filter: 38 },
+      ],
+    };
+    const passed = gridApi.rows
+      .all()
+      .filter((r) =>
+        kjMultiFilterFn(
+          { getValue: () => r.age } as unknown as Parameters<typeof kjMultiFilterFn>[0],
+          'age',
+          model,
+        ),
+      );
+    expect(passed.length).toBe(2);
+  });
+});
+
+describe('gridApi.filter.getModel / setModel', () => {
+  it('getModel returns structured models keyed by column id', async () => {
+    const { gridApi } = await getDir();
+    gridApi.filter.set('name', { filterType: 'text', type: 'contains', filter: 'al' });
+    gridApi.filter.set('age', { filterType: 'number', type: 'equals', filter: 30 });
+    const model = gridApi.filter.getModel();
+    expect(model['name']).toEqual({ filterType: 'text', type: 'contains', filter: 'al' });
+    expect(model['age']).toEqual({ filterType: 'number', type: 'equals', filter: 30 });
+  });
+
+  it('getModel omits raw (non-model) entries', async () => {
+    const { gridApi } = await getDir();
+    gridApi.filter.set('name', 'alice'); // legacy raw value
+    expect(gridApi.filter.getModel()).toEqual({});
+  });
+
+  it('setModel replaces every column filter at once', async () => {
+    const { gridApi } = await getDir();
+    gridApi.filter.set('age', { filterType: 'number', type: 'equals', filter: 30 });
+    gridApi.filter.setModel({
+      role: { filterType: 'set', values: ['editor'] },
+    });
+    expect(gridApi.filter.getModelFor('age')).toBeUndefined();
+    expect(gridApi.filter.getModelFor('role')).toEqual({ filterType: 'set', values: ['editor'] });
+  });
+
+  it('setModel(null) clears everything', async () => {
+    const { gridApi } = await getDir();
+    gridApi.filter.set('age', { filterType: 'number', type: 'equals', filter: 30 });
+    gridApi.filter.setModel(null);
+    expect(gridApi.filter.all()).toEqual([]);
+  });
+});

package/src/table/filter-models.ts

@@ -0,0 +1,124 @@
+/**
+ * Structured filter models — a near-direct adaptation of AG-Grid's
+ * `FilterModel` shape. Each built-in filter writes one of these models
+ * to `column.setFilterValue(...)` instead of a raw value. The structured
+ * shape buys two things:
+ *
+ * 1. **Server-side rendering.** `gridApi.filter.getModel()` returns a
+ *    `KjGridFilterModel` (`Record<columnId, KjFilterModel>`) that
+ *    serialises cleanly into a JSON payload your backend can translate
+ *    to SQL/Mongo/etc. without re-parsing free-form values. Pair with
+ *    `kjTableResource({ loader })` to fan changes back to the server.
+ *
+ * 2. **Cross-filter introspection.** Code that needs to "what does the
+ *    user currently have selected on column X" can discriminate on
+ *    `filterType` and `type` instead of guessing from a `string | unknown`
+ *    value.
+ *
+ * The companion `filter-fns` helpers (`kjTextFilterFn` etc.) implement
+ * client-side filtering against these models so client-mode tables work
+ * out of the box — point `kjColumn({ filterFn: kjTextFilterFn })` at one
+ * and TanStack will dispatch row matching for you.
+ */
+
+/** Comparison operators for {@link KjTextFilterModel}. */
+export type KjTextFilterType =
+  | 'contains'
+  | 'notContains'
+  | 'equals'
+  | 'notEquals'
+  | 'startsWith'
+  | 'endsWith'
+  | 'blank'
+  | 'notBlank';
+
+export interface KjTextFilterModel {
+  readonly filterType: 'text';
+  readonly type: KjTextFilterType;
+  /** Match string. Omitted for `blank` / `notBlank`. */
+  readonly filter?: string;
+  /** Case-insensitive matching. Defaults to `true`. */
+  readonly caseSensitive?: boolean;
+}
+
+/** Comparison operators for {@link KjNumberFilterModel}. */
+export type KjNumberFilterType =
+  | 'equals'
+  | 'notEquals'
+  | 'greaterThan'
+  | 'greaterThanOrEqual'
+  | 'lessThan'
+  | 'lessThanOrEqual'
+  | 'inRange'
+  | 'blank'
+  | 'notBlank';
+
+export interface KjNumberFilterModel {
+  readonly filterType: 'number';
+  readonly type: KjNumberFilterType;
+  /** Primary number. Omitted for `blank` / `notBlank`. */
+  readonly filter?: number;
+  /** Range upper bound — used by `inRange`. */
+  readonly filterTo?: number;
+}
+
+/** Comparison operators for {@link KjDateFilterModel}. */
+export type KjDateFilterType =
+  | 'equals'
+  | 'notEquals'
+  | 'greaterThan'      // after
+  | 'lessThan'         // before
+  | 'inRange'
+  | 'blank'
+  | 'notBlank';
+
+export interface KjDateFilterModel {
+  readonly filterType: 'date';
+  readonly type: KjDateFilterType;
+  /** Primary date — ISO `YYYY-MM-DD`. */
+  readonly dateFrom?: string;
+  /** Range upper bound — used by `inRange`. */
+  readonly dateTo?: string;
+}
+
+/**
+ * Set / multi-select filter — the row passes if the cell value is in
+ * `values`. An empty `values` array means "no filter" (cleared); pair
+ * with `setFilterValue(undefined)` for the cleared state by preference.
+ */
+export interface KjSetFilterModel {
+  readonly filterType: 'set';
+  readonly values: readonly unknown[];
+}
+
+/** Compound filter — combine two conditions with AND / OR. */
+export interface KjMultiConditionFilterModel<TModel extends KjFilterModel = KjFilterModel> {
+  readonly filterType: 'multi';
+  readonly operator: 'AND' | 'OR';
+  readonly conditions: readonly TModel[];
+}
+
+/** Discriminated union of every built-in filter model. */
+export type KjFilterModel =
+  | KjTextFilterModel
+  | KjNumberFilterModel
+  | KjDateFilterModel
+  | KjSetFilterModel
+  | KjMultiConditionFilterModel;
+
+/**
+ * Bulk filter snapshot — keyed by column id. Shape mirrors AG-Grid's
+ * `api.getFilterModel()` return so SSR loaders that already understand
+ * AG-Grid payloads can consume it as-is.
+ */
+export type KjGridFilterModel = Record<string, KjFilterModel>;
+
+/** Narrowing helper. */
+export function isKjFilterModel(value: unknown): value is KjFilterModel {
+  return (
+    !!value &&
+    typeof value === 'object' &&
+    'filterType' in (value as object) &&
+    typeof (value as { filterType: unknown }).filterType === 'string'
+  );
+}