@kouji-ui/components 0.1.1

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

@@ -0,0 +1,277 @@
+import { TestBed } from '@angular/core/testing';
+import { By } from '@angular/platform-browser';
+import type { Column, Table } from '@tanstack/angular-table';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { KjSelect } from '@kouji-ui/core';
+import { KjSelectComponent } from '../../select/select';
+import { KjDatePickerComponent } from '../../date-picker/date-picker';
+import { KjNumberInputComponent } from '../../number-input/number-input';
+import {
+  KJ_FILTER_CONTEXT,
+  type KjFilterContext,
+} from './text-filter';
+import { KjTextFilter } from './text-filter';
+import { KjNumberFilter } from './number-filter';
+import { KjDateFilter } from './date-filter';
+import { KjSelectFilter } from './select-filter';
+
+interface StubColumn {
+  id: string;
+  columnDef: { header: string };
+  getFilterValue: ReturnType<typeof vi.fn>;
+  setFilterValue: ReturnType<typeof vi.fn>;
+}
+
+function makeColumn(opts: {
+  header?: string;
+  id?: string;
+  initial?: unknown;
+} = {}): StubColumn {
+  return {
+    id: opts.id ?? 'col',
+    columnDef: { header: opts.header ?? 'Name' },
+    getFilterValue: vi.fn().mockReturnValue(opts.initial),
+    setFilterValue: vi.fn(),
+  };
+}
+
+function toLocalIso(d: Date | null | undefined): string | null {
+  if (!d) return null;
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, '0');
+  const day = String(d.getDate()).padStart(2, '0');
+  return `${y}-${m}-${day}`;
+}
+
+function provideCtx(column: StubColumn): { provide: typeof KJ_FILTER_CONTEXT; useValue: KjFilterContext } {
+  const ctx: KjFilterContext = {
+    column: column as unknown as Column<unknown, unknown>,
+    table: {} as Table<unknown>,
+  };
+  return { provide: KJ_FILTER_CONTEXT, useValue: ctx };
+}
+
+// ---------- KjTextFilter ----------
+
+describe('KjTextFilter', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('seeds the input from column.getFilterValue() on init', () => {
+    const column = makeColumn({ header: 'Name', initial: 'alice' });
+    TestBed.configureTestingModule({
+      imports: [KjTextFilter],
+      providers: [provideCtx(column)],
+    });
+    const fixture = TestBed.createComponent(KjTextFilter);
+    fixture.detectChanges();
+    expect(column.getFilterValue).toHaveBeenCalled();
+    const input = fixture.nativeElement.querySelector('input') as HTMLInputElement;
+    expect(input.value).toBe('alice');
+    // Accessible name comes from the wrapping <label>'s visually-hidden caption.
+    const labelText = (fixture.nativeElement.querySelector('label')?.textContent ?? '').trim();
+    expect(labelText).toBe('Filter by Name');
+  });
+
+  it('typing calls column.setFilterValue after the 300ms debounce', () => {
+    const column = makeColumn({ header: 'Name' });
+    TestBed.configureTestingModule({
+      imports: [KjTextFilter],
+      providers: [provideCtx(column)],
+    });
+    const fixture = TestBed.createComponent(KjTextFilter);
+    fixture.detectChanges();
+    const input = fixture.nativeElement.querySelector('input') as HTMLInputElement;
+
+    input.value = 'bob';
+    input.dispatchEvent(new Event('input', { bubbles: true }));
+    // Before debounce elapses, no write.
+    expect(column.setFilterValue).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(300);
+    expect(column.setFilterValue).toHaveBeenCalledTimes(1);
+    expect(column.setFilterValue).toHaveBeenCalledWith({
+      filterType: 'text',
+      type: 'contains',
+      filter: 'bob',
+    });
+  });
+});
+
+// ---------- KjNumberFilter ----------
+
+describe('KjNumberFilter', () => {
+  it('seeds the inRange operator + both inputs from a legacy [min, max] tuple', () => {
+    const column = makeColumn({ header: 'Age', initial: [18, 65] });
+    TestBed.configureTestingModule({
+      imports: [KjNumberFilter],
+      providers: [provideCtx(column)],
+    });
+    const fixture = TestBed.createComponent(KjNumberFilter);
+    fixture.detectChanges();
+    const pickers = fixture.debugElement
+      .queryAll(By.directive(KjNumberInputComponent))
+      .map((d) => d.componentInstance as KjNumberInputComponent);
+    expect(pickers.length).toBe(2);
+    expect(pickers[0].kjValue()).toBe(18);
+    expect(pickers[1].kjValue()).toBe(65);
+    expect(pickers[0].kjAriaLabel()).toBe('Filter Age minimum');
+    expect(pickers[1].kjAriaLabel()).toBe('Filter Age maximum');
+  });
+
+  it('default operator is `equals` and renders a single primary input', () => {
+    const column = makeColumn({ header: 'Age' });
+    TestBed.configureTestingModule({
+      imports: [KjNumberFilter],
+      providers: [provideCtx(column)],
+    });
+    const fixture = TestBed.createComponent(KjNumberFilter);
+    fixture.detectChanges();
+    const pickers = fixture.debugElement.queryAll(By.directive(KjNumberInputComponent));
+    expect(pickers.length).toBe(1);
+    (pickers[0].componentInstance as KjNumberInputComponent).kjValue.set(21);
+    expect(column.setFilterValue).toHaveBeenLastCalledWith({
+      filterType: 'number', type: 'equals', filter: 21,
+    });
+  });
+
+  it('switching operator to `inRange` via the native <select> reveals the second input', () => {
+    const column = makeColumn({ header: 'Age' });
+    TestBed.configureTestingModule({
+      imports: [KjNumberFilter],
+      providers: [provideCtx(column)],
+    });
+    const fixture = TestBed.createComponent(KjNumberFilter);
+    fixture.detectChanges();
+    const select = fixture.debugElement.query(By.directive(KjSelectComponent));
+    expect(select).toBeTruthy();
+    select.triggerEventHandler('valueChange', 'inRange');
+    fixture.detectChanges();
+    const pickers = fixture.debugElement.queryAll(By.directive(KjNumberInputComponent));
+    expect(pickers.length).toBe(2);
+    (pickers[0].componentInstance as KjNumberInputComponent).kjValue.set(10);
+    (pickers[1].componentInstance as KjNumberInputComponent).kjValue.set(20);
+    expect(column.setFilterValue).toHaveBeenLastCalledWith({
+      filterType: 'number', type: 'inRange', filter: 10, filterTo: 20,
+    });
+  });
+
+  it('`blank` operator hides the inputs and writes a no-value model', () => {
+    const column = makeColumn({ header: 'Age' });
+    TestBed.configureTestingModule({
+      imports: [KjNumberFilter],
+      providers: [provideCtx(column)],
+    });
+    const fixture = TestBed.createComponent(KjNumberFilter);
+    fixture.detectChanges();
+    const select = fixture.debugElement.query(By.directive(KjSelectComponent));
+    select.triggerEventHandler('valueChange', 'blank');
+    fixture.detectChanges();
+    const pickers = fixture.debugElement.queryAll(By.directive(KjNumberInputComponent));
+    expect(pickers.length).toBe(0);
+    expect(column.setFilterValue).toHaveBeenLastCalledWith({
+      filterType: 'number', type: 'blank',
+    });
+  });
+});
+
+// ---------- KjDateFilter ----------
+
+describe('KjDateFilter', () => {
+  it('seeds both from/to inputs from an existing [from, to] tuple', () => {
+    const column = makeColumn({
+      header: 'Joined',
+      initial: ['2024-01-01', '2024-12-31'],
+    });
+    TestBed.configureTestingModule({
+      imports: [KjDateFilter],
+      providers: [provideCtx(column)],
+    });
+    const fixture = TestBed.createComponent(KjDateFilter);
+    fixture.detectChanges();
+    const [fromPicker, toPicker] = fixture.debugElement
+      .queryAll(By.directive(KjDatePickerComponent))
+      .map((d) => d.componentInstance as KjDatePickerComponent);
+    expect(toLocalIso(fromPicker.kjValue())).toBe('2024-01-01');
+    expect(toLocalIso(toPicker.kjValue())).toBe('2024-12-31');
+    const captions = Array.from(
+      fixture.nativeElement.querySelectorAll('.kj-date-filter__caption'),
+    ) as HTMLElement[];
+    expect((captions[0].textContent ?? '').trim()).toBe('Filter by Joined from date');
+    expect((captions[1].textContent ?? '').trim()).toBe('Filter by Joined to date');
+  });
+
+  it('typing in from/to writes a [from, to] tuple via setFilterValue', () => {
+    const column = makeColumn({ header: 'Joined' });
+    TestBed.configureTestingModule({
+      imports: [KjDateFilter],
+      providers: [provideCtx(column)],
+    });
+    const fixture = TestBed.createComponent(KjDateFilter);
+    fixture.detectChanges();
+    const [fromPicker, toPicker] = fixture.debugElement
+      .queryAll(By.directive(KjDatePickerComponent))
+      .map((d) => d.componentInstance as KjDatePickerComponent);
+
+    fromPicker.kjValue.set(new Date(2025, 2, 1));
+    expect(column.setFilterValue).toHaveBeenLastCalledWith({
+      filterType: 'date', type: 'inRange', dateFrom: '2025-03-01', dateTo: undefined,
+    });
+
+    toPicker.kjValue.set(new Date(2025, 3, 1));
+    expect(column.setFilterValue).toHaveBeenLastCalledWith({
+      filterType: 'date', type: 'inRange', dateFrom: '2025-03-01', dateTo: '2025-04-01',
+    });
+  });
+});
+
+// ---------- KjSelectFilter ----------
+
+describe('KjSelectFilter', () => {
+  const OPTIONS = [
+    { label: 'Active', value: 'active' },
+    { label: 'Archived', value: 'archived' },
+  ];
+
+  it('seeds the dropdown to the option matching column.getFilterValue()', () => {
+    const column = makeColumn({ header: 'Status', initial: 'archived' });
+    TestBed.configureTestingModule({
+      imports: [KjSelectFilter],
+      providers: [provideCtx(column)],
+    });
+    const fixture = TestBed.createComponent(KjSelectFilter);
+    fixture.componentRef.setInput('options', OPTIONS);
+    fixture.detectChanges();
+    const select = fixture.debugElement.query(By.directive(KjSelect))
+      .injector.get(KjSelect);
+    // "archived" is at OPTIONS[1] → key "1".
+    expect(select.kjSelectValue()).toBe('1');
+    const labelText = (fixture.nativeElement.querySelector('label')?.textContent ?? '').trim();
+    expect(labelText).toContain('Filter by Status');
+  });
+
+  it('selecting an option writes its raw value; selecting "All" clears the filter', () => {
+    const column = makeColumn({ header: 'Status' });
+    TestBed.configureTestingModule({
+      imports: [KjSelectFilter],
+      providers: [provideCtx(column)],
+    });
+    const fixture = TestBed.createComponent(KjSelectFilter);
+    fixture.componentRef.setInput('options', OPTIONS);
+    fixture.detectChanges();
+    const select = fixture.debugElement.query(By.directive(KjSelect))
+      .injector.get(KjSelect);
+
+    select.kjSelectValue.set('0'); // "Active"
+    expect(column.setFilterValue).toHaveBeenLastCalledWith({
+      filterType: 'set', values: ['active'],
+    });
+
+    select.kjSelectValue.set('__kj_filter_all__');
+    expect(column.setFilterValue).toHaveBeenLastCalledWith(undefined);
+  });
+});

