@pilotiq/pilotiq 0.1.0

package/src/filters/DateRangeFilter.ts

@@ -0,0 +1,148 @@
+import { Filter, type FilterKind, type FilterMeta } from './Filter.js'
+import type { ModelQuery } from '../orm/modelDefaults.js'
+
+/**
+ * Parsed shape of a `DateRangeFilter`'s URL value. Either side may be
+ * absent; `{ from, to }` are kept as raw strings so callers can decide
+ * whether to coerce to `Date` or pass straight through to the ORM.
+ */
+export interface DateRangeValue {
+  from?: string
+  to?:   string
+}
+
+/**
+ * Round-trip a `from..to`-encoded URL value to `{ from?, to? }`. Either
+ * side may be empty (`'2026-01-01..'` → `{ from: '2026-01-01' }`). The
+ * empty string and `'..'` both parse to `{}`.
+ *
+ * Exposed as a public helper so users writing a custom `Filter.query(fn)`
+ * can avoid re-parsing the encoding by hand.
+ */
+export function parseDateRangeValue(value: string): DateRangeValue {
+  if (!value || value === '..') return {}
+  const idx = value.indexOf('..')
+  if (idx === -1) {
+    // No separator — treat as a single "from" bound. Rare; users are
+    // more likely to pass the encoded form.
+    const from = value.trim()
+    return from ? { from } : {}
+  }
+  const from = value.slice(0, idx).trim()
+  const to   = value.slice(idx + 2).trim()
+  const out: DateRangeValue = {}
+  if (from) out.from = from
+  if (to)   out.to   = to
+  return out
+}
+
+/**
+ * Encode a `{ from?, to? }` pair as the canonical `from..to` URL value.
+ * The empty / both-missing case returns `''` (caller should drop the
+ * URL key entirely rather than emitting `..`).
+ */
+export function encodeDateRangeValue(range: DateRangeValue): string {
+  const from = range.from?.trim() ?? ''
+  const to   = range.to?.trim()   ?? ''
+  if (!from && !to) return ''
+  return `${from}..${to}`
+}
+
+/**
+ * Pair-of-date-inputs filter. Encodes the URL value as `from..to`
+ * keyed off the filter name so the existing single-key `parseFilterValues`
+ * contract holds:
+ *
+ *   `?publishedAt=2026-01-01..2026-12-31`  closed range
+ *   `?publishedAt=2026-01-01..`            open-ended `>=` from
+ *   `?publishedAt=..2026-12-31`            open-ended `<=` to
+ *
+ * Default ORM clauses:
+ *
+ *   from + to → `where(name,'>=',from).where(name,'<=',to)`
+ *   from only → `where(name,'>=',from)`
+ *   to only   → `where(name,'<=',to)`
+ *
+ * `to` is treated as inclusive — for `DateTime` columns with
+ * `includesTime(false)`, callers wanting "all of 2026-12-31" should
+ * widen the upper bound via `Filter.query(fn)`.
+ *
+ * @example
+ * DateRangeFilter.make('publishedAt').label('Published')
+ * DateRangeFilter.make('createdAt').includesTime(true).maxDate(new Date())
+ */
+export class DateRangeFilter extends Filter {
+  private _includesTime = false
+  private _minDate?:    string
+  private _maxDate?:    string
+
+  static make(name: string): DateRangeFilter {
+    const f = new DateRangeFilter(name)
+    f.query((q: ModelQuery, value: string) => {
+      const { from, to } = parseDateRangeValue(value)
+      let next = q
+      if (from) next = next.where(f.name, '>=', from)
+      if (to)   next = next.where(f.name, '<=', to)
+      return next
+    })
+    return f
+  }
+
+  /** Switch the inputs to `<input type="datetime-local">` and the URL
+   *  values to ISO timestamps. Default: `false`. */
+  includesTime(value = true): this { this._includesTime = value; return this }
+
+  /** Lower bound for the input's `min` attribute. Accepts an ISO string or `Date`. */
+  minDate(value: string | Date): this {
+    this._minDate = toBoundString(value, this._includesTime)
+    return this
+  }
+
+  /** Upper bound for the input's `max` attribute. Accepts an ISO string or `Date`. */
+  maxDate(value: string | Date): this {
+    this._maxDate = toBoundString(value, this._includesTime)
+    return this
+  }
+
+  // Getters used by tests + the renderer.
+  getIncludesTime(): boolean             { return this._includesTime }
+  getMinDate():     string | undefined   { return this._minDate }
+  getMaxDate():     string | undefined   { return this._maxDate }
+
+  override getKind(): FilterKind { return 'dateRange' }
+
+  protected override formatActiveValue(value: string): string {
+    const { from, to } = parseDateRangeValue(value)
+    if (from && to) return `${from} → ${to}`
+    if (from)       return `≥ ${from}`
+    if (to)         return `≤ ${to}`
+    return value
+  }
+
+  override toMeta(): FilterMeta {
+    return {
+      ...this.buildBaseMeta(),
+      includesTime: this._includesTime,
+      ...(this._minDate !== undefined ? { minDate: this._minDate } : {}),
+      ...(this._maxDate !== undefined ? { maxDate: this._maxDate } : {}),
+      placeholder: this.getPlaceholder() ?? 'Any',
+    }
+  }
+}
+
+/** Coerce a `Date | string` bound to the canonical `YYYY-MM-DD` or
+ *  `YYYY-MM-DDTHH:mm` input-friendly string. Strings pass through
+ *  trimmed; the renderer's `min` / `max` attributes accept either. */
+function toBoundString(value: string | Date, includesTime: boolean): string {
+  if (typeof value === 'string') return value.trim()
+  // Use the local-time split so `<input type="date">` doesn't shift the
+  // bound a day under negative-UTC-offset clients.
+  const yyyy = value.getFullYear().toString().padStart(4, '0')
+  const mm   = (value.getMonth() + 1).toString().padStart(2, '0')
+  const dd   = value.getDate().toString().padStart(2, '0')
+  const date = `${yyyy}-${mm}-${dd}`
+  if (!includesTime) return date
+  const hh   = value.getHours().toString().padStart(2, '0')
+  const min  = value.getMinutes().toString().padStart(2, '0')
+  return `${date}T${hh}:${min}`
+}

