@pilotiq/pilotiq 0.1.0

package/src/fields/disableOptionsWhenSelectedInSiblingRepeaterItems.test.ts

@@ -0,0 +1,319 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { SelectField } from './SelectField.js'
+import { RadioField } from './RadioField.js'
+import { CheckboxListField } from './CheckboxListField.js'
+import { ToggleButtonsField } from './ToggleButtonsField.js'
+import { TextField } from './TextField.js'
+import { RepeaterField, type RepeaterFieldMeta } from './RepeaterField.js'
+import { BuilderField, type BuilderFieldMeta } from './BuilderField.js'
+import { Block } from '../schema/Block.js'
+import { resolveSchema } from '../schema/resolveSchema.js'
+import { disableOptionsTakenInSiblings, type SelectOption } from './optionsResolver.js'
+
+const colours = [
+  { value: 'red',   label: 'Red'   },
+  { value: 'green', label: 'Green' },
+  { value: 'blue',  label: 'Blue'  },
+]
+
+function rowOptions(meta: RepeaterFieldMeta | BuilderFieldMeta, rowIdx: number, fieldName: string): SelectOption[] {
+  const row = meta.rows[rowIdx]
+  if (!row) throw new Error(`row ${rowIdx} missing`)
+  const child = row.children.find(c => c['name'] === fieldName)
+  if (!child) throw new Error(`field "${fieldName}" missing in row ${rowIdx}`)
+  return (child['options'] as SelectOption[]) ?? []
+}
+
+describe('disableOptionsWhenSelectedInSiblingRepeaterItems', () => {
+  describe('flag plumbing', () => {
+    it('default is disabled', () => {
+      const f = SelectField.make('color')
+      assert.equal(f.shouldDisableOptionsTakenInSiblings(), false)
+    })
+
+    it('enables flag + auto-arms distinct() and live()', () => {
+      const f = SelectField.make('color').disableOptionsWhenSelectedInSiblingRepeaterItems()
+      assert.equal(f.shouldDisableOptionsTakenInSiblings(), true)
+      assert.notEqual(f.getDistinct(), undefined)
+      assert.equal(f.isLive(), true)
+    })
+
+    it('disableOptionsWhenSelectedInSiblingRepeaterItems(false) clears the flag', () => {
+      const f = SelectField.make('color').disableOptionsWhenSelectedInSiblingRepeaterItems()
+        .disableOptionsWhenSelectedInSiblingRepeaterItems(false)
+      assert.equal(f.shouldDisableOptionsTakenInSiblings(), false)
+    })
+
+    it('available on Radio / CheckboxList / ToggleButtons too', () => {
+      assert.equal(
+        RadioField.make('x').disableOptionsWhenSelectedInSiblingRepeaterItems().shouldDisableOptionsTakenInSiblings(),
+        true,
+      )
+      assert.equal(
+        CheckboxListField.make('x').disableOptionsWhenSelectedInSiblingRepeaterItems().shouldDisableOptionsTakenInSiblings(),
+        true,
+      )
+      assert.equal(
+        ToggleButtonsField.make('x').disableOptionsWhenSelectedInSiblingRepeaterItems().shouldDisableOptionsTakenInSiblings(),
+        true,
+      )
+    })
+  })
+
+  describe('disableOptionsTakenInSiblings helper', () => {
+    it('no-op when disabled', () => {
+      const out = disableOptionsTakenInSiblings(colours, false, 'color', { row: { index: 0, $get: () => undefined, $set: () => {}, siblings: [{ color: 'red' }] } })
+      assert.deepEqual(out, colours)
+    })
+
+    it('no-op without row.siblings (top-level form)', () => {
+      const out = disableOptionsTakenInSiblings(colours, true, 'color', undefined)
+      assert.deepEqual(out, colours)
+    })
+
+    it('marks taken values disabled', () => {
+      const out = disableOptionsTakenInSiblings(colours, true, 'color', {
+        row: { index: 1, $get: () => undefined, $set: () => {}, siblings: [{ color: 'red' }] },
+      })
+      assert.equal(out[0]?.disabled, true)   // red is taken
+      assert.equal(out[1]?.disabled, undefined)
+      assert.equal(out[2]?.disabled, undefined)
+    })
+
+    it('skips empty / null sibling values', () => {
+      const out = disableOptionsTakenInSiblings(colours, true, 'color', {
+        row: {
+          index: 1,
+          $get: () => undefined,
+          $set: () => {},
+          siblings: [{ color: '' }, { color: null }, { color: undefined }, { other: 'red' }],
+        },
+      })
+      assert.equal(out[0]?.disabled, undefined)
+      assert.equal(out[1]?.disabled, undefined)
+    })
+
+    it('unfolds array sibling values (CheckboxList semantics)', () => {
+      const out = disableOptionsTakenInSiblings(colours, true, 'tags', {
+        row: { index: 1, $get: () => undefined, $set: () => {}, siblings: [{ tags: ['red', 'blue'] }] },
+      })
+      assert.equal(out[0]?.disabled, true)
+      assert.equal(out[1]?.disabled, undefined)
+      assert.equal(out[2]?.disabled, true)
+    })
+
+    it('preserves user-set option.disabled (does not toggle it back to undefined)', () => {
+      const opts: SelectOption[] = [
+        { value: 'red', label: 'Red', disabled: true },
+        { value: 'green', label: 'Green' },
+      ]
+      const out = disableOptionsTakenInSiblings(opts, true, 'color', {
+        row: { index: 1, $get: () => undefined, $set: () => {}, siblings: [{ color: 'green' }] },
+      })
+      assert.equal(out[0]?.disabled, true)   // user-set, untouched
+      assert.equal(out[1]?.disabled, true)   // newly taken
+    })
+  })
+
+  describe('inside Repeater', () => {
+    function makeRep() {
+      return RepeaterField.make('picks').schema([
+        SelectField.make('color')
+          .options(colours)
+          .disableOptionsWhenSelectedInSiblingRepeaterItems(),
+      ])
+    }
+
+    it('first row sees all options enabled when no sibling has picked', async () => {
+      const [raw] = await resolveSchema([makeRep()], {
+        values: { picks: [{ color: '' }, { color: '' }] },
+      })
+      const m = raw as RepeaterFieldMeta
+      assert.equal(rowOptions(m, 0, 'color').every(o => !o.disabled), true)
+      assert.equal(rowOptions(m, 1, 'color').every(o => !o.disabled), true)
+    })
+
+    it('when row 0 picks "red", row 1 sees red disabled', async () => {
+      const [raw] = await resolveSchema([makeRep()], {
+        values: { picks: [{ color: 'red' }, { color: '' }] },
+      })
+      const m = raw as RepeaterFieldMeta
+      const row1 = rowOptions(m, 1, 'color')
+      assert.equal(row1.find(o => o.value === 'red')?.disabled, true)
+      assert.equal(row1.find(o => o.value === 'green')?.disabled, undefined)
+      assert.equal(row1.find(o => o.value === 'blue')?.disabled, undefined)
+    })
+
+    it('the picking row keeps its own pick selectable (not disabled by self)', async () => {
+      const [raw] = await resolveSchema([makeRep()], {
+        values: { picks: [{ color: 'red' }, { color: 'green' }] },
+      })
+      const m = raw as RepeaterFieldMeta
+      // Row 0 sees its own red as enabled (siblings = [{green}])
+      assert.equal(rowOptions(m, 0, 'color').find(o => o.value === 'red')?.disabled, undefined)
+      // Row 1 sees its own green as enabled (siblings = [{red}])
+      assert.equal(rowOptions(m, 1, 'color').find(o => o.value === 'green')?.disabled, undefined)
+      // … but the OTHER row's pick is disabled
+      assert.equal(rowOptions(m, 0, 'color').find(o => o.value === 'green')?.disabled, true)
+      assert.equal(rowOptions(m, 1, 'color').find(o => o.value === 'red')?.disabled, true)
+    })
+
+    it('flag off → no options ever disabled (sanity check)', async () => {
+      const f = RepeaterField.make('picks').schema([
+        SelectField.make('color').options(colours), // no disable flag
+      ])
+      const [raw] = await resolveSchema([f], {
+        values: { picks: [{ color: 'red' }, { color: '' }] },
+      })
+      const m = raw as RepeaterFieldMeta
+      assert.equal(rowOptions(m, 1, 'color').find(o => o.value === 'red')?.disabled, undefined)
+    })
+
+    it('CheckboxList — sibling array values mark each entry disabled', async () => {
+      const f = RepeaterField.make('groups').schema([
+        CheckboxListField.make('tags')
+          .options(colours)
+          .disableOptionsWhenSelectedInSiblingRepeaterItems(),
+      ])
+      const [raw] = await resolveSchema([f], {
+        values: { groups: [{ tags: ['red', 'blue'] }, { tags: [] }] },
+      })
+      const m = raw as RepeaterFieldMeta
+      const row1 = rowOptions(m, 1, 'tags')
+      assert.equal(row1.find(o => o.value === 'red')?.disabled, true)
+      assert.equal(row1.find(o => o.value === 'blue')?.disabled, true)
+      assert.equal(row1.find(o => o.value === 'green')?.disabled, undefined)
+    })
+
+    it('Radio + ToggleButtons honor the flag the same way', async () => {
+      const f = RepeaterField.make('rows').schema([
+        RadioField.make('r').options(colours).disableOptionsWhenSelectedInSiblingRepeaterItems(),
+        ToggleButtonsField.make('t').options(colours).disableOptionsWhenSelectedInSiblingRepeaterItems(),
+      ])
+      const [raw] = await resolveSchema([f], {
+        values: { rows: [{ r: 'red', t: 'blue' }, { r: '', t: '' }] },
+      })
+      const m = raw as RepeaterFieldMeta
+      assert.equal(rowOptions(m, 1, 'r').find(o => o.value === 'red')?.disabled, true)
+      assert.equal(rowOptions(m, 1, 't').find(o => o.value === 'blue')?.disabled, true)
+    })
+
+    it('top-level (non-Repeater) Select with the flag set is a no-op', async () => {
+      const top = SelectField.make('color').options(colours).disableOptionsWhenSelectedInSiblingRepeaterItems()
+      const [raw] = await resolveSchema([top], { values: { color: 'red' } })
+      const opts = (raw?.['options'] as SelectOption[]) ?? []
+      assert.equal(opts.every(o => !o.disabled), true)
+    })
+
+    it('zero submitted rows + defaultItems → no errors, options all enabled', async () => {
+      const [raw] = await resolveSchema([makeRep().defaultItems(2)])
+      const m = raw as RepeaterFieldMeta
+      // Two empty default rows; nobody has picked anything yet.
+      assert.equal(rowOptions(m, 0, 'color').every(o => !o.disabled), true)
+      assert.equal(rowOptions(m, 1, 'color').every(o => !o.disabled), true)
+    })
+  })
+
+  describe('inside Builder (per-block-type scoping)', () => {
+    function makeBuilder() {
+      return BuilderField.make('blocks').blocks([
+        Block.make('hero').schema([
+          SelectField.make('layout').options([
+            { value: 'left',  label: 'Left'  },
+            { value: 'right', label: 'Right' },
+          ]).disableOptionsWhenSelectedInSiblingRepeaterItems(),
+        ]),
+        Block.make('cta').schema([
+          // Same field name on a different block type — must NOT shadow.
+          SelectField.make('layout').options([
+            { value: 'left',  label: 'Left'  },
+            { value: 'right', label: 'Right' },
+          ]).disableOptionsWhenSelectedInSiblingRepeaterItems(),
+        ]),
+      ])
+    }
+
+    it('same-type sibling pick disables the option on the next same-type row', async () => {
+      const [raw] = await resolveSchema([makeBuilder()], {
+        values: { blocks: [
+          { type: 'hero', data: { layout: 'left' } },
+          { type: 'hero', data: { layout: '' } },
+        ] },
+      })
+      const m = raw as BuilderFieldMeta
+      const row1 = rowOptions(m, 1, 'layout')
+      assert.equal(row1.find(o => o.value === 'left')?.disabled, true)
+      assert.equal(row1.find(o => o.value === 'right')?.disabled, undefined)
+    })
+
+    it('different block types DO NOT shadow each other (cross-block isolation)', async () => {
+      const [raw] = await resolveSchema([makeBuilder()], {
+        values: { blocks: [
+          { type: 'hero', data: { layout: 'left' } },
+          { type: 'cta',  data: { layout: '' } },
+        ] },
+      })
+      const m = raw as BuilderFieldMeta
+      // The cta row at index 1 is a different block — its `layout` is its
+      // own namespace. None of its options should be disabled by the hero
+      // row's pick.
+      const row1 = rowOptions(m, 1, 'layout')
+      assert.equal(row1.every(o => !o.disabled), true)
+    })
+
+    it('three rows, two same-type → only the third sees both prior picks disabled', async () => {
+      const [raw] = await resolveSchema([makeBuilder()], {
+        values: { blocks: [
+          { type: 'hero', data: { layout: 'left'  } },
+          { type: 'hero', data: { layout: 'right' } },
+          { type: 'hero', data: { layout: ''      } },
+        ] },
+      })
+      const m = raw as BuilderFieldMeta
+      const row2 = rowOptions(m, 2, 'layout')
+      assert.equal(row2.find(o => o.value === 'left')?.disabled, true)
+      assert.equal(row2.find(o => o.value === 'right')?.disabled, true)
+    })
+  })
+
+  describe('static option.disabled is preserved alongside taken-disabled', () => {
+    it('user-set disabled stays even when not taken', async () => {
+      const f = RepeaterField.make('picks').schema([
+        SelectField.make('color')
+          .options([
+            { value: 'red',   label: 'Red'   },
+            { value: 'green', label: 'Green', disabled: true },
+            { value: 'blue',  label: 'Blue'  },
+          ])
+          .disableOptionsWhenSelectedInSiblingRepeaterItems(),
+      ])
+      const [raw] = await resolveSchema([f], {
+        values: { picks: [{ color: 'red' }, { color: '' }] },
+      })
+      const m = raw as RepeaterFieldMeta
+      const row1 = rowOptions(m, 1, 'color')
+      assert.equal(row1.find(o => o.value === 'red')?.disabled, true)    // taken
+      assert.equal(row1.find(o => o.value === 'green')?.disabled, true)  // user-set
+      assert.equal(row1.find(o => o.value === 'blue')?.disabled, undefined)
+    })
+  })
+
+  describe('cross-row interaction with non-option fields', () => {
+    it('coexists with sibling fields that are not option-bearing', async () => {
+      const f = RepeaterField.make('rows').schema([
+        TextField.make('title'),
+        SelectField.make('color').options(colours).disableOptionsWhenSelectedInSiblingRepeaterItems(),
+      ])
+      const [raw] = await resolveSchema([f], {
+        values: { rows: [
+          { title: 'A', color: 'red' },
+          { title: 'B', color: '' },
+        ] },
+      })
+      const m = raw as RepeaterFieldMeta
+      assert.equal(rowOptions(m, 1, 'color').find(o => o.value === 'red')?.disabled, true)
+    })
+  })
+})

