@lovett/ui 0.0.11 → 0.2.0

package/src/filter-core/faceting.ts

@@ -0,0 +1,120 @@
+/**
+ * @package @lovett/ui
+ * @file filter-core/faceting.ts
+ *
+ * Faceted counts, as PURE FUNCTIONS of the rows you pass in.
+ *
+ * THIS IS BUG FIX #3. The source computed facet counts inside a `useMemo`
+ * with an EMPTY dependency array (filter-value.tsx:481-489), so the numbers
+ * froze at popover-mount: adding a filter changed the board and left the
+ * facet counts showing the previous world. There is no memo, no lazy getter
+ * and no cache class here — counts are derived from the rows given, so they
+ * cannot go stale. Callers memoize with the row array as the dependency.
+ */
+
+import { filterRows } from './filter-fns'
+import { isColumnOfType } from './columns'
+import type { AnyColumnConfig, FiltersState } from './types'
+
+/**
+ * Count rows per option value for an `option` / `multiOption` column.
+ *
+ * Every value declared in `column.options` is present in the result, INCLUDING
+ * the ones no row has — a facet list that quietly omits its empty buckets
+ * reads as "this option does not exist" rather than "nothing matches". Values
+ * found in the data but not declared are appended after the declared ones.
+ *
+ * Throws for a column type that has no facets; asking a text column for its
+ * value counts is a programming error, not a runtime condition.
+ */
+export function facetedCounts<TData>(
+  rows: readonly TData[],
+  column: AnyColumnConfig<TData>,
+): Map<string, number> {
+  const counts = new Map<string, number>()
+
+  if (isColumnOfType(column, 'option')) {
+    for (const option of column.options ?? []) counts.set(option.value, 0)
+    for (const row of rows) {
+      const value = column.accessor(row)
+      if (typeof value !== 'string') continue
+      counts.set(value, (counts.get(value) ?? 0) + 1)
+    }
+    return counts
+  }
+
+  if (isColumnOfType(column, 'multiOption')) {
+    for (const option of column.options ?? []) counts.set(option.value, 0)
+    for (const row of rows) {
+      const values = column.accessor(row)
+      if (!values) continue
+      // A row counts once per DISTINCT value it carries, so a duplicated
+      // label on one task cannot inflate the facet past the row count.
+      for (const value of new Set(values)) {
+        if (typeof value !== 'string') continue
+        counts.set(value, (counts.get(value) ?? 0) + 1)
+      }
+    }
+    return counts
+  }
+
+  throw new Error(
+    `[filter-core] facetedCounts is only defined for option and multiOption ` +
+      `columns; "${column.id}" is "${column.type}"`,
+  )
+}
+
+/**
+ * The rows a facet list for `columnId` should count: everything surviving
+ * every OTHER column's filters.
+ *
+ * Counting against the fully filtered set would zero every unselected option
+ * the moment one is picked, which makes the list unusable for widening a
+ * selection. Excluding the column's own filter is the standard behaviour and
+ * it stays a pure function of `(rows, columns, filters)`.
+ */
+export function facetedRowsFor<TData>(
+  rows: readonly TData[],
+  columns: ReadonlyArray<AnyColumnConfig<TData>>,
+  filters: FiltersState,
+  columnId: string,
+): TData[] {
+  return filterRows(
+    rows,
+    columns,
+    filters.filter((filter) => filter.columnId !== columnId),
+  )
+}
+
+/**
+ * The observed `[min, max]` of a number column, or its declared bounds when
+ * both are configured. `null` when neither is available.
+ */
+export function facetedMinMax<TData>(
+  rows: readonly TData[],
+  column: AnyColumnConfig<TData>,
+): readonly [number, number] | null {
+  if (!isColumnOfType(column, 'number')) {
+    throw new Error(
+      `[filter-core] facetedMinMax is only defined for number columns; ` +
+        `"${column.id}" is "${column.type}"`,
+    )
+  }
+
+  const { min, max } = column
+  if (typeof min === 'number' && typeof max === 'number') return [min, max]
+
+  let low = Number.POSITIVE_INFINITY
+  let high = Number.NEGATIVE_INFINITY
+  let seen = false
+
+  for (const row of rows) {
+    const value = column.accessor(row)
+    if (typeof value !== 'number' || Number.isNaN(value)) continue
+    seen = true
+    if (value < low) low = value
+    if (value > high) high = value
+  }
+
+  return seen ? [low, high] : null
+}

package/src/filter-core/filter-fns.ts

