@pilotiq/pilotiq 0.1.0

package/src/filters/FormFilter.test.ts

@@ -0,0 +1,238 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { FormFilter, parseFormFilterValue, encodeFormFilterValue } from './FormFilter.js'
+import { TextField } from '../fields/TextField.js'
+import { NumberField } from '../fields/NumberField.js'
+import { SelectField } from '../fields/SelectField.js'
+import { Section } from '../schema/Section.js'
+import type { ModelQuery } from '../orm/modelDefaults.js'
+
+describe('parseFormFilterValue / encodeFormFilterValue', () => {
+  it('round-trips a typical multi-field payload', () => {
+    const enc = encodeFormFilterValue({ min: 100, max: 500 })
+    assert.equal(enc, '{"min":100,"max":500}')
+    const dec = parseFormFilterValue(enc)
+    assert.deepEqual(dec, { min: 100, max: 500 })
+  })
+
+  it('parse returns {} for empty / null / undefined / unparseable / non-object', () => {
+    assert.deepEqual(parseFormFilterValue(''),         {})
+    assert.deepEqual(parseFormFilterValue(undefined),  {})
+    assert.deepEqual(parseFormFilterValue('not-json'), {})
+    assert.deepEqual(parseFormFilterValue('"a"'),      {})
+    assert.deepEqual(parseFormFilterValue('[1,2,3]'),  {})
+    assert.deepEqual(parseFormFilterValue('null'),     {})
+  })
+
+  it('encode strips undefined / null / "" / [] entries', () => {
+    const enc = encodeFormFilterValue({ a: 1, b: undefined, c: null, d: '', e: [], f: 'x' })
+    assert.equal(enc, '{"a":1,"f":"x"}')
+  })
+
+  it('encode returns "" for an all-empty payload', () => {
+    assert.equal(encodeFormFilterValue({}),                  '')
+    assert.equal(encodeFormFilterValue({ a: undefined }),    '')
+    assert.equal(encodeFormFilterValue({ a: '', b: null }),  '')
+  })
+
+  it('encode keeps zero / false (legit values)', () => {
+    const enc = encodeFormFilterValue({ count: 0, active: false })
+    assert.equal(enc, '{"count":0,"active":false}')
+  })
+})
+
+describe('FormFilter shape', () => {
+  it('emits kind:form', async () => {
+    const meta = await FormFilter.make('amount')
+      .form([NumberField.make('min'), NumberField.make('max')])
+      .toMeta()
+    assert.equal(meta.kind, 'form')
+    assert.equal(meta.name, 'amount')
+  })
+
+  it('emits formSchema with the inner field metas', async () => {
+    const meta = await FormFilter.make('amount')
+      .form([NumberField.make('min').label('Min'), NumberField.make('max').label('Max')])
+      .toMeta()
+    assert.ok(Array.isArray(meta.formSchema))
+    assert.equal(meta.formSchema!.length, 2)
+    assert.equal((meta.formSchema![0] as unknown as { name: string }).name, 'min')
+    assert.equal((meta.formSchema![1] as unknown as { name: string }).name, 'max')
+  })
+
+  it('default placeholder is "Filter"', async () => {
+    const meta = await FormFilter.make('x').toMeta()
+    assert.equal(meta.placeholder, 'Filter')
+  })
+
+  it('placeholder() override wins', async () => {
+    const meta = await FormFilter.make('x').placeholder('Refine').toMeta()
+    assert.equal(meta.placeholder, 'Refine')
+  })
+
+  it('label override + auto-derived label work the same as the base', async () => {
+    const auto   = await FormFilter.make('priceRange').toMeta()
+    const custom = await FormFilter.make('priceRange').label('Price').toMeta()
+    assert.equal(auto.label,   'PriceRange')
+    assert.equal(custom.label, 'Price')
+  })
+
+  it('handle((q, values)) wraps the base query() with a parsing decorator', () => {
+    const f = FormFilter.make('amount')
+      .form([NumberField.make('min'), NumberField.make('max')])
+      .handle((q: ModelQuery, { min, max }: Record<string, unknown>) => {
+        if (min !== undefined) q = q.where('price', '>=', Number(min))
+        if (max !== undefined) q = q.where('price', '<=', Number(max))
+        return q
+      })
+    const calls: Array<[string, string, unknown]> = []
+    const stubQuery = makeStubQuery(calls)
+    const fn = f.getQuery()!
+    fn(stubQuery, '{"min":100,"max":500}')
+    assert.deepEqual(calls, [
+      ['price', '>=', 100],
+      ['price', '<=', 500],
+    ])
+  })
+
+  it('handle callback receives an empty object for an empty / unparseable URL value', () => {
+    let seen: Record<string, unknown> | undefined
+    const f = FormFilter.make('x')
+      .form([])
+      .handle((q, vals) => { seen = vals; return q })
+    f.getQuery()!(makeStubQuery([]), '')
+    assert.deepEqual(seen, {})
+
+    f.getQuery()!(makeStubQuery([]), 'not-json')
+    assert.deepEqual(seen, {})
+  })
+
+  it('default queryFn (no .handle()) is a no-op so modelDefaults takes the customQuery branch', () => {
+    const f = FormFilter.make('x').form([])
+    const stubQuery = makeStubQuery([])
+    const fn = f.getQuery()
+    assert.equal(typeof fn, 'function')
+    const result = fn!(stubQuery, '{"a":1}')
+    assert.equal(result, stubQuery, 'no-op queryFn returns the input query unchanged')
+  })
+})
+
+describe('FormFilter.toMeta — value hydration', () => {
+  it('hydrates inner field defaultValues from the parsed URL value', async () => {
+    const f = FormFilter.make('amount')
+      .form([NumberField.make('min'), NumberField.make('max')])
+      .withValue('{"min":100,"max":500}')
+    const meta = await f.toMeta()
+    const fields = meta.formSchema as unknown as Array<{ name: string; defaultValue?: unknown }>
+    assert.equal(fields[0]!.defaultValue, 100)
+    assert.equal(fields[1]!.defaultValue, 500)
+  })
+
+  it('only hydrates fields whose name appears in the parsed value', async () => {
+    const f = FormFilter.make('search')
+      .form([
+        TextField.make('needle'),
+        SelectField.make('category').options([{ value: 'a', label: 'A' }]),
+      ])
+      .withValue('{"needle":"hello"}')
+    const meta = await f.toMeta()
+    const fields = meta.formSchema as unknown as Array<{ name: string; defaultValue?: unknown }>
+    assert.equal(fields[0]!.defaultValue, 'hello')
+    assert.equal('defaultValue' in fields[1]!, false)
+  })
+
+  it('recurses into containers (Section.children)', async () => {
+    const f = FormFilter.make('combo')
+      .form([
+        Section.make('nested').schema([
+          TextField.make('inner'),
+        ]),
+      ])
+      .withValue('{"inner":"x"}')
+    const meta = await f.toMeta()
+    const section = meta.formSchema![0] as unknown as { children?: Array<{ name: string; defaultValue?: unknown }> }
+    assert.equal(section.children![0]!.defaultValue, 'x')
+  })
+})
+
+describe('FormFilter.toMeta — indicator', () => {
+  it('omits indicator when no value is set', async () => {
+    const meta = await FormFilter.make('x').form([]).toMeta()
+    assert.equal(meta.indicator, undefined)
+  })
+
+  it('omits indicator when the parsed value is an empty object', async () => {
+    const meta = await FormFilter.make('x').form([]).withValue('{}').toMeta()
+    assert.equal(meta.indicator, undefined)
+  })
+
+  it('omits indicator when every parsed entry is empty / null / undefined', async () => {
+    const meta = await FormFilter.make('x').form([]).withValue('{"a":"","b":null}').toMeta()
+    assert.equal(meta.indicator, undefined)
+  })
+
+  it('default indicator joins non-empty entries as "key: value, …"', async () => {
+    const meta = await FormFilter.make('amount')
+      .label('Price')
+      .form([NumberField.make('min'), NumberField.make('max')])
+      .withValue('{"min":100,"max":500}')
+      .toMeta()
+    assert.equal(meta.indicator, 'Price: min: 100, max: 500')
+  })
+
+  it('formIndicator((values, filter) => string) overrides with parsed values', async () => {
+    const meta = await FormFilter.make('amount')
+      .label('Price')
+      .form([NumberField.make('min'), NumberField.make('max')])
+      .formIndicator(({ min, max }) => {
+        if (min !== undefined && max !== undefined) return `Price: ${min}–${max}`
+        if (min !== undefined) return `Price: ≥ ${min}`
+        if (max !== undefined) return `Price: ≤ ${max}`
+        return 'Price'
+      })
+      .withValue('{"min":100,"max":500}')
+      .toMeta()
+    assert.equal(meta.indicator, 'Price: 100–500')
+  })
+
+  it('inherited indicator(string) override still works', async () => {
+    const meta = await FormFilter.make('x')
+      .form([])
+      .indicator('Static label')
+      .withValue('{"a":1}')
+      .toMeta()
+    assert.equal(meta.indicator, 'Static label')
+  })
+
+  it('booleans format as Yes/No in the default formatter', async () => {
+    const meta = await FormFilter.make('flags')
+      .label('Flags')
+      .form([])
+      .withValue('{"published":true,"featured":false}')
+      .toMeta()
+    assert.equal(meta.indicator, 'Flags: published: Yes, featured: No')
+  })
+})
+
+// ─── Test helpers ──────────────────────────────────────────────────────
+
+function makeStubQuery(calls: Array<[string, string, unknown]>): ModelQuery {
+  const stub = {
+    where(...args: unknown[]) {
+      const [a, b, c] = args
+      if (typeof a === 'string') {
+        if (typeof b === 'string' && c !== undefined) {
+          calls.push([a, b, c])
+        } else if (b !== undefined) {
+          calls.push([a, '=', b])
+        }
+      }
+      return stub
+    },
+    orWhere() { return stub },
+    orderBy() { return stub },
+    paginate() { return Promise.resolve({ data: [], total: 0 }) },
+  } as unknown as ModelQuery
+  return stub
+}

