@lovett/ui 0.0.11 → 0.2.0

package/src/filter-core/operators.ts

@@ -0,0 +1,433 @@
+/**
+ * @package @lovett/ui
+ * @file filter-core/operators.ts
+ *
+ * The operator tables — one per column type — plus the defaults and the
+ * singular/plural promotion rule.
+ *
+ * Ported from bazza/ui's `data-table-filter`. Dropped on the way in:
+ *   - `key` (i18n keys; we have no i18n and the operator IS its label).
+ *   - `relativeOf` (a hand-maintained list of sibling operators that drifts
+ *     the moment an operator is added). `relatedOperators()` derives the same
+ *     answer from `target`, so it cannot go stale.
+ *
+ * Added: `arity`. See the note on `FilterOperatorArity` in types.ts — this is
+ * the structural fix for the `in`-on-an-array date guard.
+ *
+ * `isNegated` means "reads as a negative phrase" (`is not`, `exclude`,
+ * `does not contain`) and drives UI phrasing only. `negation` / `negationOf`
+ * give the logical COMPLEMENT, which is what `negateOperator()` swaps to.
+ * Ordering operators pair off mutually (`is before` <-> `is on or after`) and
+ * are all positive — calling `is less than` a negation would be nonsense.
+ */
+
+import type {
+  ColumnDataType,
+  FilterDetails,
+  FilterOperatorArity,
+  FilterOperators,
+  FilterOperatorTarget,
+  FilterTypeOperatorDetails,
+} from './types'
+
+/* ------------------------------------------------------------------ */
+/* Tables                                                              */
+/* ------------------------------------------------------------------ */
+
+export const textFilterOperators = {
+  contains: {
+    value: 'contains',
+    target: 'single',
+    arity: 'one',
+    isNegated: false,
+    negation: 'does not contain',
+  },
+  'does not contain': {
+    value: 'does not contain',
+    target: 'single',
+    arity: 'one',
+    isNegated: true,
+    negationOf: 'contains',
+  },
+} as const satisfies FilterDetails<'text'>
+
+export const numberFilterOperators = {
+  is: {
+    value: 'is',
+    target: 'single',
+    arity: 'one',
+    singularOf: 'is between',
+    isNegated: false,
+    negation: 'is not',
+  },
+  'is not': {
+    value: 'is not',
+    target: 'single',
+    arity: 'one',
+    singularOf: 'is not between',
+    isNegated: true,
+    negationOf: 'is',
+  },
+  'is greater than': {
+    value: 'is greater than',
+    target: 'single',
+    arity: 'one',
+    singularOf: 'is between',
+    isNegated: false,
+    negation: 'is less than or equal to',
+  },
+  'is greater than or equal to': {
+    value: 'is greater than or equal to',
+    target: 'single',
+    arity: 'one',
+    singularOf: 'is between',
+    isNegated: false,
+    negation: 'is less than',
+  },
+  'is less than': {
+    value: 'is less than',
+    target: 'single',
+    arity: 'one',
+    singularOf: 'is between',
+    isNegated: false,
+    negation: 'is greater than or equal to',
+  },
+  'is less than or equal to': {
+    value: 'is less than or equal to',
+    target: 'single',
+    arity: 'one',
+    singularOf: 'is between',
+    isNegated: false,
+    negation: 'is greater than',
+  },
+  'is between': {
+    value: 'is between',
+    target: 'multiple',
+    arity: 'two',
+    pluralOf: 'is',
+    isNegated: false,
+    negation: 'is not between',
+  },
+  'is not between': {
+    value: 'is not between',
+    target: 'multiple',
+    arity: 'two',
+    pluralOf: 'is not',
+    isNegated: true,
+    negationOf: 'is between',
+  },
+} as const satisfies FilterDetails<'number'>
+
+export const dateFilterOperators = {
+  is: {
+    value: 'is',
+    target: 'single',
+    arity: 'one',
+    singularOf: 'is between',
+    isNegated: false,
+    negation: 'is not',
+  },
+  'is not': {
+    value: 'is not',
+    target: 'single',
+    arity: 'one',
+    singularOf: 'is not between',
+    isNegated: true,
+    negationOf: 'is',
+  },
+  'is before': {
+    value: 'is before',
+    target: 'single',
+    arity: 'one',
+    singularOf: 'is between',
+    isNegated: false,
+    negation: 'is on or after',
+  },
+  'is on or after': {
+    value: 'is on or after',
+    target: 'single',
+    arity: 'one',
+    singularOf: 'is between',
+    isNegated: false,
+    negation: 'is before',
+  },
+  'is after': {
+    value: 'is after',
+    target: 'single',
+    arity: 'one',
+    singularOf: 'is between',
+    isNegated: false,
+    negation: 'is on or before',
+  },
+  'is on or before': {
+    value: 'is on or before',
+    target: 'single',
+    arity: 'one',
+    singularOf: 'is between',
+    isNegated: false,
+    negation: 'is after',
+  },
+  'is between': {
+    value: 'is between',
+    target: 'multiple',
+    arity: 'two',
+    pluralOf: 'is',
+    isNegated: false,
+    negation: 'is not between',
+  },
+  'is not between': {
+    value: 'is not between',
+    target: 'multiple',
+    arity: 'two',
+    pluralOf: 'is not',
+    isNegated: true,
+    negationOf: 'is between',
+  },
+} as const satisfies FilterDetails<'date'>
+
+export const optionFilterOperators = {
+  is: {
+    value: 'is',
+    target: 'single',
+    arity: 'one',
+    singularOf: 'is any of',
+    isNegated: false,
+    negation: 'is not',
+  },
+  'is not': {
+    value: 'is not',
+    target: 'single',
+    arity: 'one',
+    singularOf: 'is none of',
+    isNegated: true,
+    negationOf: 'is',
+  },
+  'is any of': {
+    value: 'is any of',
+    target: 'multiple',
+    arity: 'many',
+    pluralOf: 'is',
+    isNegated: false,
+    negation: 'is none of',
+  },
+  'is none of': {
+    value: 'is none of',
+    target: 'multiple',
+    arity: 'many',
+    pluralOf: 'is not',
+    isNegated: true,
+    negationOf: 'is any of',
+  },
+} as const satisfies FilterDetails<'option'>
+
+export const multiOptionFilterOperators = {
+  include: {
+    value: 'include',
+    target: 'single',
+    arity: 'one',
+    singularOf: 'include any of',
+    isNegated: false,
+    negation: 'exclude',
+  },
+  exclude: {
+    value: 'exclude',
+    target: 'single',
+    arity: 'one',
+    singularOf: 'exclude if any of',
+    isNegated: true,
+    negationOf: 'include',
+  },
+  'include any of': {
+    value: 'include any of',
+    target: 'multiple',
+    arity: 'many',
+    pluralOf: 'include',
+    isNegated: false,
+    negation: 'exclude if any of',
+  },
+  'include all of': {
+    value: 'include all of',
+    target: 'multiple',
+    arity: 'many',
+    pluralOf: 'include',
+    isNegated: false,
+    negation: 'exclude if all',
+  },
+  'exclude if any of': {
+    value: 'exclude if any of',
+    target: 'multiple',
+    arity: 'many',
+    pluralOf: 'exclude',
+    isNegated: true,
+    negationOf: 'include any of',
+  },
+  'exclude if all': {
+    value: 'exclude if all',
+    target: 'multiple',
+    arity: 'many',
+    pluralOf: 'exclude',
+    isNegated: true,
+    negationOf: 'include all of',
+  },
+} as const satisfies FilterDetails<'multiOption'>
+
+/** Every operator table, keyed by column data type. */
+export const FILTER_OPERATOR_DETAILS: FilterTypeOperatorDetails = {
+  text: textFilterOperators,
+  number: numberFilterOperators,
+  date: dateFilterOperators,
+  option: optionFilterOperators,
+  multiOption: multiOptionFilterOperators,
+}
+
+/**
+ * The operator a fresh filter starts on, by type and by how many values the
+ * user picked first.
+ */
+export const DEFAULT_OPERATORS: {
+  [K in ColumnDataType]: Record<FilterOperatorTarget, FilterOperators[K]>
+} = {
+  text: { single: 'contains', multiple: 'contains' },
+  number: { single: 'is', multiple: 'is between' },
+  date: { single: 'is', multiple: 'is between' },
+  option: { single: 'is', multiple: 'is any of' },
+  multiOption: { single: 'include', multiple: 'include any of' },
+}
+
+/* ------------------------------------------------------------------ */
+/* Lookups                                                             */
+/* ------------------------------------------------------------------ */
+
+/** Every operator legal for a column type, in table order. */
+export function operatorsForType<TType extends ColumnDataType>(
+  type: TType,
+): Array<FilterOperators[TType]> {
+  return Object.keys(FILTER_OPERATOR_DETAILS[type]) as Array<
+    FilterOperators[TType]
+  >
+}
+
+/**
+ * Runtime membership test, narrowing to the operator union for `type`.
+ * The single validated entry point used by the URL parser.
+ */
+export function isOperatorOf<TType extends ColumnDataType>(
+  type: TType,
+  value: unknown,
+): value is FilterOperators[TType] {
+  return (
+    typeof value === 'string' &&
+    Object.hasOwn(FILTER_OPERATOR_DETAILS[type], value)
+  )
+}
+
+/** Metadata for one operator. Throws if the operator is not in the table. */
+export function operatorDetails<TType extends ColumnDataType>(
+  type: TType,
+  operator: FilterOperators[TType],
+): FilterOperatorDetailsShape<TType> {
+  const table: Record<string, FilterOperatorDetailsShape<TType>> =
+    FILTER_OPERATOR_DETAILS[type]
+  const details = table[operator]
+  if (!details) {
+    throw new Error(
+      `[filter-core] unknown operator "${String(operator)}" for column type "${type}"`,
+    )
+  }
+  return details
+}
+
+/**
+ * The widened shape of one operator's metadata. `FilterOperatorDetails` is
+ * keyed by the specific operator literal; this is the read-side view where
+ * the literal is not known statically.
+ */
+export type FilterOperatorDetailsShape<TType extends ColumnDataType> = {
+  readonly value: FilterOperators[TType]
+  readonly target: FilterOperatorTarget
+  readonly arity: FilterOperatorArity
+  readonly singularOf?: FilterOperators[TType]
+  readonly pluralOf?: FilterOperators[TType]
+  readonly isNegated: boolean
+  readonly negation?: FilterOperators[TType]
+  readonly negationOf?: FilterOperators[TType]
+}
+
+/**
+ * Operators a user could swap to without changing how many values they have
+ * selected — i.e. every operator sharing the current one's target.
+ *
+ * Replaces the source's hand-written `relativeOf`, which had to be edited in
+ * five places for every new operator and was already inconsistent.
+ */
+export function relatedOperators<TType extends ColumnDataType>(
+  type: TType,
+  operator: FilterOperators[TType],
+): Array<FilterOperators[TType]> {
+  const { target } = operatorDetails(type, operator)
+  return operatorsForType(type).filter(
+    (candidate) =>
+      candidate !== operator && operatorDetails(type, candidate).target === target,
+  )
+}
+
+/** The negated twin of an operator, or the operator itself if it has none. */
+export function negateOperator<TType extends ColumnDataType>(
+  type: TType,
+  operator: FilterOperators[TType],
+): FilterOperators[TType] {
+  const details = operatorDetails(type, operator)
+  return details.negation ?? details.negationOf ?? operator
+}
+
+/** How many values an operator requires: `[min, max]`, `max` may be Infinity. */
+export function operatorValueArity<TType extends ColumnDataType>(
+  type: TType,
+  operator: FilterOperators[TType],
+): readonly [number, number] {
+  switch (operatorDetails(type, operator).arity) {
+    case 'one':
+      return [1, 1]
+    case 'two':
+      return [2, 2]
+    case 'many':
+      return [1, Number.POSITIVE_INFINITY]
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* Promotion / demotion                                                */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Pick the operator that fits a new value count.
+ *
+ * `is` promotes to `is any of` the moment a second value is picked, and
+ * demotes back when the list falls to one. An operator with no singular or
+ * plural twin (text's `contains`, or an already-correct arity) is left alone.
+ *
+ * Simplified from the source, which special-cased `values[0]` being an array
+ * to cope with its own inconsistent multiOption shape. Ours is flat, so the
+ * rule is just a length comparison.
+ */
+export function determineNewOperator<TType extends ColumnDataType>(
+  type: TType,
+  oldValues: readonly unknown[],
+  nextValues: readonly unknown[],
+  currentOperator: FilterOperators[TType],
+): FilterOperators[TType] {
+  const before = oldValues.length
+  const after = nextValues.length
+
+  // No transition across the single/multiple boundary: nothing to do.
+  if (before === after) return currentOperator
+  if (before >= 2 && after >= 2) return currentOperator
+  if (before <= 1 && after <= 1) return currentOperator
+
+  const details = operatorDetails(type, currentOperator)
+
+  // Grew past one value: promote to the plural form.
+  if (after >= 2) return details.singularOf ?? currentOperator
+  // Fell back to one value or none: demote to the singular form.
+  return details.pluralOf ?? currentOperator
+}

package/src/filter-core/state.ts

@@ -0,0 +1,280 @@
+/**
+ * @package @lovett/ui
+ * @file filter-core/state.ts
+ *
+ * Immutable transitions on a `FiltersState`.
+ *
+ * These exist so the operator-promotion rule has exactly ONE caller. Without
+ * them every consumer that writes a filter — the filter popover, a facet row
+ * click, a stats row click — re-derives "when do I switch `is` to `is any
+ * of`", and they drift. Setting a value list to empty REMOVES the filter, so
+ * a chip cleared to nothing does not linger as a no-op in the URL.
+ *
+ * Every function returns a new array; nothing is mutated.
+ */
+
+import { DEFAULT_OPERATORS, determineNewOperator } from './operators'
+import type {
+  ColumnConfig,
+  FilterModel,
+  FiltersState,
+  FilterOperators,
+} from './types'
+
+/** The filter currently applied to a column, if any. */
+export function getFilter(
+  state: FiltersState,
+  columnId: string,
+): FilterModel | undefined {
+  return state.find((filter) => filter.columnId === columnId)
+}
+
+/** Drop one column's filter. */
+export function removeFilter(
+  state: FiltersState,
+  columnId: string,
+): FiltersState {
+  return state.filter((filter) => filter.columnId !== columnId)
+}
+
+/** Drop every filter. */
+export function clearFilters(): FiltersState {
+  return []
+}
+
+/** Replace or append one column's filter, preserving order. */
+export function upsertFilter(
+  state: FiltersState,
+  next: FilterModel,
+): FiltersState {
+  const index = state.findIndex((filter) => filter.columnId === next.columnId)
+  if (index === -1) return [...state, next]
+  const copy = [...state]
+  copy[index] = next
+  return copy
+}
+
+/* ------------------------------------------------------------------ */
+/* Per-type setters                                                    */
+/* ------------------------------------------------------------------ */
+
+export function setTextFilter<TData>(
+  state: FiltersState,
+  column: ColumnConfig<TData, 'text'>,
+  query: string,
+): FiltersState {
+  if (query.trim() === '') return removeFilter(state, column.id)
+  const existing = getFilter(state, column.id)
+  const operator: FilterOperators['text'] =
+    existing?.type === 'text' ? existing.operator : DEFAULT_OPERATORS.text.single
+  return upsertFilter(state, {
+    columnId: column.id,
+    type: 'text',
+    operator,
+    values: [query],
+  })
+}
+
+export function setNumberFilter<TData>(
+  state: FiltersState,
+  column: ColumnConfig<TData, 'number'>,
+  values: readonly number[],
+): FiltersState {
+  if (values.length === 0) return removeFilter(state, column.id)
+  const existing = getFilter(state, column.id)
+  const operator: FilterOperators['number'] =
+    existing?.type === 'number'
+      ? determineNewOperator(
+          'number',
+          existing.values,
+          values,
+          existing.operator,
+        )
+      : values.length > 1
+        ? DEFAULT_OPERATORS.number.multiple
+        : DEFAULT_OPERATORS.number.single
+  return upsertFilter(state, {
+    columnId: column.id,
+    type: 'number',
+    operator,
+    values: [...values],
+  })
+}
+
+export function setDateFilter<TData>(
+  state: FiltersState,
+  column: ColumnConfig<TData, 'date'>,
+  values: readonly Date[],
+): FiltersState {
+  if (values.length === 0) return removeFilter(state, column.id)
+  const existing = getFilter(state, column.id)
+  const operator: FilterOperators['date'] =
+    existing?.type === 'date'
+      ? determineNewOperator('date', existing.values, values, existing.operator)
+      : values.length > 1
+        ? DEFAULT_OPERATORS.date.multiple
+        : DEFAULT_OPERATORS.date.single
+  return upsertFilter(state, {
+    columnId: column.id,
+    type: 'date',
+    operator,
+    values: [...values],
+  })
+}
+
+export function setOptionFilter<TData>(
+  state: FiltersState,
+  column: ColumnConfig<TData, 'option'>,
+  values: readonly string[],
+): FiltersState {
+  if (values.length === 0) return removeFilter(state, column.id)
+  const existing = getFilter(state, column.id)
+  const operator: FilterOperators['option'] =
+    existing?.type === 'option'
+      ? determineNewOperator(
+          'option',
+          existing.values,
+          values,
+          existing.operator,
+        )
+      : values.length > 1
+        ? DEFAULT_OPERATORS.option.multiple
+        : DEFAULT_OPERATORS.option.single
+  return upsertFilter(state, {
+    columnId: column.id,
+    type: 'option',
+    operator,
+    values: [...values],
+  })
+}
+
+export function setMultiOptionFilter<TData>(
+  state: FiltersState,
+  column: ColumnConfig<TData, 'multiOption'>,
+  values: readonly string[],
+): FiltersState {
+  if (values.length === 0) return removeFilter(state, column.id)
+  const existing = getFilter(state, column.id)
+  const operator: FilterOperators['multiOption'] =
+    existing?.type === 'multiOption'
+      ? determineNewOperator(
+          'multiOption',
+          existing.values,
+          values,
+          existing.operator,
+        )
+      : values.length > 1
+        ? DEFAULT_OPERATORS.multiOption.multiple
+        : DEFAULT_OPERATORS.multiOption.single
+  return upsertFilter(state, {
+    columnId: column.id,
+    type: 'multiOption',
+    operator,
+    values: [...values],
+  })
+}
+
+/* ------------------------------------------------------------------ */
+/* Toggles — the facet-row / stats-row click path                      */
+/* ------------------------------------------------------------------ */
+
+function toggled(values: readonly string[], value: string): string[] {
+  return values.includes(value)
+    ? values.filter((candidate) => candidate !== value)
+    : [...values, value]
+}
+
+/** Add or remove one option value, promoting/demoting the operator with it. */
+export function toggleOptionValue<TData>(
+  state: FiltersState,
+  column: ColumnConfig<TData, 'option'>,
+  value: string,
+): FiltersState {
+  const existing = getFilter(state, column.id)
+  const current = existing?.type === 'option' ? existing.values : []
+  return setOptionFilter(state, column, toggled(current, value))
+}
+
+/** Add or remove one multi-option value. */
+export function toggleMultiOptionValue<TData>(
+  state: FiltersState,
+  column: ColumnConfig<TData, 'multiOption'>,
+  value: string,
+): FiltersState {
+  const existing = getFilter(state, column.id)
+  const current = existing?.type === 'multiOption' ? existing.values : []
+  return setMultiOptionFilter(state, column, toggled(current, value))
+}
+
+/** Swap a filter to its logical complement, leaving its values in place. */
+export function setFilterOperator(
+  state: FiltersState,
+  columnId: string,
+  operator: FilterModel['operator'],
+): FiltersState {
+  const existing = getFilter(state, columnId)
+  if (!existing) return state
+
+  switch (existing.type) {
+    case 'text':
+      return operator === 'contains' || operator === 'does not contain'
+        ? upsertFilter(state, { ...existing, operator })
+        : state
+    case 'number':
+      return isMemberOf(NUMBER_OPERATORS, operator)
+        ? upsertFilter(state, { ...existing, operator })
+        : state
+    case 'date':
+      return isMemberOf(DATE_OPERATORS, operator)
+        ? upsertFilter(state, { ...existing, operator })
+        : state
+    case 'option':
+      return isMemberOf(OPTION_OPERATORS, operator)
+        ? upsertFilter(state, { ...existing, operator })
+        : state
+    case 'multiOption':
+      return isMemberOf(MULTI_OPTION_OPERATORS, operator)
+        ? upsertFilter(state, { ...existing, operator })
+        : state
+  }
+}
+
+const NUMBER_OPERATORS = [
+  'is',
+  'is not',
+  'is greater than',
+  'is greater than or equal to',
+  'is less than',
+  'is less than or equal to',
+  'is between',
+  'is not between',
+] as const
+
+const DATE_OPERATORS = [
+  'is',
+  'is not',
+  'is before',
+  'is on or after',
+  'is after',
+  'is on or before',
+  'is between',
+  'is not between',
+] as const
+
+const OPTION_OPERATORS = ['is', 'is not', 'is any of', 'is none of'] as const
+
+const MULTI_OPTION_OPERATORS = [
+  'include',
+  'exclude',
+  'include any of',
+  'include all of',
+  'exclude if any of',
+  'exclude if all',
+] as const
+
+function isMemberOf<T extends string>(
+  allowed: readonly T[],
+  value: string,
+): value is T {
+  return (allowed as readonly string[]).includes(value)
+}