@pilotiq/pilotiq 0.1.0

package/src/filters/TrashedFilter.test.ts

@@ -0,0 +1,149 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { TrashedFilter } from './TrashedFilter.js'
+import type { FilterMeta } from './Filter.js'
+import { Table } from '../elements/Table.js'
+import { Resource } from '../Resource.js'
+import { applyTableDefaults } from '../defaultPages.js'
+import type { ModelQuery } from '../orm/modelDefaults.js'
+
+/** Stub query that records which trashed-scope methods got called. */
+function makeStubQuery() {
+  const calls: string[] = []
+  const q = {
+    where:    () => q,
+    orWhere:  () => q,
+    orderBy:  () => q,
+    paginate: async () => ({ data: [], total: 0 }),
+    withTrashed: () => { calls.push('withTrashed'); return q },
+    onlyTrashed: () => { calls.push('onlyTrashed'); return q },
+  } as unknown as ModelQuery
+  return { q, calls }
+}
+
+describe('TrashedFilter', () => {
+  it('default name is "trashed"', () => {
+    const f = TrashedFilter.make()
+    assert.equal(f.name, 'trashed')
+  })
+
+  it('accepts a custom URL key (e.g. archived)', () => {
+    const f = TrashedFilter.make('archived')
+    assert.equal(f.name, 'archived')
+  })
+
+  it('renders as a select kind with two options + "Active" placeholder', () => {
+    const meta = TrashedFilter.make().toMeta()
+    assert.equal(meta.kind, 'select')
+    assert.equal(meta.placeholder, 'Active')
+    assert.deepEqual(meta.options, [
+      { value: 'withTrashed', label: 'With trashed' },
+      { value: 'onlyTrashed', label: 'Only trashed' },
+    ])
+  })
+
+  it('value=withTrashed calls query.withTrashed()', () => {
+    const f = TrashedFilter.make()
+    const handler = f.getQuery()!
+    const { q, calls } = makeStubQuery()
+    handler(q, 'withTrashed')
+    assert.deepEqual(calls, ['withTrashed'])
+  })
+
+  it('value=onlyTrashed calls query.onlyTrashed()', () => {
+    const f = TrashedFilter.make()
+    const handler = f.getQuery()!
+    const { q, calls } = makeStubQuery()
+    handler(q, 'onlyTrashed')
+    assert.deepEqual(calls, ['onlyTrashed'])
+  })
+
+  it('empty / unknown value is a no-op (default scope already excludes trashed)', () => {
+    const f = TrashedFilter.make()
+    const handler = f.getQuery()!
+    const { q, calls } = makeStubQuery()
+    handler(q, '')
+    handler(q, 'active')
+    handler(q, 'garbage')
+    assert.deepEqual(calls, [])
+  })
+
+  it('gracefully no-ops when query lacks withTrashed (e.g. non-soft-delete query)', () => {
+    const f = TrashedFilter.make()
+    const handler = f.getQuery()!
+    const bareQ = {
+      where:    () => bareQ,
+      orWhere:  () => bareQ,
+      orderBy:  () => bareQ,
+      paginate: async () => ({ data: [], total: 0 }),
+    } as unknown as ModelQuery
+    const result = handler(bareQ, 'withTrashed')
+    assert.equal(result, bareQ, 'returns the query unchanged when withTrashed is absent')
+  })
+
+  it('label can be overridden via .label()', () => {
+    const f = TrashedFilter.make().label('Archive status')
+    assert.equal(f.toMeta().label, 'Archive status')
+  })
+})
+
+describe('applyTableDefaults — TrashedFilter auto-injection', () => {
+  it('auto-injects TrashedFilter when Resource.softDeletes = true', () => {
+    class R extends Resource {
+      static override label = 'Posts'
+      static override softDeletes = true
+    }
+    const table = R.table(Table.make())
+    applyTableDefaults(R, table)
+    const filters = table.getFilters()
+    assert.equal(filters.length, 1)
+    assert.ok(filters[0] instanceof TrashedFilter)
+  })
+
+  it('does not double-inject when the user already added a TrashedFilter', () => {
+    class R extends Resource {
+      static override label = 'Posts'
+      static override softDeletes = true
+      static override table(t: Table): Table {
+        return t.filters([TrashedFilter.make().label('Custom label')])
+      }
+    }
+    const table = R.table(Table.make())
+    applyTableDefaults(R, table)
+    const filters = table.getFilters()
+    assert.equal(filters.length, 1)
+    const meta = filters[0]!.toMeta() as FilterMeta
+    assert.equal(meta.label, 'Custom label',
+      'user-supplied filter wins over the auto-injected one')
+  })
+
+  it('does not inject when Resource.softDeletes = false (default)', () => {
+    class R extends Resource { static override label = 'Posts' }
+    const table = R.table(Table.make())
+    applyTableDefaults(R, table)
+    assert.equal(table.getFilters().length, 0)
+  })
+
+  it('preserves user-supplied non-trashed filters alongside the auto-injected one', async () => {
+    const { SelectFilter } = await import('./SelectFilter.js')
+    class R extends Resource {
+      static override label = 'Posts'
+      static override softDeletes = true
+      static override table(t: Table): Table {
+        return t.filters([
+          SelectFilter.make('status').options([
+            { value: 'draft',     label: 'Draft' },
+            { value: 'published', label: 'Published' },
+          ]),
+        ])
+      }
+    }
+    const table = R.table(Table.make())
+    applyTableDefaults(R, table)
+    const filters = table.getFilters()
+    assert.equal(filters.length, 2)
+    assert.equal(filters[0]!.name, 'status')
+    assert.ok(filters[1] instanceof TrashedFilter)
+  })
+})