package/src/filters/Filter.test.ts

@@ -0,0 +1,268 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Table } from '../elements/Table.js'
+import { Column } from '../Column.js'
+import { SelectFilter } from './SelectFilter.js'
+import { BooleanFilter, coerceBooleanFilterValue } from './BooleanFilter.js'
+import { TernaryFilter } from './TernaryFilter.js'
+import { DateRangeFilter } from './DateRangeFilter.js'
+import { parseFilterValues, loadTableRecords } from '../elements/dispatchTable.js'
+import { modelTableRecords } from '../orm/modelDefaults.js'
+import type { ModelLike, ModelQuery } from '../orm/modelDefaults.js'
+
+describe('SelectFilter / BooleanFilter shape', () => {
+  it('SelectFilter.toMeta emits kind:select + options + placeholder', () => {
+    const meta = SelectFilter.make('status')
+      .options([{ value: 'draft', label: 'Draft' }, { value: 'published', label: 'Published' }])
+      .toMeta()
+    assert.equal(meta.kind, 'select')
+    assert.equal(meta.name, 'status')
+    assert.equal(meta.label, 'Status')
+    assert.deepEqual(meta.options, [
+      { value: 'draft', label: 'Draft' },
+      { value: 'published', label: 'Published' },
+    ])
+    assert.equal(meta.placeholder, 'All')
+  })
+
+  it('BooleanFilter.toMeta emits kind:boolean + Any placeholder', () => {
+    const meta = BooleanFilter.make('featured').toMeta()
+    assert.equal(meta.kind, 'boolean')
+    assert.equal(meta.placeholder, 'Any')
+  })
+
+  it('label() override wins over the auto-derived label', () => {
+    assert.equal(SelectFilter.make('status').label('Publish state').toMeta().label, 'Publish state')
+  })
+
+  it('withValue mirrors current selection into meta', () => {
+    const meta = SelectFilter.make('status').withValue('published').toMeta()
+    assert.equal(meta.value, 'published')
+  })
+
+  it('coerceBooleanFilterValue maps string values to booleans', () => {
+    assert.equal(coerceBooleanFilterValue('1'),     true)
+    assert.equal(coerceBooleanFilterValue('true'),  true)
+    assert.equal(coerceBooleanFilterValue('yes'),   true)
+    assert.equal(coerceBooleanFilterValue('on'),    true)
+    assert.equal(coerceBooleanFilterValue('0'),     false)
+    assert.equal(coerceBooleanFilterValue('false'), false)
+    assert.equal(coerceBooleanFilterValue(''),      false)
+  })
+})
+
+describe('Filter.indicator + active-value formatting', () => {
+  it('omits indicator when no value is set', () => {
+    const meta = SelectFilter.make('status').toMeta()
+    assert.equal(meta.indicator, undefined)
+  })
+
+  it('SelectFilter formats active value via option label', () => {
+    const meta = SelectFilter.make('status')
+      .options([{ value: 'draft', label: 'Draft' }, { value: 'published', label: 'Published' }])
+      .withValue('published')
+      .toMeta()
+    assert.equal(meta.indicator, 'Status: Published')
+  })
+
+  it('SelectFilter falls back to raw value when option missing', () => {
+    const meta = SelectFilter.make('status').withValue('mystery').toMeta()
+    assert.equal(meta.indicator, 'Status: mystery')
+  })
+
+  it('BooleanFilter renders Yes / No', () => {
+    assert.equal(BooleanFilter.make('featured').withValue('1').toMeta().indicator,  'Featured: Yes')
+    assert.equal(BooleanFilter.make('featured').withValue('0').toMeta().indicator,  'Featured: No')
+  })
+
+  it('TernaryFilter maps yes / no / blank through the configured labels', () => {
+    const f = TernaryFilter.make('verified')
+      .trueLabel('Verified').falseLabel('Unverified').blankLabel('Pending')
+    assert.equal(f.withValue('yes').toMeta().indicator,   'Verified: Verified')
+    assert.equal(f.withValue('no').toMeta().indicator,    'Verified: Unverified')
+    assert.equal(f.withValue('blank').toMeta().indicator, 'Verified: Pending')
+  })
+
+  it('DateRangeFilter formats both / one-sided ranges', () => {
+    const f = DateRangeFilter.make('publishedAt')
+    assert.equal(f.withValue('2026-01-01..2026-12-31').toMeta().indicator, 'PublishedAt: 2026-01-01 → 2026-12-31')
+    assert.equal(f.withValue('2026-01-01..').toMeta().indicator,           'PublishedAt: ≥ 2026-01-01')
+    assert.equal(f.withValue('..2026-12-31').toMeta().indicator,           'PublishedAt: ≤ 2026-12-31')
+  })
+
+  it('Filter.indicator(string) is a literal override', () => {
+    const meta = SelectFilter.make('status')
+      .options([{ value: 'draft', label: 'Draft' }])
+      .indicator('Filtered')
+      .withValue('draft')
+      .toMeta()
+    assert.equal(meta.indicator, 'Filtered')
+  })
+
+  it('Filter.indicator(fn) receives value + filter for custom formatting', () => {
+    const meta = SelectFilter.make('status')
+      .label('Publish state')
+      .options([{ value: 'draft', label: 'Draft' }])
+      .indicator((v, f) => `${f.getLabel()} = ${v}`)
+      .withValue('draft')
+      .toMeta()
+    assert.equal(meta.indicator, 'Publish state = draft')
+  })
+})
+
+describe('Table.filters() + getFilters()', () => {
+  it('attaches filters as children alongside columns', () => {
+    const table = Table.make()
+      .columns([Column.make('title')])
+      .filters([SelectFilter.make('status'), BooleanFilter.make('featured')])
+    const filters = table.getFilters()
+    assert.equal(filters.length, 2)
+    assert.equal(filters[0]!.name, 'status')
+    assert.equal(filters[1]!.name, 'featured')
+    // Columns still present
+    assert.equal(table.getColumns().length, 1)
+  })
+
+  it('replacing filters does not clobber columns', () => {
+    const table = Table.make()
+      .columns([Column.make('title')])
+      .filters([SelectFilter.make('status')])
+      .filters([BooleanFilter.make('featured')])  // replace
+    assert.equal(table.getFilters().length, 1)
+    assert.equal(table.getFilters()[0]!.name, 'featured')
+    assert.equal(table.getColumns().length, 1)
+  })
+})
+
+describe('parseFilterValues', () => {
+  it('returns empty when no filters are registered', () => {
+    assert.deepEqual(parseFilterValues({ status: 'x' }, []), {})
+  })
+
+  it('drops reserved query keys + non-matching names', () => {
+    const filters = [SelectFilter.make('status'), BooleanFilter.make('featured')]
+    const r = parseFilterValues(
+      { status: 'published', featured: '1', search: 'hi', sort: 'title:asc', unknown: 'x' },
+      filters,
+    )
+    assert.deepEqual(r, { status: 'published', featured: '1' })
+  })
+
+  it('drops empty-string values', () => {
+    const filters = [SelectFilter.make('status')]
+    assert.deepEqual(parseFilterValues({ status: '' }, filters), {})
+  })
+})
+
+describe('loadTableRecords mirrors filter values + passes them in TableContext', () => {
+  it('Filter.withValue is called for each parsed filter, ctx.filters reaches the records handler', async () => {
+    let receivedCtx: unknown
+    const table = Table.make()
+      .columns([Column.make('title')])
+      .filters([
+        SelectFilter.make('status').options([{ value: 'published', label: 'Published' }]),
+        BooleanFilter.make('featured'),
+      ])
+      .records(async (ctx) => { receivedCtx = ctx; return { rows: [], total: 0 } })
+
+    await loadTableRecords([table], { status: 'published', featured: '1' })
+
+    const ctx = receivedCtx as { filters?: Record<string, string> }
+    assert.deepEqual(ctx.filters, { status: 'published', featured: '1' })
+
+    const filters = table.getFilters()
+    assert.equal(filters[0]!.getValue(), 'published')
+    assert.equal(filters[1]!.getValue(), '1')
+  })
+
+  it('omits ctx.filters when no filter values are present', async () => {
+    let receivedCtx: { filters?: unknown } = {}
+    const table = Table.make()
+      .columns([Column.make('title')])
+      .filters([SelectFilter.make('status')])
+      .records(async (ctx) => { receivedCtx = ctx; return { rows: [], total: 0 } })
+
+    await loadTableRecords([table], {})
+    assert.equal(receivedCtx.filters, undefined)
+  })
+})
+
+// ── modelTableRecords applies filter where-clauses ────────────────────
+
+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('modelTableRecords applies filters', () => {
+  it('select filter contributes a where(name, value) clause', async () => {
+    const M = fakeModel()
+    const table = Table.make()
+      .columns([Column.make('title')])
+      .filters([SelectFilter.make('status').options([{ value: 'published', label: 'Published' }])])
+    const handler = modelTableRecords(M, table)
+    await handler({ filters: { status: 'published' }, page: 1 })
+    const ops = M.lastQuery!.ops
+    assert.deepEqual(ops[0], { op: 'where', args: ['status', 'published'] })
+  })
+
+  it('boolean filter coerces the string value to a boolean', async () => {
+    const M = fakeModel()
+    const table = Table.make()
+      .columns([Column.make('title')])
+      .filters([BooleanFilter.make('featured')])
+    const handler = modelTableRecords(M, table)
+    await handler({ filters: { featured: '1' }, page: 1 })
+    const ops = M.lastQuery!.ops
+    assert.deepEqual(ops[0], { op: 'where', args: ['featured', true] })
+  })
+
+  it('Filter.query(fn) custom hook overrides the default where clause', async () => {
+    const M = fakeModel()
+    const table = Table.make()
+      .columns([Column.make('title')])
+      .filters([
+        SelectFilter.make('age').query((q, value) => q.where('age', '>=', Number(value))),
+      ])
+    const handler = modelTableRecords(M, table)
+    await handler({ filters: { age: '18' }, page: 1 })
+    const ops = M.lastQuery!.ops
+    assert.deepEqual(ops[0], { op: 'where', args: ['age', '>=', 18] })
+  })
+
+  it('skips filters with empty / undefined values', async () => {
+    const M = fakeModel()
+    const table = Table.make()
+      .columns([Column.make('title').searchable()])
+      .filters([SelectFilter.make('status')])
+    const handler = modelTableRecords(M, table)
+    await handler({ filters: { status: '' }, search: 'hi', page: 1 })
+    const ops = M.lastQuery!.ops
+    // Only the search clause + paginate, no status where.
+    assert.equal(ops.find(o => o.op === 'where' && (o.args as unknown[])[0] === 'status'), undefined)
+  })
+})