@@ -0,0 +1,335 @@
+/**
+ * @package @lovett/ui
+ * @file filter-core/filter-fns.ts
+ *
+ * The predicates — one per column type — and the combinator over them.
+ *
+ * Semantics:
+ *   - ACROSS columns: AND. Every filter in the state must pass.
+ *   - WITHIN a column: the operator decides. `is any of` is an OR over the
+ *     value list; `include all of` is an AND over it.
+ *   - An empty value list is a no-op filter (passes everything), so a
+ *     half-built filter chip never blanks the board.
+ *
+ * Missing values. Each predicate takes `Nullable<T>` because an accessor is
+ * allowed to return nothing, and the answer is not the same for every type:
+ *   - text  — a missing value behaves as the empty string, so `does not
+ *             contain "x"` is TRUE for a row with no title. The source
+ *             returned false for both halves of the pair, which made the two
+ *             operators non-complementary.
+ *   - option / multiOption — a missing value matches no positive operator and
+ *             every negated one, for the same reason.
+ *   - number / date — a missing value matches NOTHING, including the negated
+ *             operators. "Due before Friday" over a task with no due date is
+ *             not a question with a true answer; excluding it is the
+ *             behaviour a board wants. Config-level sentinels (see the
+ *             `assignee` example) are the way to make absence filterable.
+ */
+
+import { isColumnOfType } from './columns'
+import { endOfDay, isSameDay, startOfDay } from './date-utils'
+import { operatorDetails } from './operators'
+import type {
+  AnyColumnConfig,
+  FilterModel,
+  FiltersState,
+  Nullable,
+} from './types'
+
+/* ------------------------------------------------------------------ */
+/* Arity guards                                                        */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Assert a filter carries the number of values its operator requires.
+ *
+ * THIS IS BUG FIX #1. The source wrote the plural half as
+ *
+ *     filterValue.operator in ['is between', 'is not between']
+ *
+ * (filter-fns.ts:80). `in` on an ARRAY tests index keys — '0', '1', 'length'
+ * — so the condition is false for every operator and the guard never fired.
+ * A one-value `is between` sailed past it into an interval with an undefined
+ * end. Here the requirement is read off the operator table's `arity`, which
+ * cannot be written that way.
+ */
+function assertArity(filter: FilterModel): void {
+  const details = operatorDetails(filter.type, filter.operator)
+  const count = filter.values.length
+
+  if (details.arity === 'one' && count > 1) {
+    throw new Error(
+      `[filter-core] operator "${filter.operator}" on column ` +
+        `"${filter.columnId}" takes at most one value, got ${count}`,
+    )
+  }
+  if (details.arity === 'two' && count !== 2) {
+    throw new Error(
+      `[filter-core] operator "${filter.operator}" on column ` +
+        `"${filter.columnId}" requires exactly two values, got ${count}`,
+    )
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* Predicates                                                          */
+/* ------------------------------------------------------------------ */
+
+export function textFilterFn(
+  input: Nullable<string>,
+  filter: FilterModel<'text'>,
+): boolean {
+  assertArity(filter)
+  const needle = filter.values[0]
+  if (needle === undefined) return true
+
+  const trimmed = needle.toLowerCase().trim()
+  if (trimmed === '') return true
+
+  const found = (input ?? '').toLowerCase().trim().includes(trimmed)
+
+  switch (filter.operator) {
+    case 'contains':
+      return found
+    case 'does not contain':
+      return !found
+  }
+}
+
+export function numberFilterFn(
+  input: Nullable<number>,
+  filter: FilterModel<'number'>,
+): boolean {
+  assertArity(filter)
+  const first = filter.values[0]
+  if (first === undefined) return true
+  if (typeof input !== 'number' || Number.isNaN(input)) return false
+
+  switch (filter.operator) {
+    case 'is':
+      return input === first
+    case 'is not':
+      return input !== first
+    case 'is greater than':
+      return input > first
+    case 'is greater than or equal to':
+      return input >= first
+    case 'is less than':
+      return input < first
+    case 'is less than or equal to':
+      return input <= first
+    case 'is between':
+    case 'is not between': {
+      const second = filter.values[1]
+      // assertArity has already guaranteed two values.
+      if (second === undefined) return true
+      const lower = Math.min(first, second)
+      const upper = Math.max(first, second)
+      const within = input >= lower && input <= upper
+      return filter.operator === 'is between' ? within : !within
+    }
+  }
+}
+
+export function dateFilterFn(
+  input: Nullable<Date>,
+  filter: FilterModel<'date'>,
+): boolean {
+  assertArity(filter)
+  const first = filter.values[0]
+  if (first === undefined) return true
+  if (!(input instanceof Date) || Number.isNaN(input.getTime())) return false
+
+  switch (filter.operator) {
+    case 'is':
+      return isSameDay(input, first)
+    case 'is not':
+      return !isSameDay(input, first)
+    case 'is before':
+      return input.getTime() < startOfDay(first).getTime()
+    case 'is on or after':
+      return input.getTime() >= startOfDay(first).getTime()
+    case 'is after':
+      return input.getTime() > endOfDay(first).getTime()
+    case 'is on or before':
+      return input.getTime() <= endOfDay(first).getTime()
+    case 'is between':
+    case 'is not between': {
+      const second = filter.values[1]
+      // assertArity has already guaranteed two values.
+      if (second === undefined) return true
+      const [lower, upper] =
+        first.getTime() <= second.getTime() ? [first, second] : [second, first]
+      const within =
+        input.getTime() >= startOfDay(lower).getTime() &&
+        input.getTime() <= endOfDay(upper).getTime()
+      return filter.operator === 'is between' ? within : !within
+    }
+  }
+}
+
+export function optionFilterFn(
+  input: Nullable<string>,
+  filter: FilterModel<'option'>,
+): boolean {
+  assertArity(filter)
+  if (filter.values.length === 0) return true
+
+  // Exact match, not case-folded. Option values are ids; lower-casing them
+  // (as the source did) silently collides two options that differ by case.
+  const found = input != null && filter.values.includes(input)
+
+  switch (filter.operator) {
+    case 'is':
+    case 'is any of':
+      return found
+    case 'is not':
+    case 'is none of':
+      return !found
+  }
+}
+
+export function multiOptionFilterFn(
+  input: Nullable<readonly string[]>,
+  filter: FilterModel<'multiOption'>,
+): boolean {
+  assertArity(filter)
+  if (filter.values.length === 0) return true
+
+  const present = new Set(input ?? [])
+  const selected = filter.values
+  const anyPresent = selected.some((value) => present.has(value))
+  const allPresent = selected.every((value) => present.has(value))
+
+  switch (filter.operator) {
+    case 'include':
+    case 'include any of':
+      return anyPresent
+    case 'include all of':
+      return allPresent
+    case 'exclude':
+    case 'exclude if any of':
+      return !anyPresent
+    case 'exclude if all':
+      return !allPresent
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* Combinator                                                          */
+/* ------------------------------------------------------------------ */
+
+/** Unreachable-branch guard. A new ColumnDataType fails to compile here. */
+function assertNever(value: never, message: string): never {
+  throw new Error(`${message}: ${JSON.stringify(value)}`)
+}
+
+/**
+ * Test one row against one filter, through one column.
+ *
+ * THIS IS BUG FIX #2. Every declared type has a case; there is no fallthrough
+ * `return true`. A filter whose type disagrees with its column's THROWS —
+ * a state that only arises from a programming error, since `pruneFilters`
+ * drops such a filter when it comes off the URL.
+ */
+export function rowMatchesFilter<TData>(
+  row: TData,
+  column: AnyColumnConfig<TData>,
+  filter: FilterModel,
+): boolean {
+  const mismatch = (): never => {
+    throw new Error(
+      `[filter-core] filter on column "${filter.columnId}" is typed ` +
+        `"${filter.type}" but the column is "${column.type}"`,
+    )
+  }
+
+  switch (filter.type) {
+    case 'text':
+      return isColumnOfType(column, 'text')
+        ? textFilterFn(column.accessor(row), filter)
+        : mismatch()
+    case 'number':
+      return isColumnOfType(column, 'number')
+        ? numberFilterFn(column.accessor(row), filter)
+        : mismatch()
+    case 'date':
+      return isColumnOfType(column, 'date')
+        ? dateFilterFn(column.accessor(row), filter)
+        : mismatch()
+    case 'option':
+      return isColumnOfType(column, 'option')
+        ? optionFilterFn(column.accessor(row), filter)
+        : mismatch()
+    case 'multiOption':
+      return isColumnOfType(column, 'multiOption')
+        ? multiOptionFilterFn(column.accessor(row), filter)
+        : mismatch()
+    default:
+      return assertNever(filter, '[filter-core] unhandled filter type')
+  }
+}
+
+/**
+ * Drop filters that cannot be applied to this column set: an unknown column
+ * id (a stale link after a column was renamed) or a type that disagrees with
+ * the column's declared type (a hand-edited URL). Also collapses duplicate
+ * entries for one column, keeping the first.
+ *
+ * Dropping is right here and throwing is right in `rowMatchesFilter`, because
+ * this is where UNTRUSTED input meets the config. CLAUDE.md: parse at the
+ * boundary, and let broken invariants throw further in.
+ */
+export function pruneFilters<TData>(
+  filters: FiltersState,
+  columns: ReadonlyArray<AnyColumnConfig<TData>>,
+): FiltersState {
+  const byId = new Map(columns.map((column) => [column.id, column]))
+  const kept: FiltersState = []
+  const seen = new Set<string>()
+
+  for (const filter of filters) {
+    const column = byId.get(filter.columnId)
+    if (!column) continue
+    if (column.type !== filter.type) continue
+    if (seen.has(filter.columnId)) continue
+    seen.add(filter.columnId)
+    kept.push(filter)
+  }
+
+  return kept
+}
+
+/** Whether a row survives every filter in the state. AND across columns. */
+export function rowMatchesFilters<TData>(
+  row: TData,
+  columns: ReadonlyMap<string, AnyColumnConfig<TData>>,
+  filters: FiltersState,
+): boolean {
+  for (const filter of filters) {
+    const column = columns.get(filter.columnId)
+    // An unknown column id is not a filter we can honour. Ignore it rather
+    // than blanking the board; pruneFilters is how a caller sees it happen.
+    if (!column) continue
+    if (!rowMatchesFilter(row, column, filter)) return false
+  }
+  return true
+}
+
+/**
+ * Apply a filter state to a row set. Pure — same inputs, same output, no
+ * caching. The caller memoizes.
+ */
+export function filterRows<TData>(
+  rows: readonly TData[],
+  columns: ReadonlyArray<AnyColumnConfig<TData>>,
+  filters: FiltersState,
+): TData[] {
+  if (filters.length === 0) return [...rows]
+
+  const byId = new Map(columns.map((column) => [column.id, column]))
+  const applicable = pruneFilters(filters, columns)
+  if (applicable.length === 0) return [...rows]
+
+  return rows.filter((row) => rowMatchesFilters(row, byId, applicable))
+}

package/src/filter-core/index.ts

@@ -0,0 +1,105 @@
+/**
+ * @package @lovett/ui
+ * @file filter-core/index.ts
+ *
+ * `filter-core` — the pure-TypeScript filter model behind the board header.
+ *
+ * Zero React, zero CSS, zero domain knowledge, zero runtime dependencies.
+ * The boundary is `ColumnConfig[]` in, `FiltersState` out; the UI layer sits
+ * on top of it and the URL is its persistence.
+ *
+ * Ported from bazza/ui's `data-table-filter` (vendored in continuity-control)
+ * with three of its bugs fixed on the way in — see the `THIS IS BUG FIX`
+ * comments in filter-fns.ts (arity guard, exhaustive combinator) and
+ * faceting.ts (counts as a pure function).
+ *
+ * The example config lives at ./examples/task-filter-columns and is NOT
+ * exported from here: it is illustration, not API.
+ */
+
+export {
+  COLUMN_DATA_TYPES,
+} from './types'
+
+export type {
+  AnyColumnConfig,
+  ColumnAccessor,
+  ColumnConfig,
+  ColumnDataNativeMap,
+  ColumnDataType,
+  ColumnOption,
+  ColumnValueMap,
+  DateFilterOperator,
+  ElementType,
+  FilterDetails,
+  FilterModel,
+  FilterOperatorArity,
+  FilterOperatorDetails,
+  FilterOperators,
+  FilterOperatorTarget,
+  FiltersState,
+  FilterTypeOperatorDetails,
+  FilterValues,
+  MultiOptionFilterOperator,
+  Nullable,
+  NumberFilterOperator,
+  OptionBasedColumnDataType,
+  OptionFilterOperator,
+  TextFilterOperator,
+} from './types'
+
+export {
+  DEFAULT_OPERATORS,
+  FILTER_OPERATOR_DETAILS,
+  dateFilterOperators,
+  determineNewOperator,
+  isOperatorOf,
+  multiOptionFilterOperators,
+  negateOperator,
+  numberFilterOperators,
+  operatorDetails,
+  operatorValueArity,
+  operatorsForType,
+  optionFilterOperators,
+  relatedOperators,
+  textFilterOperators,
+} from './operators'
+
+export type { FilterOperatorDetailsShape } from './operators'
+
+export { defineColumns, indexColumns, isColumnOfType } from './columns'
+
+export {
+  dateFilterFn,
+  filterRows,
+  multiOptionFilterFn,
+  numberFilterFn,
+  optionFilterFn,
+  pruneFilters,
+  rowMatchesFilter,
+  rowMatchesFilters,
+  textFilterFn,
+} from './filter-fns'
+
+export { facetedCounts, facetedMinMax, facetedRowsFor } from './faceting'
+
+export {
+  clearFilters,
+  getFilter,
+  removeFilter,
+  setDateFilter,
+  setFilterOperator,
+  setMultiOptionFilter,
+  setNumberFilter,
+  setOptionFilter,
+  setTextFilter,
+  toggleMultiOptionValue,
+  toggleOptionValue,
+  upsertFilter,
+} from './state'
+
+export {
+  FILTERS_SEARCH_PARAM,
+  parseFilters,
+  serializeFilters,
+} from './url'