@lovett/ui 0.0.11 → 0.2.0

package/src/filter-core/__tests__/operators.test.ts

@@ -0,0 +1,235 @@
+/**
+ * Operator tables, defaults, and the singular <-> plural promotion rule.
+ */
+import { describe, expect, it } from 'vitest'
+import {
+  COLUMN_DATA_TYPES,
+  DEFAULT_OPERATORS,
+  FILTER_OPERATOR_DETAILS,
+  determineNewOperator,
+  isOperatorOf,
+  negateOperator,
+  operatorDetails,
+  operatorValueArity,
+  operatorsForType,
+  relatedOperators,
+} from '../index'
+import type { ColumnDataType } from '../index'
+
+describe('operator tables', () => {
+  it('declares a table for every column data type', () => {
+    for (const type of COLUMN_DATA_TYPES) {
+      expect(Object.keys(FILTER_OPERATOR_DETAILS[type]).length).toBeGreaterThan(0)
+    }
+  })
+
+  it('keys every entry by its own value', () => {
+    for (const type of COLUMN_DATA_TYPES) {
+      for (const operator of operatorsForType(type)) {
+        expect(operatorDetails(type, operator).value).toBe(operator)
+      }
+    }
+  })
+
+  it('points singularOf at a multiple-target operator and pluralOf at a single one', () => {
+    // Promotion is many-to-one on purpose: five number operators all promote
+    // to "is between", which can only demote back to one of them. So the
+    // invariant is about DIRECTION, not a round trip.
+    for (const type of COLUMN_DATA_TYPES) {
+      for (const operator of operatorsForType(type)) {
+        const details = operatorDetails(type, operator)
+        if (details.singularOf) {
+          const target = operatorDetails(type, details.singularOf)
+          expect(details.target).toBe('single')
+          expect(target.target).toBe('multiple')
+        }
+        if (details.pluralOf) {
+          const target = operatorDetails(type, details.pluralOf)
+          expect(details.target).toBe('multiple')
+          expect(target.target).toBe('single')
+        }
+      }
+    }
+  })
+
+  it('round-trips the is / is any of family exactly', () => {
+    const pairs = [
+      ['option', 'is', 'is any of'],
+      ['option', 'is not', 'is none of'],
+      ['number', 'is', 'is between'],
+      ['date', 'is', 'is between'],
+      ['multiOption', 'include', 'include any of'],
+    ] as const
+    for (const [type, singular, plural] of pairs) {
+      expect(operatorDetails(type, singular).singularOf).toBe(plural)
+      expect(operatorDetails(type, plural).pluralOf).toBe(singular)
+    }
+  })
+
+  it('documents the lossy demotions, so they are a decision and not a surprise', () => {
+    // "include all of" and "exclude if all" have no one-value form of their
+    // own, so they demote to "include" / "exclude" and a later second value
+    // promotes to the ANY form. Inherited from the source; pinned here so a
+    // change to it is visible.
+    expect(operatorDetails('multiOption', 'include all of').pluralOf).toBe('include')
+    expect(operatorDetails('multiOption', 'include').singularOf).toBe('include any of')
+    expect(operatorDetails('number', 'is greater than').singularOf).toBe('is between')
+    expect(operatorDetails('number', 'is between').pluralOf).toBe('is')
+  })
+
+  it('pairs negations symmetrically', () => {
+    for (const type of COLUMN_DATA_TYPES) {
+      for (const operator of operatorsForType(type)) {
+        const details = operatorDetails(type, operator)
+        const twin = details.negation ?? details.negationOf
+        expect(twin).toBeDefined()
+        if (!twin) continue
+        expect(negateOperator(type, twin)).toBe(operator)
+      }
+    }
+  })
+
+  it('gives every default operator a real table entry', () => {
+    for (const type of COLUMN_DATA_TYPES) {
+      const defaults = DEFAULT_OPERATORS[type]
+      expect(isOperatorOf(type, defaults.single)).toBe(true)
+      expect(isOperatorOf(type, defaults.multiple)).toBe(true)
+    }
+  })
+
+  it('marks only "not"-phrased operators as negated', () => {
+    // isNegated is about PHRASING, not logic. "is less than" is the
+    // complement of "is greater than or equal to", but it is not a negation
+    // and a UI must not render it with a "not" chip.
+    expect(operatorDetails('number', 'is less than').isNegated).toBe(false)
+    expect(operatorDetails('date', 'is on or after').isNegated).toBe(false)
+    expect(operatorDetails('number', 'is not').isNegated).toBe(true)
+    expect(operatorDetails('option', 'is none of').isNegated).toBe(true)
+    expect(operatorDetails('multiOption', 'exclude if all').isNegated).toBe(true)
+  })
+
+  it('rejects an unknown operator at lookup', () => {
+    expect(isOperatorOf('option', 'is sort of')).toBe(false)
+    expect(isOperatorOf('option', '__proto__')).toBe(false)
+    expect(isOperatorOf('option', 'toString')).toBe(false)
+    expect(isOperatorOf('text', 42)).toBe(false)
+  })
+})
+
+describe('operatorValueArity', () => {
+  it('requires exactly two values for the between operators', () => {
+    expect(operatorValueArity('date', 'is between')).toEqual([2, 2])
+    expect(operatorValueArity('date', 'is not between')).toEqual([2, 2])
+    expect(operatorValueArity('number', 'is between')).toEqual([2, 2])
+  })
+
+  it('requires exactly one value for the single-target operators', () => {
+    expect(operatorValueArity('text', 'contains')).toEqual([1, 1])
+    expect(operatorValueArity('option', 'is')).toEqual([1, 1])
+  })
+
+  it('allows an open-ended list for the many-target operators', () => {
+    const [min, max] = operatorValueArity('option', 'is any of')
+    expect(min).toBe(1)
+    expect(max).toBe(Number.POSITIVE_INFINITY)
+  })
+})
+
+describe('relatedOperators', () => {
+  it('offers only operators with the same target', () => {
+    expect(relatedOperators('option', 'is')).toEqual(['is not'])
+    expect(relatedOperators('option', 'is any of')).toEqual(['is none of'])
+  })
+
+  it('never offers the operator itself', () => {
+    for (const type of COLUMN_DATA_TYPES) {
+      for (const operator of operatorsForType(type)) {
+        expect(relatedOperators(type, operator)).not.toContain(operator)
+      }
+    }
+  })
+})
+
+describe('determineNewOperator', () => {
+  it('promotes is -> is any of when a second value is picked', () => {
+    expect(determineNewOperator('option', ['a'], ['a', 'b'], 'is')).toBe(
+      'is any of',
+    )
+  })
+
+  it('promotes is not -> is none of', () => {
+    expect(determineNewOperator('option', ['a'], ['a', 'b'], 'is not')).toBe(
+      'is none of',
+    )
+  })
+
+  it('demotes is any of -> is when the list falls back to one', () => {
+    expect(
+      determineNewOperator('option', ['a', 'b'], ['a'], 'is any of'),
+    ).toBe('is')
+  })
+
+  it('demotes is none of -> is not', () => {
+    expect(
+      determineNewOperator('option', ['a', 'b'], ['b'], 'is none of'),
+    ).toBe('is not')
+  })
+
+  it('demotes to the singular form when the list empties', () => {
+    expect(determineNewOperator('option', ['a', 'b'], [], 'is any of')).toBe('is')
+  })
+
+  it('leaves the operator alone inside the single band', () => {
+    expect(determineNewOperator('option', [], ['a'], 'is')).toBe('is')
+    expect(determineNewOperator('option', ['a'], ['b'], 'is not')).toBe('is not')
+  })
+
+  it('leaves the operator alone inside the multiple band', () => {
+    expect(
+      determineNewOperator('option', ['a', 'b'], ['a', 'b', 'c'], 'is any of'),
+    ).toBe('is any of')
+  })
+
+  it('promotes number and date to their between forms', () => {
+    expect(determineNewOperator('number', [1], [1, 9], 'is')).toBe('is between')
+    expect(determineNewOperator('number', [1], [1, 9], 'is not')).toBe(
+      'is not between',
+    )
+    expect(
+      determineNewOperator(
+        'date',
+        [new Date(2026, 0, 1)],
+        [new Date(2026, 0, 1), new Date(2026, 0, 9)],
+        'is',
+      ),
+    ).toBe('is between')
+  })
+
+  it('promotes multiOption include -> include any of and back', () => {
+    expect(determineNewOperator('multiOption', ['x'], ['x', 'y'], 'include')).toBe(
+      'include any of',
+    )
+    expect(
+      determineNewOperator('multiOption', ['x', 'y'], ['x'], 'include all of'),
+    ).toBe('include')
+  })
+
+  it('leaves an operator with no plural twin alone', () => {
+    // text has one target band, so nothing to promote to.
+    expect(determineNewOperator('text', ['a'], ['a', 'b'], 'contains')).toBe(
+      'contains',
+    )
+  })
+
+  it('never returns an operator outside the type table', () => {
+    const types: ColumnDataType[] = [...COLUMN_DATA_TYPES]
+    for (const type of types) {
+      for (const operator of operatorsForType(type)) {
+        const grown = determineNewOperator(type, ['a'], ['a', 'b'], operator)
+        const shrunk = determineNewOperator(type, ['a', 'b'], ['a'], operator)
+        expect(isOperatorOf(type, grown)).toBe(true)
+        expect(isOperatorOf(type, shrunk)).toBe(true)
+      }
+    }
+  })
+})