package/src/filters/TrashedFilter.ts

@@ -0,0 +1,55 @@
+import { Filter, type FilterKind, type FilterMeta } from './Filter.js'
+import type { ModelQuery } from '../orm/modelDefaults.js'
+
+/**
+ * Plan #13 — three-state filter for soft-deleted resources.
+ *
+ *   `''` (default)    — active records only (default scope already
+ *                       excludes trashed; no clause added)
+ *   `'withTrashed'`   — active + trashed records together
+ *   `'onlyTrashed'`   — trashed records only
+ *
+ * Auto-injected on `ListPage` for resources with `softDeletes = true`
+ * unless the user attached one explicitly. URL key defaults to
+ * `?trashed=…`; rename via `TrashedFilter.make('archived')` for
+ * resources using a different column name (the URL key, not the
+ * predicate path — the predicate always calls `query.withTrashed() /
+ * onlyTrashed()` regardless of the filter's name).
+ *
+ * Renders as a `'select'` kind so the existing select-renderer handles
+ * it without changes. The default `query()` handler short-circuits to
+ * the running ORM query when `withTrashed / onlyTrashed` aren't on the
+ * `ModelQuery` (e.g. during testing with a stub query) — production
+ * paths always have them when the model has `softDeletes = true`.
+ */
+export class TrashedFilter extends Filter {
+  static make(name = 'trashed'): TrashedFilter {
+    const f = new TrashedFilter(name)
+    f.query((q: ModelQuery, value: string) => {
+      if (value === 'withTrashed' && typeof q.withTrashed === 'function') {
+        return q.withTrashed()
+      }
+      if (value === 'onlyTrashed' && typeof q.onlyTrashed === 'function') {
+        return q.onlyTrashed()
+      }
+      return q
+    })
+    return f
+  }
+
+  override getKind(): FilterKind { return 'select' }
+
+  override toMeta(): FilterMeta {
+    return {
+      ...this.buildBaseMeta(),
+      // Default-scope value (empty / "active only") is implicit — no
+      // option needed. Users select withTrashed / onlyTrashed to
+      // broaden; clearing the select returns to active-only.
+      options: [
+        { value: 'withTrashed', label: 'With trashed' },
+        { value: 'onlyTrashed', label: 'Only trashed' },
+      ],
+      placeholder: this.getPlaceholder() ?? 'Active',
+    }
+  }
+}