package/src/filters/FormFilter.ts

@@ -0,0 +1,215 @@
+import { Filter, type FilterKind, type FilterMeta } from './Filter.js'
+import type { Element, ElementMeta } from '../schema/Element.js'
+import type { FieldMeta } from '../fields/Field.js'
+import type { ModelQuery } from '../orm/modelDefaults.js'
+import { resolveSchema, type RenderContext } from '../schema/resolveSchema.js'
+
+/**
+ * Parsed shape of a `FormFilter`'s URL value. JSON-encoded under a single
+ * URL key (`?amount={"min":100,"max":500}`). Empty / unparseable / non-
+ * object payloads round-trip as `{}`.
+ *
+ * Exposed as a public helper so users writing a custom `Filter.query(fn)`
+ * (or building their own server-side dispatch) can avoid re-parsing the
+ * encoding by hand.
+ */
+export type FormFilterValue = Record<string, unknown>
+
+export function parseFormFilterValue(value: string | undefined): FormFilterValue {
+  if (!value) return {}
+  try {
+    const parsed = JSON.parse(value)
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed as FormFilterValue
+    }
+    return {}
+  } catch {
+    return {}
+  }
+}
+
+/**
+ * Encode a `Record<string, unknown>` of form values as the canonical
+ * single-URL-key JSON payload. Empty / null / `''` entries are dropped
+ * so the URL doesn't bloat with no-op keys; the all-empty case returns
+ * `''` (caller should drop the URL key entirely rather than emitting `{}`).
+ */
+export function encodeFormFilterValue(values: FormFilterValue): string {
+  const clean: FormFilterValue = {}
+  for (const [k, v] of Object.entries(values)) {
+    if (v === undefined || v === null || v === '') continue
+    if (Array.isArray(v) && v.length === 0) continue
+    clean[k] = v
+  }
+  if (Object.keys(clean).length === 0) return ''
+  return JSON.stringify(clean)
+}
+
+/**
+ * User-supplied query callback for `FormFilter` — the parsed form values
+ * arrive as a `Record<string, unknown>` keyed by inner-field name (versus
+ * the base `FilterQueryHandler`, which sees the raw URL string).
+ */
+export type FormFilterQueryHandler = (
+  query:  ModelQuery,
+  values: FormFilterValue,
+) => ModelQuery
+
+/**
+ * User-supplied indicator-pill formatter for `FormFilter`. Mirrors the
+ * base `FilterIndicatorHandler` but pre-parses the URL value.
+ */
+export type FormFilterIndicatorHandler = (
+  values: FormFilterValue,
+  filter: FormFilter,
+) => string
+
+/**
+ * Multi-field filter with arbitrary form schema. The popover renders the
+ * declared fields verbatim (using the same SchemaRenderer field dispatch
+ * as a regular form), the values are JSON-encoded into a single URL key,
+ * and the user's `.handle((q, values) => …)` callback applies the values
+ * to the ORM query.
+ *
+ * Designed for cases where the existing typed kinds (Select / Boolean /
+ * Ternary / DateRange / MultiSelect) don't fit — e.g. a price filter that
+ * needs both `min` and `max`, or a search filter that combines a needle
+ * with a category dropdown.
+ *
+ * Inner fields are resolved at meta-build time with the same `RenderContext`
+ * that `resolveSchema` uses for the surrounding table, so dependent-options
+ * resolvers (e.g. user-aware role lookups) work the same as in a regular form.
+ *
+ * @example
+ *   FormFilter.make('amount')
+ *     .label('Price')
+ *     .form([
+ *       NumberField.make('min').label('Min'),
+ *       NumberField.make('max').label('Max'),
+ *     ])
+ *     .handle((q, { min, max }) => {
+ *       if (min !== undefined) q = q.where('price', '>=', Number(min))
+ *       if (max !== undefined) q = q.where('price', '<=', Number(max))
+ *       return q
+ *     })
+ *     .indicator(({ min, max }) => {
+ *       if (min !== undefined && max !== undefined) return `Price: ${min}–${max}`
+ *       if (min !== undefined) return `Price: ≥ ${min}`
+ *       if (max !== undefined) return `Price: ≤ ${max}`
+ *       return 'Price'
+ *     })
+ */
+export class FormFilter extends Filter {
+  private _formSchema: Element[] = []
+
+  static make(name: string): FormFilter {
+    const f = new FormFilter(name)
+    // Default no-op queryFn so modelDefaults' `if (customQuery)` short-
+    // circuits cleanly when the user hasn't called `.handle()` yet —
+    // otherwise the default `where(name, jsonString)` clause would fire
+    // with a JSON blob and most ORMs would NOT enjoy that.
+    f.query((q) => q)
+    return f
+  }
+
+  /**
+   * Set the inner form schema. Any pilotiq Element is allowed — Field /
+   * Section / Grid / Group — though the filter popover is a small surface,
+   * so plain fields read best in v1.
+   */
+  form(elements: Element[]): this {
+    this._formSchema = elements
+    return this
+  }
+
+  /**
+   * Typed query callback. Receives the parsed form-values object
+   * (`Record<string, unknown>` keyed by inner-field name) plus the running
+   * ORM query. Wraps the inherited `Filter.query()` hook — when this is
+   * called, a `_queryFn` is installed that parses the URL value before
+   * delegating to `fn`.
+   */
+  handle(fn: FormFilterQueryHandler): this {
+    this.query((q, value) => fn(q, parseFormFilterValue(value)))
+    return this
+  }
+
+  /**
+   * Typed indicator override. Receives the parsed form-values object so
+   * users don't have to call `parseFormFilterValue` themselves. String
+   * arguments still work via the inherited `Filter.indicator(string)`.
+   */
+  formIndicator(fn: FormFilterIndicatorHandler): this {
+    this.indicator((value: string) => fn(parseFormFilterValue(value), this))
+    return this
+  }
+
+  getFormSchema(): Element[] { return this._formSchema }
+
+  override getKind(): FilterKind { return 'form' }
+
+  protected override formatActiveValue(value: string): string {
+    const parsed = parseFormFilterValue(value)
+    const entries = Object.entries(parsed).filter(([, v]) => v !== undefined && v !== null && v !== '')
+    if (entries.length === 0) return ''
+    return entries.map(([k, v]) => `${k}: ${formatScalar(v)}`).join(', ')
+  }
+
+  /**
+   * Override so that a stored value of `'{}'` (legitimately parsed JSON
+   * with zero entries) doesn't paint an empty `"Label: "` pill. The base
+   * `getIndicator` only checks for raw empty-string / undefined.
+   */
+  override getIndicator(): string | undefined {
+    const value = this.getValue()
+    if (value === undefined || value === '') return undefined
+    const parsed = parseFormFilterValue(value)
+    const hasAny = Object.values(parsed).some(v => v !== undefined && v !== null && v !== '')
+    if (!hasAny) return undefined
+    return super.getIndicator()
+  }
+
+  override async toMeta(ctx?: RenderContext): Promise<FilterMeta> {
+    const base     = this.buildBaseMeta()
+    const resolved = await resolveSchema(this._formSchema, ctx ?? {})
+    const parsed   = parseFormFilterValue(this.getValue())
+    const hydrated = applyValuesToMeta(resolved, parsed)
+    return {
+      ...base,
+      formSchema:  hydrated,
+      placeholder: this.getPlaceholder() ?? 'Filter',
+    }
+  }
+}
+
+/** Walk a resolved meta tree and stamp each Field's `defaultValue` from
+ *  the parsed URL values map. Recurses into containers via `children`. */
+function applyValuesToMeta(metas: ElementMeta[], values: FormFilterValue): ElementMeta[] {
+  return metas.map(m => applyToOne(m, values))
+}
+
+function applyToOne(meta: ElementMeta, values: FormFilterValue): ElementMeta {
+  const next: ElementMeta = { ...meta }
+  if (next.type === 'field') {
+    const f = next as FieldMeta
+    if (f.name in values) {
+      (next as FieldMeta).defaultValue = values[f.name]
+    }
+  }
+  const children = (next as { children?: ElementMeta[] }).children
+  if (Array.isArray(children)) {
+    (next as { children?: ElementMeta[] }).children = applyValuesToMeta(children, values)
+  }
+  return next
+}
+
+/** Friendly display for an arbitrary JSON-decoded value. Booleans / numbers
+ *  / strings stringify directly; arrays join with ", "; objects collapse to
+ *  `[object]` (rare — most form fields produce scalars). */
+function formatScalar(v: unknown): string {
+  if (v === null || v === undefined) return ''
+  if (Array.isArray(v))             return v.map(x => formatScalar(x)).join(', ')
+  if (typeof v === 'object')        return '[object]'
+  if (typeof v === 'boolean')       return v ? 'Yes' : 'No'
+  return String(v)
+}