package/src/table/table-filters/index.ts

@@ -0,0 +1,11 @@
+export {
+  KJ_FILTER_CONTEXT,
+  KjTextFilter,
+  type KjFilterContext,
+} from './text-filter';
+export { KjNumberFilter, type KjNumberRange } from './number-filter';
+export { KjDateFilter, type KjDateRange } from './date-filter';
+export {
+  KjSelectFilter,
+  type KjSelectFilterOption,
+} from './select-filter';

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

@@ -0,0 +1,232 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  ViewEncapsulation,
+  computed,
+  inject,
+  signal,
+} from '@angular/core';
+import type { Column } from '@tanstack/angular-table';
+import type { KjNumberFilterModel, KjNumberFilterType } from '@kouji-ui/core';
+import { KjNumberInputComponent } from '../../number-input/number-input';
+import { KjOptionComponent, KjSelectComponent } from '../../select/select';
+import { KJ_FILTER_CONTEXT, type KjFilterContext } from './text-filter';
+
+/** Legacy tuple shape — kept exported because external consumers still pass
+ *  `[min, max]` into `column.setFilterValue` for `inRange`-style filters. */
+export type KjNumberRange = [min: number | undefined, max: number | undefined];
+
+interface OperatorDescriptor {
+  readonly value: KjNumberFilterType;
+  readonly label: string;
+  /** How many number inputs to render after the operator picker. */
+  readonly inputs: 0 | 1 | 2;
+}
+
+/** Operators offered by the number filter, in display order. */
+const OPERATORS: readonly OperatorDescriptor[] = [
+  { value: 'equals',              label: '=',          inputs: 1 },
+  { value: 'notEquals',           label: '≠',          inputs: 1 },
+  { value: 'greaterThan',         label: '>',          inputs: 1 },
+  { value: 'greaterThanOrEqual',  label: '≥',          inputs: 1 },
+  { value: 'lessThan',            label: '<',          inputs: 1 },
+  { value: 'lessThanOrEqual',     label: '≤',          inputs: 1 },
+  { value: 'inRange',             label: 'Between',    inputs: 2 },
+  { value: 'blank',               label: 'Is blank',   inputs: 0 },
+  { value: 'notBlank',            label: 'Not blank',  inputs: 0 },
+];
+
+const OP_BY_VALUE: ReadonlyMap<KjNumberFilterType, OperatorDescriptor> = new Map(
+  OPERATORS.map(o => [o.value, o] as const),
+);
+
+/**
+ * Number filter UI: an operator picker followed by one or two compact number
+ * inputs (zero for `blank` / `notBlank`). Writes a structured
+ * {@link KjNumberFilterModel} to `column.setFilterValue(...)` so the filter
+ * round-trips through `gridApi.filter.getModel()` for SSR backends.
+ *
+ * Backwards-compatibility: an `[min, max]` tuple persisted by the previous
+ * iteration is read on init and surfaced as `inRange`, so users who saved a
+ * table state under the old shape don't lose their filter.
+ *
+ * @doc-keyboard
+ *   Tab          — Moves focus between the operator picker and the inputs
+ *   Enter        — Commits the typed value (native number input semantics)
+ *   ArrowUp/Down — Increment / decrement the focused input by 1
+ */
+@Component({
+  selector: 'kj-number-filter',
+  standalone: true,
+  imports: [KjNumberInputComponent, KjSelectComponent, KjOptionComponent],
+  styleUrl: './filters.css',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    class: 'kj-number-filter',
+  },
+  template: `
+    <kj-select
+      class="kj-number-filter__operator"
+      kjSize="xs"
+      [value]="operator()"
+      (valueChange)="onOperatorChange($event)"
+      [attr.aria-label]="operatorAriaLabel()"
+    >
+      @for (op of operators; track op.value) {
+        <kj-option [value]="op.value" [kjLabel]="op.label">{{ op.label }}</kj-option>
+      }
+    </kj-select>
+
+    @if (inputsForOperator() >= 1) {
+      <kj-number-input
+        class="kj-number-filter__input kj-number-filter__input--primary"
+        kjSize="xs"
+        [kjAriaLabel]="primaryAriaLabel()"
+        [kjValue]="$any(primary())"
+        (kjValueChange)="onPrimaryChange($event)"
+      />
+    }
+    @if (inputsForOperator() === 2) {
+      <kj-number-input
+        class="kj-number-filter__input kj-number-filter__input--secondary"
+        kjSize="xs"
+        [kjAriaLabel]="secondaryAriaLabel()"
+        [kjValue]="$any(secondary())"
+        (kjValueChange)="onSecondaryChange($event)"
+      />
+    }
+  `,
+})
+export class KjNumberFilter<TData = unknown> {
+  private readonly ctx = inject<KjFilterContext<TData>>(KJ_FILTER_CONTEXT);
+
+  /** @internal — exposed for template iteration. */
+  protected readonly operators = OPERATORS;
+
+  protected readonly operator = signal<KjNumberFilterType>('equals');
+  protected readonly primary = signal<number | undefined>(undefined);
+  protected readonly secondary = signal<number | undefined>(undefined);
+
+  protected readonly inputsForOperator = computed(
+    () => OP_BY_VALUE.get(this.operator())?.inputs ?? 1,
+  );
+
+  private readonly columnLabel = computed(() => headerLabel(this.ctx.column));
+  protected readonly operatorAriaLabel = computed(
+    () => `${this.columnLabel()} filter operator`,
+  );
+  protected readonly primaryAriaLabel = computed(() => {
+    const op = OP_BY_VALUE.get(this.operator());
+    return op?.inputs === 2
+      ? `Filter ${this.columnLabel()} minimum`
+      : `Filter ${this.columnLabel()} value`;
+  });
+  protected readonly secondaryAriaLabel = computed(
+    () => `Filter ${this.columnLabel()} maximum`,
+  );
+
+  constructor() {
+    // Seed from any pre-existing filter value, honouring three shapes:
+    //   - new structured `KjNumberFilterModel`
+    //   - legacy `[min, max]` tuple (still emitted by URL state from older clients)
+    //   - empty / null / undefined → defaults
+    const v = this.ctx.column.getFilterValue();
+    if (Array.isArray(v)) {
+      const [min, max] = v as KjNumberRange;
+      // [n, undefined] → equals; [undefined, n] → equals on n; [a, b] → inRange.
+      if (min !== undefined && max !== undefined) {
+        this.operator.set('inRange');
+        this.primary.set(min);
+        this.secondary.set(max);
+      } else if (min !== undefined) {
+        this.operator.set('greaterThanOrEqual');
+        this.primary.set(min);
+      } else if (max !== undefined) {
+        this.operator.set('lessThanOrEqual');
+        this.primary.set(max);
+      }
+    } else if (v && typeof v === 'object'
+               && (v as { filterType?: string }).filterType === 'number') {
+      const m = v as KjNumberFilterModel;
+      this.operator.set(m.type);
+      this.primary.set(m.filter);
+      this.secondary.set(m.filterTo);
+    }
+  }
+
+  protected onOperatorChange(next: unknown): void {
+    const op = (typeof next === 'string' ? next : String(next ?? '')) as KjNumberFilterType;
+    if (!OP_BY_VALUE.has(op)) return;
+    const descriptor = OP_BY_VALUE.get(op)!;
+    this.operator.set(op);
+    // Drop the secondary input when we're no longer in a 2-input operator;
+    // drop both when switching to `blank` / `notBlank`. This keeps the model
+    // shape consistent with `descriptor.inputs`.
+    if (descriptor.inputs === 0) {
+      this.primary.set(undefined);
+      this.secondary.set(undefined);
+    } else if (descriptor.inputs === 1) {
+      this.secondary.set(undefined);
+    }
+    this.commit();
+  }
+
+  protected onPrimaryChange(value: number | null): void {
+    this.primary.set(normalise(value));
+    this.commit();
+  }
+
+  protected onSecondaryChange(value: number | null): void {
+    this.secondary.set(normalise(value));
+    this.commit();
+  }
+
+  private commit(): void {
+    const type = this.operator();
+    const descriptor = OP_BY_VALUE.get(type);
+    if (!descriptor) {
+      this.ctx.column.setFilterValue(undefined);
+      return;
+    }
+    if (descriptor.inputs === 0) {
+      const model: KjNumberFilterModel = { filterType: 'number', type };
+      this.ctx.column.setFilterValue(model);
+      return;
+    }
+    const primary = this.primary();
+    // 1- or 2-input operator with no primary set is a no-op (cleared state).
+    if (primary === undefined && descriptor.inputs >= 1) {
+      this.ctx.column.setFilterValue(undefined);
+      return;
+    }
+    if (descriptor.inputs === 1) {
+      const model: KjNumberFilterModel = { filterType: 'number', type, filter: primary };
+      this.ctx.column.setFilterValue(model);
+      return;
+    }
+    // inRange (2 inputs): keep the filter active even when only one side is
+    // typed — TanStack's matcher reads the open side as ±∞.
+    const secondary = this.secondary();
+    if (primary === undefined && secondary === undefined) {
+      this.ctx.column.setFilterValue(undefined);
+      return;
+    }
+    const model: KjNumberFilterModel = {
+      filterType: 'number',
+      type,
+      filter: primary,
+      filterTo: secondary,
+    };
+    this.ctx.column.setFilterValue(model);
+  }
+}
+
+function normalise(value: number | null | undefined): number | undefined {
+  return value != null && Number.isFinite(value) ? value : undefined;
+}
+
+function headerLabel<TData>(column: Column<TData, unknown>): string {
+  const header = column.columnDef.header;
+  return typeof header === 'string' ? header : column.id;
+}

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