package/src/filters/Filter.ts

@@ -0,0 +1,184 @@
+import { Element, type ElementMeta } from '../schema/Element.js'
+import type { ModelQuery } from '../orm/modelDefaults.js'
+import type { RenderContext } from '../schema/resolveSchema.js'
+
+/**
+ * Discriminator for the renderer to pick a control.
+ *
+ * - `'select'`      — single-value dropdown (`SelectFilter`, `TrashedFilter`).
+ * - `'multiSelect'` — checkbox list; URL value is comma-separated.
+ * - `'boolean'`     — three-state yes/no/any.
+ * - `'ternary'`     — three-state with a meaningful "blank" (NULL) bucket.
+ * - `'dateRange'`   — pair of date / datetime inputs encoded as `from..to`.
+ * - `'form'`        — arbitrary-schema multi-field popover; URL value is
+ *                     a JSON-encoded object keyed by inner-field name.
+ * - `'queryBuilder'` — composable rules with per-column constraints; URL
+ *                     value is a JSON-encoded `{ operator, rules }` tree.
+ *
+ * Extends naturally — future kinds may include `'numberRange'`.
+ */
+export type FilterKind = 'select' | 'multiSelect' | 'boolean' | 'ternary' | 'dateRange' | 'form' | 'queryBuilder'
+
+export interface FilterMeta extends ElementMeta {
+  type:        'filter'
+  name:        string
+  label:       string
+  kind:        FilterKind
+  /** Currently-selected value, mirrored from the URL query at render time. */
+  value?:      string
+  /** Placeholder shown when no value is selected (e.g. "All", "Any"). */
+  placeholder?: string
+  /** Options for `kind === 'select' | 'multiSelect' | 'ternary'`. Boolean uses fixed yes/no. */
+  options?:    Array<{ value: string; label: string }>
+  /** `kind === 'dateRange'` — true switches the inputs to `datetime-local`. */
+  includesTime?: boolean
+  /** `kind === 'dateRange'` — clamp the inputs' `min` attribute. */
+  minDate?:    string
+  /** `kind === 'dateRange'` — clamp the inputs' `max` attribute. */
+  maxDate?:    string
+  /**
+   * `kind === 'form'` — resolved schema for the popover sub-form. Each
+   * field's `defaultValue` is pre-hydrated from the active URL value so
+   * the inputs round-trip across navigations.
+   */
+  formSchema?: ElementMeta[]
+  /**
+   * `kind === 'queryBuilder'` — declared constraints (one per queryable
+   * column) the user can pick from when adding a rule. Wire shape comes
+   * from `Constraint.toMeta()`.
+   */
+  constraints?: Array<Record<string, unknown>>
+  /**
+   * Active-filter indicator pill text. Present only when the filter has an
+   * active value. Default format is `"<label>: <displayValue>"`; users can
+   * override via `Filter.indicator(string | (value, filter) => string)`.
+   */
+  indicator?:  string
+}
+
+/**
+ * User-supplied query customizer. Receives the active filter value plus
+ * the running ORM query and returns the modified query. When supplied,
+ * `Filter.query(fn)` overrides the default `where(name, value)` clause.
+ */
+export type FilterQueryHandler = (query: ModelQuery, value: string) => ModelQuery
+
+/**
+ * User-supplied indicator-pill formatter. Receives the active value plus
+ * the filter so callbacks can read its label / option set. The default
+ * indicator is `"<label>: <displayValue>"` where `displayValue` comes from
+ * each subclass's `formatActiveValue` hook.
+ */
+export type FilterIndicatorHandler = (value: string, filter: Filter) => string
+
+/**
+ * Base class for table filters. Filters live as children of `Table` and
+ * surface as form controls in the table's header bar. Their values are
+ * carried through the URL query (`?status=published&featured=1`) and
+ * applied to the underlying ORM query for `Table.records`.
+ */
+export abstract class Filter extends Element {
+  readonly name: string
+  protected _label?: string
+  protected _value?: string
+  protected _queryFn?: FilterQueryHandler
+  protected _placeholder?: string
+  protected _indicatorFn?: FilterIndicatorHandler
+
+  protected constructor(name: string) {
+    super()
+    this.name = name
+  }
+
+  label(l: string): this { this._label = l; return this }
+
+  /** Override the placeholder shown when no value is selected. */
+  placeholder(p: string): this { this._placeholder = p; return this }
+
+  /**
+   * Override the default `where(name, value)` clause this filter
+   * contributes to the ORM query. Receives the current `ModelQuery` plus
+   * the active value and must return the modified query.
+   */
+  query(fn: FilterQueryHandler): this { this._queryFn = fn; return this }
+
+  /**
+   * Override the active-filter indicator pill text. Accepts either a
+   * literal string or a `(value, filter) => string` callback. The default
+   * indicator is `"<label>: <displayValue>"`, where `<displayValue>` comes
+   * from each subclass's `formatActiveValue(value)` hook (e.g. SelectFilter
+   * maps `'draft'` → its option label `'Draft'`).
+   */
+  indicator(fn: string | FilterIndicatorHandler): this {
+    this._indicatorFn = typeof fn === 'function' ? fn : () => fn
+    return this
+  }
+
+  /** Render-time setter: framework calls this with the URL-supplied value. */
+  withValue(v: string): this { this._value = v; return this }
+
+  // ─── Getters ──────────────────────────────────────────
+
+  getLabel(): string {
+    return this._label ?? this.name.charAt(0).toUpperCase() + this.name.slice(1)
+  }
+  getValue(): string | undefined            { return this._value }
+  getPlaceholder(): string | undefined      { return this._placeholder }
+  getQuery(): FilterQueryHandler | undefined { return this._queryFn }
+
+  abstract getKind(): FilterKind
+
+  /**
+   * Subclass hook — render the active value as a human-readable string for
+   * the indicator pill. Default is the raw value; SelectFilter/TernaryFilter
+   * map to option labels, BooleanFilter to "Yes"/"No", DateRangeFilter to a
+   * `from → to` range. Override when the URL value isn't user-friendly.
+   */
+  protected formatActiveValue(value: string): string { return value }
+
+  /**
+   * Render the indicator pill text. Returns `undefined` when no value is
+   * active so the renderer can skip the pill entirely. Honours the user's
+   * `indicator(fn)` override when supplied.
+   */
+  getIndicator(): string | undefined {
+    const value = this._value
+    if (value === undefined || value === '') return undefined
+    if (this._indicatorFn) return this._indicatorFn(value, this)
+    return `${this.getLabel()}: ${this.formatActiveValue(value)}`
+  }
+
+  // ─── Element contract ────────────────────────────────
+
+  getType(): string { return 'filter' }
+
+  /**
+   * Sync by default — `kind: 'form'` filters override to async because they
+   * need to resolve their inner schema. The optional `_ctx` parameter is
+   * threaded by `resolveSchema` so subclasses can read the active user /
+   * record / values when building their meta. Existing typed filters
+   * (Select / Boolean / Ternary / DateRange / MultiSelect / Trashed)
+   * ignore the parameter.
+   */
+  override toMeta(_ctx?: RenderContext): FilterMeta | Promise<FilterMeta> {
+    return this.buildBaseMeta()
+  }
+
+  /**
+   * Shared meta construction for `Filter` subclasses — exposed as a
+   * protected helper so async subclasses (e.g. `FormFilter`) can pull
+   * the same shape without spreading a `Promise<FilterMeta>` union.
+   */
+  protected buildBaseMeta(): FilterMeta {
+    const indicator = this.getIndicator()
+    return {
+      type:  'filter',
+      name:  this.name,
+      label: this.getLabel(),
+      kind:  this.getKind(),
+      ...(this._value       !== undefined ? { value:       this._value       } : {}),
+      ...(this._placeholder !== undefined ? { placeholder: this._placeholder } : {}),
+      ...(indicator         !== undefined ? { indicator                      } : {}),
+    }
+  }
+}