package/src/fields/optionsResolver.ts

@@ -0,0 +1,95 @@
+import type { RenderContext } from '../schema/resolveSchema.js'
+
+/**
+ * Shape of an option in a SelectField / Radio / CheckboxList.
+ * `value` round-trips through the form body; `label` is display only.
+ *
+ * `disabled` greys the option out and blocks selection. Stamped server-side
+ * by `disableOptionsWhenSelectedInSiblingRepeaterItems()` for options taken
+ * in sibling Repeater/Builder rows; users may also set it themselves on the
+ * static option list to express "this choice is permanently unavailable".
+ */
+export type SelectOption = { value: string; label: string; disabled?: boolean }
+
+/**
+ * Reactive options resolver. Receives the same `{ $get, $set, record,
+ * user, values }` ctx that `afterStateUpdated` sees, runs every resolve
+ * cycle, and may be async (for DB-backed lookups). Throws are swallowed
+ * to an empty array + console.warn — the field still renders, just with
+ * no choices.
+ *
+ * Used by SelectField, Radio, CheckboxList. Each calls `resolveOptions`
+ * from inside its async `toMeta` so the resolver runs at the same point
+ * in the render cycle for every dependent-options field type.
+ */
+export type OptionsResolver = (ctx: {
+  $get?:    (name: string) => unknown
+  $set?:    (name: string, value: unknown) => void
+  record?:  unknown
+  user?:    unknown
+  values?:  Record<string, unknown>
+}) => SelectOption[] | Promise<SelectOption[]>
+
+/**
+ * Resolve a `SelectOption[] | OptionsResolver` source against the
+ * current render context. Returns the resolved option array, or `[]`
+ * with a `console.warn` when the resolver throws — failure should
+ * never crash a form render.
+ */
+export async function resolveOptions(
+  source:    SelectOption[] | OptionsResolver,
+  ctx:       RenderContext | undefined,
+  fieldName: string,
+): Promise<SelectOption[]> {
+  if (Array.isArray(source)) return source
+  try {
+    return await source({
+      ...(ctx?.$get   ? { $get:   ctx.$get   } : {}),
+      ...(ctx?.$set   ? { $set:   ctx.$set   } : {}),
+      ...(ctx?.record !== undefined ? { record: ctx.record } : {}),
+      ...(ctx?.user   !== undefined ? { user:   ctx.user   } : {}),
+      ...(ctx?.values ? { values: ctx.values } : {}),
+    })
+  } catch (err) {
+    console.warn(`[pilotiq] options() resolver for "${fieldName}" threw:`, err)
+    return []
+  }
+}
+
+/**
+ * Apply the "disable options taken in sibling Repeater/Builder rows" gate.
+ * No-op outside an array-row context (no `ctx.row.siblings`) or when the
+ * field hasn't opted in. Builder scoping (same-block-type only) is handled
+ * by the resolver — by the time we get here, `ctx.row.siblings` already
+ * reflects the right scope.
+ *
+ * Multi-value sibling rows (e.g. `CheckboxList` storing `string[]`) unfold
+ * into individual taken values; single-value rows contribute one taken
+ * entry. Empty / null / `''` sibling values are skipped (they aren't real
+ * picks yet — same posture as `Field.distinct()`'s default `ignoreNulls`).
+ */
+export function disableOptionsTakenInSiblings(
+  options:   SelectOption[],
+  enabled:   boolean,
+  fieldName: string,
+  ctx:       RenderContext | undefined,
+): SelectOption[] {
+  if (!enabled) return options
+  const siblings = ctx?.row?.siblings
+  if (!siblings || siblings.length === 0) return options
+  const taken = new Set<string>()
+  for (const sib of siblings) {
+    if (!sib || typeof sib !== 'object') continue
+    const v = (sib as Record<string, unknown>)[fieldName]
+    if (Array.isArray(v)) {
+      for (const x of v) {
+        if (x === undefined || x === null || x === '') continue
+        taken.add(String(x))
+      }
+    } else if (v !== undefined && v !== null && v !== '') {
+      taken.add(String(v))
+    }
+  }
+  if (taken.size === 0) return options
+  return options.map(o => (taken.has(o.value) && !o.disabled ? { ...o, disabled: true } : o))
+}