package/src/filters/queryBuilder/BooleanConstraint.ts

@@ -0,0 +1,31 @@
+import { Constraint, type ConstraintOperator, type ConstraintOperatorName } from './Constraint.js'
+import type { ModelQuery } from '../../orm/modelDefaults.js'
+
+const OPERATORS: ConstraintOperator[] = [
+  { name: 'isTrue',     label: 'Is true',      valueKind: 'none' },
+  { name: 'isFalse',    label: 'Is false',     valueKind: 'none' },
+  { name: 'isEmpty',    label: 'Is empty',     valueKind: 'none' },
+  { name: 'isNotEmpty', label: 'Is not empty', valueKind: 'none' },
+]
+
+/**
+ * Boolean-column constraint. No value input — every operator is binary.
+ * `isEmpty / isNotEmpty` exist for nullable boolean columns and rely on
+ * `ModelQuery.whereNull?` (mirrors `TernaryFilter`'s blank bucket).
+ */
+export class BooleanConstraint extends Constraint {
+  static make(name: string): BooleanConstraint { return new BooleanConstraint(name) }
+
+  override getOperators(): ConstraintOperator[] { return OPERATORS }
+
+  override apply(query: ModelQuery, operator: ConstraintOperatorName, _value: unknown): ModelQuery {
+    switch (operator) {
+      case 'isTrue':     return query.where(this.name, '=',  true)
+      case 'isFalse':    return query.where(this.name, '=',  false)
+      case 'isEmpty':
+        return typeof query.whereNull === 'function' ? query.whereNull(this.name) : query.where(this.name, '=', null)
+      case 'isNotEmpty': return query.where(this.name, '!=', null)
+      default:           return query
+    }
+  }
+}

package/src/filters/queryBuilder/Constraint.ts