package/src/filter-core/__tests__/state.test.ts

@@ -0,0 +1,268 @@
+/**
+ * Immutable filter-state transitions, and the one place operator promotion
+ * is applied.
+ */
+import { describe, expect, it } from 'vitest'
+import {
+  clearFilters,
+  defineColumns,
+  getFilter,
+  removeFilter,
+  setDateFilter,
+  setFilterOperator,
+  setMultiOptionFilter,
+  setNumberFilter,
+  setOptionFilter,
+  setTextFilter,
+  toggleMultiOptionValue,
+  toggleOptionValue,
+  upsertFilter,
+} from '../index'
+import type { ColumnConfig, FiltersState } from '../index'
+
+interface Task {
+  readonly title: string
+  readonly priority: string
+  readonly points: number
+  readonly due: Date
+  readonly labels: readonly string[]
+}
+
+const title: ColumnConfig<Task, 'text'> = {
+  id: 'title',
+  type: 'text',
+  displayName: 'Title',
+  accessor: (t) => t.title,
+}
+const priority: ColumnConfig<Task, 'option'> = {
+  id: 'priority',
+  type: 'option',
+  displayName: 'Priority',
+  accessor: (t) => t.priority,
+  options: [
+    { value: 'low', label: 'Low' },
+    { value: 'high', label: 'High' },
+  ],
+}
+const points: ColumnConfig<Task, 'number'> = {
+  id: 'points',
+  type: 'number',
+  displayName: 'Points',
+  accessor: (t) => t.points,
+}
+const due: ColumnConfig<Task, 'date'> = {
+  id: 'due',
+  type: 'date',
+  displayName: 'Due',
+  accessor: (t) => t.due,
+}
+const labels: ColumnConfig<Task, 'multiOption'> = {
+  id: 'labels',
+  type: 'multiOption',
+  displayName: 'Labels',
+  accessor: (t) => t.labels,
+  options: [
+    { value: 'bug', label: 'Bug' },
+    { value: 'ui', label: 'UI' },
+  ],
+}
+
+// The columns are also a valid config set.
+defineColumns<Task>([title, priority, points, due, labels])
+
+describe('immutability', () => {
+  it('never mutates the state it is given', () => {
+    const state: FiltersState = []
+    const next = setOptionFilter(state, priority, ['high'])
+    expect(state).toEqual([])
+    expect(next).not.toBe(state)
+  })
+})
+
+describe('setOptionFilter', () => {
+  it('creates a filter on the singular default operator', () => {
+    const state = setOptionFilter([], priority, ['high'])
+    expect(state[0]).toEqual({
+      columnId: 'priority',
+      type: 'option',
+      operator: 'is',
+      values: ['high'],
+    })
+  })
+
+  it('creates a filter on the plural default when handed several values', () => {
+    const state = setOptionFilter([], priority, ['high', 'low'])
+    expect(state[0]?.operator).toBe('is any of')
+  })
+
+  it('promotes on growth and demotes on shrink', () => {
+    let state = setOptionFilter([], priority, ['high'])
+    state = setOptionFilter(state, priority, ['high', 'low'])
+    expect(state[0]?.operator).toBe('is any of')
+    state = setOptionFilter(state, priority, ['low'])
+    expect(state[0]?.operator).toBe('is')
+  })
+
+  it('preserves a chosen negated operator across a promotion', () => {
+    let state = setOptionFilter([], priority, ['high'])
+    state = setFilterOperator(state, 'priority', 'is not')
+    state = setOptionFilter(state, priority, ['high', 'low'])
+    expect(state[0]?.operator).toBe('is none of')
+  })
+
+  it('removes the filter when the value list empties', () => {
+    const state = setOptionFilter(setOptionFilter([], priority, ['high']), priority, [])
+    expect(state).toEqual([])
+  })
+
+  it('keeps position when updating an existing filter', () => {
+    let state = setTextFilter([], title, 'ship')
+    state = setOptionFilter(state, priority, ['high'])
+    state = setTextFilter(state, title, 'rail')
+    expect(state.map((f) => f.columnId)).toEqual(['title', 'priority'])
+  })
+})
+
+describe('toggleOptionValue', () => {
+  it('adds, promotes, then removes and demotes', () => {
+    let state = toggleOptionValue([], priority, 'high')
+    expect(state[0]?.values).toEqual(['high'])
+    expect(state[0]?.operator).toBe('is')
+
+    state = toggleOptionValue(state, priority, 'low')
+    expect(state[0]?.values).toEqual(['high', 'low'])
+    expect(state[0]?.operator).toBe('is any of')
+
+    state = toggleOptionValue(state, priority, 'high')
+    expect(state[0]?.values).toEqual(['low'])
+    expect(state[0]?.operator).toBe('is')
+
+    state = toggleOptionValue(state, priority, 'low')
+    expect(state).toEqual([])
+  })
+})
+
+describe('toggleMultiOptionValue', () => {
+  it('promotes include -> include any of', () => {
+    let state = toggleMultiOptionValue([], labels, 'bug')
+    expect(state[0]?.operator).toBe('include')
+    state = toggleMultiOptionValue(state, labels, 'ui')
+    expect(state[0]?.operator).toBe('include any of')
+    expect(state[0]?.values).toEqual(['bug', 'ui'])
+  })
+})
+
+describe('setMultiOptionFilter', () => {
+  it('creates on the plural default, and removes when emptied', () => {
+    const state = setMultiOptionFilter([], labels, ['bug', 'ui'])
+    expect(state[0]).toEqual({
+      columnId: 'labels',
+      type: 'multiOption',
+      operator: 'include any of',
+      values: ['bug', 'ui'],
+    })
+    expect(setMultiOptionFilter(state, labels, [])).toEqual([])
+  })
+
+  it('demotes include any of back to include', () => {
+    const state = setMultiOptionFilter(
+      setMultiOptionFilter([], labels, ['bug', 'ui']),
+      labels,
+      ['bug'],
+    )
+    expect(state[0]?.operator).toBe('include')
+  })
+})
+
+describe('setTextFilter', () => {
+  it('stores a single value and removes on blank', () => {
+    const state = setTextFilter([], title, 'ship')
+    expect(state[0]).toEqual({
+      columnId: 'title',
+      type: 'text',
+      operator: 'contains',
+      values: ['ship'],
+    })
+    expect(setTextFilter(state, title, '   ')).toEqual([])
+  })
+
+  it('keeps a chosen negated operator', () => {
+    let state = setTextFilter([], title, 'ship')
+    state = setFilterOperator(state, 'title', 'does not contain')
+    state = setTextFilter(state, title, 'rail')
+    expect(state[0]?.operator).toBe('does not contain')
+  })
+})
+
+describe('setNumberFilter / setDateFilter', () => {
+  it('promotes number is -> is between', () => {
+    let state = setNumberFilter([], points, [3])
+    expect(state[0]?.operator).toBe('is')
+    state = setNumberFilter(state, points, [3, 8])
+    expect(state[0]?.operator).toBe('is between')
+    state = setNumberFilter(state, points, [3])
+    expect(state[0]?.operator).toBe('is')
+  })
+
+  it('promotes date is -> is between', () => {
+    let state = setDateFilter([], due, [new Date(2026, 0, 1)])
+    expect(state[0]?.operator).toBe('is')
+    state = setDateFilter(state, due, [new Date(2026, 0, 1), new Date(2026, 0, 9)])
+    expect(state[0]?.operator).toBe('is between')
+  })
+
+  it('copies the value array rather than aliasing the caller s', () => {
+    const values = [3, 8]
+    const state = setNumberFilter([], points, values)
+    values.push(99)
+    expect(state[0]?.values).toEqual([3, 8])
+  })
+})
+
+describe('setFilterOperator', () => {
+  it('leaves the state alone for an unknown column', () => {
+    const state = setOptionFilter([], priority, ['high'])
+    expect(setFilterOperator(state, 'nope', 'is not')).toBe(state)
+  })
+
+  it('refuses an operator from another column type', () => {
+    const state = setOptionFilter([], priority, ['high'])
+    expect(setFilterOperator(state, 'priority', 'contains')).toBe(state)
+  })
+
+  it('swaps to a legal operator of the same type', () => {
+    const state = setFilterOperator(
+      setOptionFilter([], priority, ['high']),
+      'priority',
+      'is not',
+    )
+    expect(state[0]?.operator).toBe('is not')
+  })
+})
+
+describe('getFilter / removeFilter / clearFilters / upsertFilter', () => {
+  it('reads, removes and clears', () => {
+    const state = setOptionFilter(setTextFilter([], title, 'ship'), priority, ['high'])
+    expect(getFilter(state, 'priority')?.values).toEqual(['high'])
+    expect(getFilter(state, 'missing')).toBeUndefined()
+    expect(removeFilter(state, 'priority').map((f) => f.columnId)).toEqual(['title'])
+    expect(clearFilters()).toEqual([])
+  })
+
+  it('appends an unseen column and replaces a seen one', () => {
+    const first = upsertFilter([], {
+      columnId: 'priority',
+      type: 'option',
+      operator: 'is',
+      values: ['high'],
+    })
+    const second = upsertFilter(first, {
+      columnId: 'priority',
+      type: 'option',
+      operator: 'is',
+      values: ['low'],
+    })
+    expect(second).toHaveLength(1)
+    expect(second[0]?.values).toEqual(['low'])
+  })
+})