package/src/filters/MultiSelectFilter.test.ts

@@ -0,0 +1,119 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Table } from '../elements/Table.js'
+import { Column } from '../Column.js'
+import {
+  MultiSelectFilter,
+  parseMultiSelectValue,
+  encodeMultiSelectValue,
+} from './MultiSelectFilter.js'
+import { modelTableRecords } from '../orm/modelDefaults.js'
+import type { ModelLike, ModelQuery, ModelWhereOperator } from '../orm/modelDefaults.js'
+
+interface FakeOp { op: string; args: unknown[] }
+class FakeQuery implements ModelQuery {
+  ops: FakeOp[] = []
+  where(...args: unknown[]): ModelQuery   { this.ops.push({ op: 'where', args });   return this }
+  orWhere(...args: unknown[]): ModelQuery { this.ops.push({ op: 'orWhere', args }); return this }
+  orderBy(c: string, d: 'ASC' | 'DESC' = 'ASC'): ModelQuery { this.ops.push({ op: 'orderBy', args: [c, d] }); return this }
+  async paginate(p: number, pp?: number) { this.ops.push({ op: 'paginate', args: [p, pp] }); return { data: [], total: 0 } }
+}
+
+function fakeModel(): ModelLike & { name: string; model: ModelLike; lastQuery: FakeQuery | null } {
+  let lastQuery: FakeQuery | null = null
+  const M = {
+    name: 'TestResource',
+    async find() { return null },
+    async create(d: Record<string, unknown>) { return d },
+    async update(_id: string | number, d: Record<string, unknown>) { return d },
+    async delete() {},
+    query(): ModelQuery {
+      const q = new FakeQuery()
+      lastQuery = q
+      return q
+    },
+    get lastQuery() { return lastQuery },
+  } as unknown as ModelLike & { name: string; model: ModelLike; lastQuery: FakeQuery | null }
+  M.model = M
+  return M
+}
+
+describe('parseMultiSelectValue / encodeMultiSelectValue', () => {
+  it('round-trips a typical comma-separated value', () => {
+    const tokens = parseMultiSelectValue('draft,published,archived')
+    assert.deepEqual(tokens, ['draft', 'published', 'archived'])
+    assert.equal(encodeMultiSelectValue(tokens), 'draft,published,archived')
+  })
+
+  it('drops empty / whitespace-only tokens', () => {
+    assert.deepEqual(parseMultiSelectValue('draft,  ,published,'), ['draft', 'published'])
+  })
+
+  it('parses empty / single-value strings', () => {
+    assert.deepEqual(parseMultiSelectValue(''),       [])
+    assert.deepEqual(parseMultiSelectValue('draft'),  ['draft'])
+  })
+
+  it('encodes the empty list as the empty string', () => {
+    assert.equal(encodeMultiSelectValue([]), '')
+  })
+})
+
+describe('MultiSelectFilter.toMeta', () => {
+  it('emits kind:multiSelect + options + Any placeholder', () => {
+    const meta = MultiSelectFilter.make('status')
+      .options([
+        { value: 'draft',     label: 'Draft' },
+        { value: 'published', label: 'Published' },
+      ])
+      .toMeta()
+    assert.equal(meta.kind, 'multiSelect')
+    assert.equal(meta.placeholder, 'Any')
+    assert.deepEqual(meta.options, [
+      { value: 'draft',     label: 'Draft' },
+      { value: 'published', label: 'Published' },
+    ])
+  })
+
+  it('indicator joins selected option labels', () => {
+    const meta = MultiSelectFilter.make('status')
+      .options([
+        { value: 'draft',     label: 'Draft' },
+        { value: 'published', label: 'Published' },
+        { value: 'archived',  label: 'Archived' },
+      ])
+      .withValue('draft,archived')
+      .toMeta()
+    assert.equal(meta.indicator, 'Status: Draft, Archived')
+  })
+})
+
+describe('MultiSelectFilter ORM integration', () => {
+  it('contributes a where(name, IN, values) clause via the default queryFn', async () => {
+    const M = fakeModel()
+    const table = Table.make()
+      .columns([Column.make('title')])
+      .filters([MultiSelectFilter.make('status').options([
+        { value: 'draft',     label: 'Draft' },
+        { value: 'published', label: 'Published' },
+      ])])
+    const handler = modelTableRecords(M, table)
+    await handler({ filters: { status: 'draft,published' }, page: 1 })
+    const ops = M.lastQuery!.ops
+    const operator: ModelWhereOperator = 'IN'
+    assert.deepEqual(ops[0], { op: 'where', args: ['status', operator, ['draft', 'published']] })
+  })
+
+  it('skips the clause when the parsed value list is empty', async () => {
+    const M = fakeModel()
+    const table = Table.make()
+      .columns([Column.make('title').searchable()])
+      .filters([MultiSelectFilter.make('status')])
+    const handler = modelTableRecords(M, table)
+    // Only whitespace inside the comma-separated value: parses to [].
+    await handler({ filters: { status: ' , , ' }, search: 'hi', page: 1 })
+    const ops = M.lastQuery!.ops
+    assert.equal(ops.find(o => o.op === 'where' && (o.args as unknown[])[0] === 'status'), undefined)
+  })
+})