@@ -0,0 +1,115 @@
+import type { ModelQuery } from '../../orm/modelDefaults.js'
+
+/**
+ * Wire-side discriminator for the value input the renderer mounts under
+ * a constraint row. `'none'` means the operator implies no value (e.g.
+ * `isEmpty / isNotEmpty / isTrue / isFalse`) — the renderer hides the
+ * value input entirely.
+ */
+export type ConstraintValueKind =
+  | 'text'
+  | 'number'
+  | 'date'
+  | 'dateTime'
+  | 'select'
+  | 'multiSelect'
+  | 'boolean'
+  | 'numberRange'
+  | 'dateRange'
+  | 'none'
+
+/**
+ * Canonical operator names a constraint advertises. The set is wider than
+ * any single subclass returns — each `Constraint` exposes its valid subset
+ * via `getOperators()`. Storage / URL value rules reference operators by
+ * this string.
+ */
+export type ConstraintOperatorName =
+  | 'equals' | 'notEquals'
+  | 'contains' | 'startsWith' | 'endsWith'
+  | 'lt' | 'lte' | 'gt' | 'gte' | 'between'
+  | 'before' | 'after' | 'dateBetween'
+  | 'in' | 'notIn'
+  | 'isEmpty' | 'isNotEmpty'
+  | 'isTrue' | 'isFalse'
+
+/** A single operator option with renderer-side label + value-input kind. */
+export interface ConstraintOperator {
+  name:      ConstraintOperatorName
+  label:     string
+  valueKind: ConstraintValueKind
+}
+
+/** Wire shape consumed by the renderer to mount a constraint row. */
+export interface ConstraintMeta {
+  name:       string
+  label:      string
+  operators:  ConstraintOperator[]
+  options?:   Array<{ value: string; label: string }>
+  /** Default operator pre-selected when the user adds a fresh row. */
+  defaultOperator?: ConstraintOperatorName
+}
+
+/**
+ * Base class for `QueryBuilder` constraints — declares which column the
+ * user can query, which operators they get, and how to translate a
+ * `(operator, value)` pair into ORM `where` clauses.
+ *
+ * Subclasses are typed value-objects (NOT `Element`) — they live as
+ * children of `QueryBuilderFilter.constraints([...])`, never standalone.
+ *
+ * The `apply()` contract takes a `ModelQuery` and returns it with any
+ * number of `.where()` calls chained on. v1 dispatches every rule through
+ * `.where()` (AND-root only) — see `QueryBuilderFilter` for the why.
+ */
+export abstract class Constraint {
+  readonly name: string
+  protected _label?: string
+
+  protected constructor(name: string) {
+    this.name = name
+  }
+
+  label(l: string): this { this._label = l; return this }
+
+  getLabel(): string {
+    return this._label ?? this.name.charAt(0).toUpperCase() + this.name.slice(1)
+  }
+
+  /** Operators this constraint advertises. Subclasses override. */
+  abstract getOperators(): ConstraintOperator[]
+
+  /** Default operator pre-selected on a fresh row. Defaults to first. */
+  getDefaultOperator(): ConstraintOperatorName {
+    const ops = this.getOperators()
+    return ops[0]?.name ?? 'equals'
+  }
+
+  /** Optional select-style options surfaced under `meta.options`. */
+  getOptions(): Array<{ value: string; label: string }> | undefined { return undefined }
+
+  /**
+   * Translate a single rule into ORM `where` clauses. Returns the modified
+   * query. Always called inside the QueryBuilder's AND-root pipeline in
+   * v1 — multi-clause operators (e.g. `between` → two `where` calls) are
+   * naturally AND'd by the running pipeline.
+   *
+   * Implementations should silently no-op on malformed values (return `q`
+   * unchanged). Throwing would abort the whole list query.
+   */
+  abstract apply(query: ModelQuery, operator: ConstraintOperatorName, value: unknown): ModelQuery
+
+  /** Wire shape consumed by the React renderer. */
+  toMeta(): ConstraintMeta {
+    const ops = this.getOperators()
+    const out: ConstraintMeta = {
+      name:            this.name,
+      label:           this.getLabel(),
+      operators:       ops,
+      defaultOperator: this.getDefaultOperator(),
+    }
+    const options = this.getOptions()
+    if (options) out.options = options
+    return out
+  }
+}

package/src/filters/queryBuilder/DateConstraint.ts