package/src/fields/resolveField.ts

@@ -0,0 +1,28 @@
+import type { Field, FieldMeta } from './Field.js'
+import type { RenderContext } from '../schema/resolveSchema.js'
+
+/**
+ * Resolve a single Field against a render context.
+ *
+ * Returns `null` if the field should be hidden — visibility flags
+ * (`hideFromTable` / `hideFromCreate` / etc.) and condition callbacks
+ * (`showWhen` / `hideWhen`) are evaluated server-side. The serialized meta
+ * never includes a hidden field.
+ *
+ * Async because reactive Field subclasses (Plan #5 — `SelectField` with
+ * a resolver-style `options(fn)`) may compute meta asynchronously.
+ */
+export async function resolveField(field: Field, ctx: RenderContext = {}): Promise<FieldMeta | null> {
+  if (field.isHiddenIn(ctx)) return null
+  return await field.toMeta(ctx)
+}
+
+/**
+ * Resolve an array of Fields, dropping any that are hidden for the current
+ * context. Used by `Resource.form()` / `Resource.table()` paths until 1.3
+ * unifies Fields under the schema-element resolver.
+ */
+export async function resolveFields(fields: Field[], ctx: RenderContext = {}): Promise<FieldMeta[]> {
+  const metas = await Promise.all(fields.map(f => resolveField(f, ctx)))
+  return metas.filter((m): m is FieldMeta => m !== null)
+}