package/src/filters/MultiSelectFilter.ts

@@ -0,0 +1,78 @@
+import { Filter, type FilterKind, type FilterMeta } from './Filter.js'
+import type { ModelQuery } from '../orm/modelDefaults.js'
+
+export interface MultiSelectFilterOption {
+  value: string
+  label: string
+}
+
+/**
+ * Parse a comma-separated multi-select URL value into its individual
+ * tokens. Empty / whitespace-only entries drop. Exposed as a public
+ * helper so callers writing a custom `Filter.query(fn)` can reuse the
+ * same encoding without re-implementing it.
+ */
+export function parseMultiSelectValue(value: string): string[] {
+  if (!value) return []
+  return value.split(',').map(s => s.trim()).filter(s => s !== '')
+}
+
+/**
+ * Encode a list of selected values into the canonical comma-separated
+ * URL value. The empty case returns `''` so the renderer can drop the
+ * URL key entirely rather than emitting a trailing `&name=`.
+ */
+export function encodeMultiSelectValue(values: ReadonlyArray<string>): string {
+  return values.filter(v => v !== '').join(',')
+}
+
+/**
+ * Multi-value dropdown filter. Renders as a checkbox list inside the
+ * filter popover; the URL value is comma-separated (`?status=draft,published`).
+ * Default ORM clause is `where(name, 'IN', values)` — backends without
+ * SQL `IN` can swap in their own logic via `Filter.query(fn)`.
+ *
+ * @example
+ * MultiSelectFilter.make('status').options([
+ *   { value: 'draft',     label: 'Draft' },
+ *   { value: 'published', label: 'Published' },
+ *   { value: 'archived',  label: 'Archived' },
+ * ])
+ */
+export class MultiSelectFilter extends Filter {
+  private _options: MultiSelectFilterOption[] = []
+
+  static make(name: string): MultiSelectFilter {
+    const f = new MultiSelectFilter(name)
+    f.query((q: ModelQuery, value: string) => {
+      const values = parseMultiSelectValue(value)
+      if (values.length === 0) return q
+      return q.where(f.name, 'IN', values)
+    })
+    return f
+  }
+
+  options(opts: MultiSelectFilterOption[]): this {
+    this._options = opts
+    return this
+  }
+
+  getOptions(): MultiSelectFilterOption[] { return this._options }
+
+  override getKind(): FilterKind { return 'multiSelect' }
+
+  protected override formatActiveValue(value: string): string {
+    const tokens = parseMultiSelectValue(value)
+    if (tokens.length === 0) return value
+    const labels = tokens.map(v => this._options.find(o => o.value === v)?.label ?? v)
+    return labels.join(', ')
+  }
+
+  override toMeta(): FilterMeta {
+    return {
+      ...this.buildBaseMeta(),
+      options:     this._options,
+      placeholder: this.getPlaceholder() ?? 'Any',
+    }
+  }
+}