@@ -0,0 +1,69 @@
+import { Constraint, type ConstraintOperator, type ConstraintOperatorName } from './Constraint.js'
+import type { ModelQuery } from '../../orm/modelDefaults.js'
+
+/**
+ * Date-column constraint. `includesTime()` flips the value inputs to
+ * `datetime-local` and the wire `valueKind` to `'dateTime'`.
+ *
+ * Values arrive as ISO strings (`'2026-05-04'` / `'2026-05-04T13:00'`) and
+ * are passed through to the ORM as-is — Prisma / SQLite / MySQL all accept
+ * ISO strings on date columns.
+ */
+export class DateConstraint extends Constraint {
+  static make(name: string): DateConstraint { return new DateConstraint(name) }
+
+  private _includesTime = false
+
+  includesTime(v = true): this { this._includesTime = v; return this }
+
+  override getOperators(): ConstraintOperator[] {
+    const kind = this._includesTime ? 'dateTime' : 'date'
+    const range = this._includesTime ? 'dateTime' : 'dateRange'
+    return [
+      { name: 'equals',      label: 'On',          valueKind: kind  },
+      { name: 'before',      label: 'Before',      valueKind: kind  },
+      { name: 'after',       label: 'After',       valueKind: kind  },
+      { name: 'dateBetween', label: 'Between',     valueKind: range },
+      { name: 'isEmpty',     label: 'Is empty',    valueKind: 'none' },
+      { name: 'isNotEmpty',  label: 'Is not empty', valueKind: 'none' },
+    ]
+  }
+
+  override apply(query: ModelQuery, operator: ConstraintOperatorName, value: unknown): ModelQuery {
+    if (operator === 'isEmpty') {
+      return typeof query.whereNull === 'function' ? query.whereNull(this.name) : query.where(this.name, '=', null)
+    }
+    if (operator === 'isNotEmpty') {
+      return query.where(this.name, '!=', null)
+    }
+
+    if (operator === 'dateBetween') {
+      const [from, to] = parseDatePair(value)
+      if (from) query = query.where(this.name, '>=', from)
+      if (to)   query = query.where(this.name, '<=', to)
+      return query
+    }
+
+    const v = parseDate(value)
+    if (v === undefined) return query
+
+    switch (operator) {
+      case 'equals': return query.where(this.name, '=',  v)
+      case 'before': return query.where(this.name, '<',  v)
+      case 'after':  return query.where(this.name, '>',  v)
+      default:       return query
+    }
+  }
+}
+
+function parseDate(v: unknown): string | undefined {
+  if (v === null || v === undefined || v === '') return undefined
+  return String(v)
+}
+
+function parseDatePair(v: unknown): [string | undefined, string | undefined] {
+  if (Array.isArray(v)) {
+    return [parseDate(v[0]), parseDate(v[1])]
+  }
+  return [undefined, undefined]
+}

package/src/filters/queryBuilder/NumberConstraint.ts

@@ -0,0 +1,66 @@
+import { Constraint, type ConstraintOperator, type ConstraintOperatorName } from './Constraint.js'
+import type { ModelQuery } from '../../orm/modelDefaults.js'
+
+const OPERATORS: ConstraintOperator[] = [
+  { name: 'equals',     label: 'Equals',           valueKind: 'number' },
+  { name: 'notEquals',  label: 'Does not equal',   valueKind: 'number' },
+  { name: 'gt',         label: 'Greater than',     valueKind: 'number' },
+  { name: 'gte',        label: 'Greater or equal', valueKind: 'number' },
+  { name: 'lt',         label: 'Less than',        valueKind: 'number' },
+  { name: 'lte',        label: 'Less or equal',    valueKind: 'number' },
+  { name: 'between',    label: 'Between',          valueKind: 'numberRange' },
+  { name: 'isEmpty',    label: 'Is empty',         valueKind: 'none' },
+  { name: 'isNotEmpty', label: 'Is not empty',     valueKind: 'none' },
+]
+
+/**
+ * Numeric-column constraint. `between` takes a `[min, max]` tuple — both
+ * sides optional, missing side skipped (mirrors `DateRangeFilter`).
+ */
+export class NumberConstraint extends Constraint {
+  static make(name: string): NumberConstraint { return new NumberConstraint(name) }
+
+  override getOperators(): ConstraintOperator[] { return OPERATORS }
+
+  override apply(query: ModelQuery, operator: ConstraintOperatorName, value: unknown): ModelQuery {
+    if (operator === 'isEmpty') {
+      return typeof query.whereNull === 'function' ? query.whereNull(this.name) : query.where(this.name, '=', null)
+    }
+    if (operator === 'isNotEmpty') {
+      return query.where(this.name, '!=', null)
+    }
+
+    if (operator === 'between') {
+      const [min, max] = parseNumberPair(value)
+      if (min !== undefined) query = query.where(this.name, '>=', min)
+      if (max !== undefined) query = query.where(this.name, '<=', max)
+      return query
+    }
+
+    const n = parseNumber(value)
+    if (n === undefined) return query
+
+    switch (operator) {
+      case 'equals':    return query.where(this.name, '=',  n)
+      case 'notEquals': return query.where(this.name, '!=', n)
+      case 'gt':        return query.where(this.name, '>',  n)
+      case 'gte':       return query.where(this.name, '>=', n)
+      case 'lt':        return query.where(this.name, '<',  n)
+      case 'lte':       return query.where(this.name, '<=', n)
+      default:          return query
+    }
+  }
+}
+
+function parseNumber(v: unknown): number | undefined {
+  if (v === null || v === undefined || v === '') return undefined
+  const n = Number(v)
+  return Number.isFinite(n) ? n : undefined
+}
+
+function parseNumberPair(v: unknown): [number | undefined, number | undefined] {
+  if (Array.isArray(v)) {
+    return [parseNumber(v[0]), parseNumber(v[1])]
+  }
+  return [undefined, undefined]
+}