package/src/filters/BooleanFilter.ts

@@ -0,0 +1,35 @@
+import { Filter, type FilterKind, type FilterMeta } from './Filter.js'
+
+/**
+ * Three-state filter: yes / no / any. Renders as a dropdown. When a
+ * value is selected, contributes `where(name, true|false)` to the
+ * underlying ORM query — values `'1'` and `'true'` map to `true`,
+ * everything else to `false`. The empty value means "any" (no clause
+ * applied).
+ *
+ * @example
+ * BooleanFilter.make('featured').label('Featured only')
+ */
+export class BooleanFilter extends Filter {
+  static make(name: string): BooleanFilter {
+    return new BooleanFilter(name)
+  }
+
+  override getKind(): FilterKind { return 'boolean' }
+
+  protected override formatActiveValue(value: string): string {
+    return coerceBooleanFilterValue(value) ? 'Yes' : 'No'
+  }
+
+  override toMeta(): FilterMeta {
+    return {
+      ...this.buildBaseMeta(),
+      placeholder: this.getPlaceholder() ?? 'Any',
+    }
+  }
+}
+
+/** Coerce a URL-string filter value to a boolean. */
+export function coerceBooleanFilterValue(value: string): boolean {
+  return value === '1' || value === 'true' || value === 'yes' || value === 'on'
+}