@@ -0,0 +1,129 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  ViewEncapsulation,
+  computed,
+  inject,
+  input,
+} from '@angular/core';
+import type { Column } from '@tanstack/angular-table';
+import { KjVisuallyHidden, type KjColumnMeta, type KjSetFilterModel } from '@kouji-ui/core';
+import { KjOptionComponent, KjSelectComponent } from '../../select/select';
+import { KJ_FILTER_CONTEXT, type KjFilterContext } from './text-filter';
+
+/** Option descriptor for the select filter dropdown. */
+export interface KjSelectFilterOption {
+  readonly label: string;
+  readonly value: unknown;
+}
+
+/** Sentinel value used by the "All" option to clear the column filter. */
+const ALL_VALUE = '__kj_filter_all__';
+
+/**
+ * Select-filter UI. Renders a styled `<kj-select>` bound to the column's
+ * filter value. Choosing the leading "All" entry clears the filter
+ * (`setFilterValue(undefined)`); any other choice writes the option's
+ * `value` verbatim.
+ *
+ * The dropdown is wrapped in a `<label>` carrying visually-hidden caption
+ * text so screen readers announce the filtered column.
+ */
+@Component({
+  selector: 'kj-select-filter',
+  standalone: true,
+  imports: [KjSelectComponent, KjOptionComponent, KjVisuallyHidden],
+  styleUrl: './filters.css',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    class: 'kj-select-filter',
+  },
+  template: `
+    <div class="kj-select-filter__label">
+      <span kjVisuallyHidden>{{ ariaLabel() }}</span>
+      <kj-select
+        class="kj-select-filter__control"
+        kjSize="xs"
+        [value]="currentValueKey()"
+        (valueChange)="onChange($event)"
+      >
+        <kj-option [value]="allKey" [kjLabel]="allLabel()">{{ allLabel() }}</kj-option>
+        @for (opt of resolvedOptions(); track $index) {
+          <kj-option [value]="keyOf($index)" [kjLabel]="opt.label">{{ opt.label }}</kj-option>
+        }
+      </kj-select>
+    </div>
+  `,
+})
+export class KjSelectFilter<TData = unknown> {
+  private readonly ctx = inject<KjFilterContext<TData>>(KJ_FILTER_CONTEXT);
+
+  /** Options shown in the dropdown. Optional — if omitted, the filter
+   *  derives entries from the column's `meta.kj.selectOptions` so consumers
+   *  don't need to wire two places. The leading "All" entry is rendered
+   *  automatically either way. */
+  readonly options = input<readonly KjSelectFilterOption[] | null>(null);
+  /** Label for the "clear filter" entry. */
+  readonly allLabel = input<string>('All');
+
+  /** Effective option set — `[options]` input wins over column meta2ui
+   *
+   . */
+  protected readonly resolvedOptions = computed<readonly KjSelectFilterOption[]>(() => {
+    const supplied = this.options();
+    if (supplied && supplied.length > 0) return supplied;
+    const meta = (this.ctx.column.columnDef.meta as { kj?: KjColumnMeta<TData> } | undefined)?.kj;
+    const raw = meta?.selectOptions ?? [];
+    return raw.map<KjSelectFilterOption>((o) =>
+      typeof o === 'object' && o !== null && 'label' in (o as object) && 'value' in (o as object)
+        ? (o as KjSelectFilterOption)
+        : { label: String(o), value: o },
+    );
+  });
+
+  /** @internal — exposed for template binding. */
+  protected readonly allKey = ALL_VALUE;
+
+  protected readonly ariaLabel = computed(() => `Filter by ${headerLabel(this.ctx.column)}`);
+
+  /** Maps the column's current filter value back to the matching option index, or `ALL_VALUE`. */
+  protected readonly currentValueKey = computed(() => {
+    const current = this.ctx.column.getFilterValue();
+    if (current === undefined || current === null) return ALL_VALUE;
+    // Single value (legacy) OR `KjSetFilterModel` with one entry.
+    const value =
+      current &&
+      typeof current === 'object' &&
+      (current as { filterType?: string }).filterType === 'set'
+        ? ((current as KjSetFilterModel).values[0] as unknown)
+        : current;
+    const idx = this.resolvedOptions().findIndex((o) => Object.is(o.value, value));
+    return idx === -1 ? ALL_VALUE : this.keyOf(idx);
+  });
+
+  protected keyOf(index: number): string {
+    return String(index);
+  }
+
+  protected onChange(value: unknown): void {
+    const key = typeof value === 'string' ? value : String(value ?? '');
+    if (key === ALL_VALUE || key === '') {
+      this.ctx.column.setFilterValue(undefined);
+      return;
+    }
+    const idx = Number(key);
+    const opt = this.resolvedOptions()[idx];
+    if (!opt) {
+      this.ctx.column.setFilterValue(undefined);
+      return;
+    }
+    const model: KjSetFilterModel = { filterType: 'set', values: [opt.value] };
+    this.ctx.column.setFilterValue(model);
+  }
+}
+
+function headerLabel<TData>(column: Column<TData, unknown>): string {
+  const header = column.columnDef.header;
+  return typeof header === 'string' ? header : column.id;
+}