package/src/filters/queryBuilder/SelectConstraint.ts

@@ -0,0 +1,72 @@
+import { Constraint, type ConstraintOperator, type ConstraintOperatorName } from './Constraint.js'
+import type { ModelQuery } from '../../orm/modelDefaults.js'
+
+/**
+ * Enum-column constraint. Values come from a fixed `options([...])` list;
+ * the renderer mounts a single-select for `equals / notEquals` and a
+ * multi-select chip stack for `in / notIn`.
+ */
+export class SelectConstraint extends Constraint {
+  static make(name: string): SelectConstraint { return new SelectConstraint(name) }
+
+  private _options: Array<{ value: string; label: string }> = []
+
+  options(opts: Array<{ value: string; label: string }>): this {
+    this._options = opts
+    return this
+  }
+
+  override getOptions(): Array<{ value: string; label: string }> | undefined {
+    return this._options.length > 0 ? this._options : undefined
+  }
+
+  override getOperators(): ConstraintOperator[] {
+    return [
+      { name: 'equals',     label: 'Equals',           valueKind: 'select' },
+      { name: 'notEquals',  label: 'Does not equal',   valueKind: 'select' },
+      { name: 'in',         label: 'Is one of',        valueKind: 'multiSelect' },
+      { name: 'notIn',      label: 'Is not one of',    valueKind: 'multiSelect' },
+      { name: 'isEmpty',    label: 'Is empty',         valueKind: 'none' },
+      { name: 'isNotEmpty', label: 'Is not empty',     valueKind: 'none' },
+    ]
+  }
+
+  override apply(query: ModelQuery, operator: ConstraintOperatorName, value: unknown): ModelQuery {
+    if (operator === 'isEmpty') {
+      return typeof query.whereNull === 'function' ? query.whereNull(this.name) : query.where(this.name, '=', null)
+    }
+    if (operator === 'isNotEmpty') {
+      return query.where(this.name, '!=', null)
+    }
+
+    if (operator === 'in' || operator === 'notIn') {
+      const list = parseList(value)
+      if (list.length === 0) return query
+      return query.where(this.name, operator === 'in' ? 'IN' : 'NOT IN', list)
+    }
+
+    const v = parseScalar(value)
+    if (v === undefined) return query
+
+    switch (operator) {
+      case 'equals':    return query.where(this.name, '=',  v)
+      case 'notEquals': return query.where(this.name, '!=', v)
+      default:          return query
+    }
+  }
+}
+
+function parseScalar(v: unknown): string | undefined {
+  if (v === null || v === undefined || v === '') return undefined
+  return String(v)
+}
+
+function parseList(v: unknown): string[] {
+  if (!Array.isArray(v)) return []
+  const out: string[] = []
+  for (const item of v) {
+    if (item === null || item === undefined || item === '') continue
+    out.push(String(item))
+  }
+  return out
+}

package/src/filters/queryBuilder/TextConstraint.ts