package/src/filters/DateRangeFilter.test.ts

@@ -0,0 +1,194 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Table } from '../elements/Table.js'
+import { Column } from '../Column.js'
+import {
+  DateRangeFilter,
+  parseDateRangeValue,
+  encodeDateRangeValue,
+} from './DateRangeFilter.js'
+import { modelTableRecords } from '../orm/modelDefaults.js'
+import type { ModelLike, ModelQuery } 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() { this.ops.push({ op: 'paginate', args: [] }); 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('parseDateRangeValue', () => {
+  it('round-trips a closed range', () => {
+    assert.deepEqual(
+      parseDateRangeValue('2026-01-01..2026-12-31'),
+      { from: '2026-01-01', to: '2026-12-31' },
+    )
+  })
+
+  it('round-trips an open-from range', () => {
+    assert.deepEqual(parseDateRangeValue('2026-01-01..'), { from: '2026-01-01' })
+  })
+
+  it('round-trips an open-to range', () => {
+    assert.deepEqual(parseDateRangeValue('..2026-12-31'), { to: '2026-12-31' })
+  })
+
+  it('treats empty / `..` as the empty range', () => {
+    assert.deepEqual(parseDateRangeValue(''),    {})
+    assert.deepEqual(parseDateRangeValue('..'),  {})
+  })
+
+  it('treats a missing separator as a single from bound', () => {
+    assert.deepEqual(parseDateRangeValue('2026-01-01'), { from: '2026-01-01' })
+  })
+
+  it('trims whitespace on both sides', () => {
+    assert.deepEqual(
+      parseDateRangeValue('  2026-01-01 .. 2026-12-31  '),
+      { from: '2026-01-01', to: '2026-12-31' },
+    )
+  })
+})
+
+describe('encodeDateRangeValue', () => {
+  it('encodes a closed range', () => {
+    assert.equal(encodeDateRangeValue({ from: '2026-01-01', to: '2026-12-31' }), '2026-01-01..2026-12-31')
+  })
+  it('encodes open-from / open-to', () => {
+    assert.equal(encodeDateRangeValue({ from: '2026-01-01' }), '2026-01-01..')
+    assert.equal(encodeDateRangeValue({ to:   '2026-12-31' }), '..2026-12-31')
+  })
+  it('returns empty string when both sides are missing', () => {
+    assert.equal(encodeDateRangeValue({}),                       '')
+    assert.equal(encodeDateRangeValue({ from: '', to: '' }),     '')
+  })
+})
+
+describe('DateRangeFilter shape', () => {
+  it('toMeta emits kind:dateRange + includesTime + Any placeholder', () => {
+    const meta = DateRangeFilter.make('publishedAt').toMeta()
+    assert.equal(meta.kind,         'dateRange')
+    assert.equal(meta.includesTime, false)
+    assert.equal(meta.placeholder,  'Any')
+    assert.equal(meta.minDate,      undefined)
+    assert.equal(meta.maxDate,      undefined)
+  })
+
+  it('includesTime() flips the meta flag', () => {
+    const meta = DateRangeFilter.make('publishedAt').includesTime(true).toMeta()
+    assert.equal(meta.includesTime, true)
+  })
+
+  it('minDate / maxDate accept ISO strings + Date objects', () => {
+    const date = new Date(2026, 0, 15) // 2026-01-15 local
+    const meta = DateRangeFilter.make('publishedAt')
+      .minDate('2020-01-01')
+      .maxDate(date)
+      .toMeta()
+    assert.equal(meta.minDate, '2020-01-01')
+    assert.equal(meta.maxDate, '2026-01-15')
+  })
+
+  it('Date bounds include time when includesTime(true) was set first', () => {
+    const date = new Date(2026, 0, 15, 14, 30) // 2026-01-15 14:30 local
+    const meta = DateRangeFilter.make('publishedAt')
+      .includesTime(true)
+      .maxDate(date)
+      .toMeta()
+    assert.equal(meta.maxDate, '2026-01-15T14:30')
+  })
+
+  it('placeholder override wins over Any default', () => {
+    const meta = DateRangeFilter.make('publishedAt').placeholder('Any time').toMeta()
+    assert.equal(meta.placeholder, 'Any time')
+  })
+})
+
+describe('DateRangeFilter default query handler', () => {
+  it('closed range emits two where clauses (>=, <=)', async () => {
+    const M = fakeModel()
+    const table = Table.make()
+      .columns([Column.make('title')])
+      .filters([DateRangeFilter.make('publishedAt')])
+    const handler = modelTableRecords(M, table)
+    await handler({ filters: { publishedAt: '2026-01-01..2026-12-31' }, page: 1 })
+    const wheres = M.lastQuery!.ops.filter(o => o.op === 'where')
+    assert.deepEqual(wheres[0]!.args, ['publishedAt', '>=', '2026-01-01'])
+    assert.deepEqual(wheres[1]!.args, ['publishedAt', '<=', '2026-12-31'])
+  })
+
+  it('open-from emits a single >= clause', async () => {
+    const M = fakeModel()
+    const table = Table.make()
+      .columns([Column.make('title')])
+      .filters([DateRangeFilter.make('publishedAt')])
+    const handler = modelTableRecords(M, table)
+    await handler({ filters: { publishedAt: '2026-01-01..' }, page: 1 })
+    const wheres = M.lastQuery!.ops.filter(o => o.op === 'where')
+    assert.equal(wheres.length, 1)
+    assert.deepEqual(wheres[0]!.args, ['publishedAt', '>=', '2026-01-01'])
+  })
+
+  it('open-to emits a single <= clause', async () => {
+    const M = fakeModel()
+    const table = Table.make()
+      .columns([Column.make('title')])
+      .filters([DateRangeFilter.make('publishedAt')])
+    const handler = modelTableRecords(M, table)
+    await handler({ filters: { publishedAt: '..2026-12-31' }, page: 1 })
+    const wheres = M.lastQuery!.ops.filter(o => o.op === 'where')
+    assert.equal(wheres.length, 1)
+    assert.deepEqual(wheres[0]!.args, ['publishedAt', '<=', '2026-12-31'])
+  })
+
+  it('parseFilterValues drops `..` (no clauses)', async () => {
+    // The parser drops empty values upstream, but `..` is non-empty —
+    // the default handler itself short-circuits the no-bound case.
+    const M = fakeModel()
+    const table = Table.make()
+      .columns([Column.make('title')])
+      .filters([DateRangeFilter.make('publishedAt')])
+    const handler = modelTableRecords(M, table)
+    await handler({ filters: { publishedAt: '..' }, page: 1 })
+    const wheres = M.lastQuery!.ops.filter(o => o.op === 'where')
+    assert.equal(wheres.length, 0)
+  })
+
+  it('user .query(fn) override sees the raw encoded value', async () => {
+    const M = fakeModel()
+    let received: string | undefined
+    const table = Table.make()
+      .columns([Column.make('title')])
+      .filters([
+        DateRangeFilter.make('publishedAt').query((q, value) => {
+          received = value
+          return q
+        }),
+      ])
+    const handler = modelTableRecords(M, table)
+    await handler({ filters: { publishedAt: '2026-01-01..2026-12-31' }, page: 1 })
+    assert.equal(received, '2026-01-01..2026-12-31')
+  })
+})