@@ -0,0 +1,65 @@
+import { Constraint, type ConstraintOperator, type ConstraintOperatorName } from './Constraint.js'
+import type { ModelQuery } from '../../orm/modelDefaults.js'
+
+// `notContains` is intentionally omitted in v1 — the rudder Prisma adapter
+// doesn't translate `NOT LIKE` (only `LIKE`). Re-add once the adapter
+// learns negation, mirrored on the pilotiq `ModelWhereOperator` union.
+const OPERATORS: ConstraintOperator[] = [
+  { name: 'contains',     label: 'Contains',         valueKind: 'text' },
+  { name: 'equals',       label: 'Equals',           valueKind: 'text' },
+  { name: 'notEquals',    label: 'Does not equal',   valueKind: 'text' },
+  { name: 'startsWith',   label: 'Starts with',      valueKind: 'text' },
+  { name: 'endsWith',     label: 'Ends with',        valueKind: 'text' },
+  { name: 'isEmpty',      label: 'Is empty',         valueKind: 'none' },
+  { name: 'isNotEmpty',   label: 'Is not empty',     valueKind: 'none' },
+]
+
+/**
+ * String-column constraint. Default operator is `'contains'` because text
+ * filters in admin tables almost always want substring search rather than
+ * exact match.
+ *
+ * `isEmpty / isNotEmpty` rely on `ModelQuery.whereNull?` (added for
+ * `TernaryFilter`). When unavailable they fall back to `where(name, '')`
+ * which still catches the common case for non-NULL string columns.
+ */
+export class TextConstraint extends Constraint {
+  static make(name: string): TextConstraint { return new TextConstraint(name) }
+
+  override getOperators(): ConstraintOperator[] { return OPERATORS }
+
+  override getDefaultOperator(): ConstraintOperatorName { return 'contains' }
+
+  override apply(query: ModelQuery, operator: ConstraintOperatorName, value: unknown): ModelQuery {
+    if (operator === 'isEmpty')    return whereNullOrEmpty(query, this.name)
+    if (operator === 'isNotEmpty') return whereNotNullAndNotEmpty(query, this.name)
+
+    const v = value === null || value === undefined ? '' : String(value)
+    if (v === '') return query
+
+    switch (operator) {
+      case 'contains':    return query.where(this.name, 'LIKE', `%${escapeLike(v)}%`)
+      case 'startsWith':  return query.where(this.name, 'LIKE', `${escapeLike(v)}%`)
+      case 'endsWith':    return query.where(this.name, 'LIKE', `%${escapeLike(v)}`)
+      case 'equals':      return query.where(this.name, '=', v)
+      case 'notEquals':   return query.where(this.name, '!=', v)
+      default:            return query
+    }
+  }
+}
+
+function whereNullOrEmpty(q: ModelQuery, col: string): ModelQuery {
+  if (typeof q.whereNull === 'function') {
+    return q.whereNull(col).orWhere(col, '=', '')
+  }
+  return q.where(col, '=', '')
+}
+
+function whereNotNullAndNotEmpty(q: ModelQuery, col: string): ModelQuery {
+  return q.where(col, '!=', '')
+}
+
+/** Escape SQL `LIKE` wildcards in user input. Mirrors `unique` validator. */
+function escapeLike(input: string): string {
+  return input.replace(/\\/g, '\\\\').replace(/%/g, '\\%').replace(/_/g, '\\_')
+}

package/src/filters/queryBuilder/index.ts

@@ -0,0 +1,12 @@
+export {
+  Constraint,
+  type ConstraintMeta,
+  type ConstraintOperator,
+  type ConstraintOperatorName,
+  type ConstraintValueKind,
+} from './Constraint.js'
+export { TextConstraint }    from './TextConstraint.js'
+export { NumberConstraint }  from './NumberConstraint.js'
+export { DateConstraint }    from './DateConstraint.js'
+export { SelectConstraint }  from './SelectConstraint.js'
+export { BooleanConstraint } from './BooleanConstraint.js'

package/src/icons/index.ts

@@ -0,0 +1,2 @@
+export { registerIcons, getIcon, type IconType, type IconMap } from './registry.js'
+export { type IconValue, type SerializedIcon, serializeIcon } from './types.js'