@lovett/ui 0.0.11 → 0.2.0

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

@@ -0,0 +1,350 @@
+/**
+ * URL serialisation, and the defensive parse of untrusted input.
+ *
+ * A query string is hand-editable and shareable, so `parseFilters` must never
+ * throw and must never let a malformed entry through to the predicates.
+ */
+import { describe, expect, it } from 'vitest'
+import {
+  FILTERS_SEARCH_PARAM,
+  filterRows,
+  defineColumns,
+  parseFilters,
+  serializeFilters,
+} from '../index'
+import type { FiltersState } from '../index'
+
+const roundTrip = (state: FiltersState): FiltersState =>
+  parseFilters(serializeFilters(state))
+
+describe('serializeFilters', () => {
+  it('serialises an empty state to the empty string', () => {
+    // The caller's cue to DELETE the param rather than write ?filters=[].
+    expect(serializeFilters([])).toBe('')
+  })
+
+  it('names the conventional search param', () => {
+    expect(FILTERS_SEARCH_PARAM).toBe('filters')
+  })
+
+  it('survives a URLSearchParams round trip', () => {
+    const state: FiltersState = [
+      { columnId: 'priority', type: 'option', operator: 'is any of', values: ['high', 'low'] },
+    ]
+    const params = new URLSearchParams()
+    params.set(FILTERS_SEARCH_PARAM, serializeFilters(state))
+    const back = parseFilters(new URLSearchParams(params.toString()).get(FILTERS_SEARCH_PARAM))
+    expect(back).toEqual(state)
+  })
+})
+
+describe('parseFilters round trip', () => {
+  it('round-trips an option filter', () => {
+    const state: FiltersState = [
+      { columnId: 'priority', type: 'option', operator: 'is any of', values: ['high', 'low'] },
+    ]
+    expect(roundTrip(state)).toEqual(state)
+  })
+
+  it('round-trips a text filter', () => {
+    const state: FiltersState = [
+      { columnId: 'title', type: 'text', operator: 'does not contain', values: ['rail'] },
+    ]
+    expect(roundTrip(state)).toEqual(state)
+  })
+
+  it('round-trips a number between filter', () => {
+    const state: FiltersState = [
+      { columnId: 'points', type: 'number', operator: 'is between', values: [1, 9] },
+    ]
+    expect(roundTrip(state)).toEqual(state)
+  })
+
+  it('round-trips a date filter as real Date instances', () => {
+    const state: FiltersState = [
+      {
+        columnId: 'due',
+        type: 'date',
+        operator: 'is between',
+        values: [new Date(2026, 0, 1), new Date(2026, 0, 31)],
+      },
+    ]
+    const back = roundTrip(state)
+    const first = back[0]
+    expect(first?.type).toBe('date')
+    expect(back).toEqual(state)
+    if (first?.type === 'date') {
+      expect(first.values[0]).toBeInstanceOf(Date)
+      expect(first.values[0]?.getTime()).toBe(new Date(2026, 0, 1).getTime())
+    }
+  })
+
+  it('round-trips a multiOption filter', () => {
+    const state: FiltersState = [
+      { columnId: 'labels', type: 'multiOption', operator: 'include all of', values: ['bug', 'ui'] },
+    ]
+    expect(roundTrip(state)).toEqual(state)
+  })
+
+  it('round-trips several columns at once, in order', () => {
+    const state: FiltersState = [
+      { columnId: 'priority', type: 'option', operator: 'is', values: ['high'] },
+      { columnId: 'title', type: 'text', operator: 'contains', values: ['ship'] },
+      { columnId: 'points', type: 'number', operator: 'is greater than', values: [2] },
+    ]
+    expect(roundTrip(state)).toEqual(state)
+  })
+
+  it('produces a state that still filters after the trip', () => {
+    interface Row { readonly id: string; readonly priority: string }
+    const columns = defineColumns<Row>([
+      {
+        id: 'priority',
+        type: 'option',
+        displayName: 'Priority',
+        accessor: (r) => r.priority,
+        options: [
+          { value: 'high', label: 'High' },
+          { value: 'low', label: 'Low' },
+        ],
+      },
+    ])
+    const rows: Row[] = [
+      { id: 'a', priority: 'high' },
+      { id: 'b', priority: 'low' },
+    ]
+    const state = parseFilters(
+      serializeFilters([
+        { columnId: 'priority', type: 'option', operator: 'is', values: ['high'] },
+      ]),
+    )
+    expect(filterRows(rows, columns, state).map((r) => r.id)).toEqual(['a'])
+  })
+})
+
+describe('parseFilters is defensive', () => {
+  it('never throws, whatever it is handed', () => {
+    const hostile: unknown[] = [
+      null,
+      undefined,
+      '',
+      '   ',
+      'not json',
+      '{',
+      '{}',
+      '"a string"',
+      '42',
+      'null',
+      42,
+      true,
+      {},
+      [],
+      [null],
+      [[]],
+      new Date(),
+      Symbol('nope'),
+      () => undefined,
+    ]
+    for (const input of hostile) {
+      expect(() => parseFilters(input)).not.toThrow()
+      expect(Array.isArray(parseFilters(input))).toBe(true)
+    }
+  })
+
+  it('returns an empty state for a non-array payload', () => {
+    expect(parseFilters('{"columnId":"priority"}')).toEqual([])
+    expect(parseFilters('42')).toEqual([])
+  })
+
+  it('drops an entry that is not an object', () => {
+    expect(parseFilters('[1, "x", null, []]')).toEqual([])
+  })
+
+  it('drops an entry with an unknown column data type', () => {
+    expect(
+      parseFilters('[{"columnId":"a","type":"boolean","operator":"is","values":["x"]}]'),
+    ).toEqual([])
+  })
+
+  it('drops an entry with an operator that is not on that type', () => {
+    // "contains" is a text operator; it must not survive on an option column.
+    expect(
+      parseFilters('[{"columnId":"a","type":"option","operator":"contains","values":["x"]}]'),
+    ).toEqual([])
+    expect(
+      parseFilters('[{"columnId":"a","type":"option","operator":"is sort of","values":["x"]}]'),
+    ).toEqual([])
+  })
+
+  it('drops an entry whose values are not an array', () => {
+    expect(
+      parseFilters('[{"columnId":"a","type":"option","operator":"is","values":"high"}]'),
+    ).toEqual([])
+    expect(
+      parseFilters('[{"columnId":"a","type":"option","operator":"is","values":{"0":"high"}}]'),
+    ).toEqual([])
+    expect(
+      parseFilters('[{"columnId":"a","type":"option","operator":"is"}]'),
+    ).toEqual([])
+  })
+
+  it('drops an entry whose values are the wrong primitive for its type', () => {
+    expect(
+      parseFilters('[{"columnId":"a","type":"number","operator":"is","values":["5"]}]'),
+    ).toEqual([])
+    expect(
+      parseFilters('[{"columnId":"a","type":"option","operator":"is","values":[5]}]'),
+    ).toEqual([])
+    expect(
+      parseFilters('[{"columnId":"a","type":"date","operator":"is","values":["not a date"]}]'),
+    ).toEqual([])
+  })
+
+  it('drops a number filter carrying NaN or Infinity', () => {
+    // JSON has no NaN literal, so this arrives as an already-parsed value.
+    expect(
+      parseFilters([
+        { columnId: 'a', type: 'number', operator: 'is', values: [Number.NaN] },
+      ]),
+    ).toEqual([])
+    expect(
+      parseFilters([
+        {
+          columnId: 'a',
+          type: 'number',
+          operator: 'is',
+          values: [Number.POSITIVE_INFINITY],
+        },
+      ]),
+    ).toEqual([])
+  })
+
+  it('drops an entry whose value count the operator cannot use', () => {
+    // This is what keeps a hand-edited URL from reaching the arity throw in
+    // the predicates: "is between" with one value never gets that far.
+    expect(
+      parseFilters('[{"columnId":"a","type":"date","operator":"is between","values":["2026-01-01T00:00:00.000Z"]}]'),
+    ).toEqual([])
+    expect(
+      parseFilters('[{"columnId":"a","type":"option","operator":"is","values":["a","b"]}]'),
+    ).toEqual([])
+    expect(
+      parseFilters('[{"columnId":"a","type":"option","operator":"is any of","values":[]}]'),
+    ).toEqual([])
+  })
+
+  it('drops an entry with a blank or over-long column id', () => {
+    expect(
+      parseFilters('[{"columnId":"","type":"option","operator":"is","values":["x"]}]'),
+    ).toEqual([])
+    const long = 'c'.repeat(200)
+    expect(
+      parseFilters(
+        `[{"columnId":"${long}","type":"option","operator":"is","values":["x"]}]`,
+      ),
+    ).toEqual([])
+  })
+
+  it('drops an over-long value string', () => {
+    const long = 'v'.repeat(300)
+    expect(
+      parseFilters(
+        `[{"columnId":"a","type":"option","operator":"is","values":["${long}"]}]`,
+      ),
+    ).toEqual([])
+  })
+
+  it('drops an over-long payload outright', () => {
+    const filler = 'x'.repeat(9000)
+    expect(parseFilters(`["${filler}"]`)).toEqual([])
+  })
+
+  it('caps the number of filters and the number of values', () => {
+    const many = Array.from({ length: 40 }, (_, index) => ({
+      columnId: `c${index}`,
+      type: 'option',
+      operator: 'is',
+      values: ['x'],
+    }))
+    expect(parseFilters(many)).toHaveLength(32)
+
+    const wide = [
+      {
+        columnId: 'a',
+        type: 'option',
+        operator: 'is any of',
+        values: Array.from({ length: 100 }, (_, index) => `v${index}`),
+      },
+    ]
+    expect(parseFilters(wide)).toEqual([])
+  })
+
+  it('keeps the first entry when a column appears twice', () => {
+    const state = parseFilters([
+      { columnId: 'a', type: 'option', operator: 'is', values: ['first'] },
+      { columnId: 'a', type: 'option', operator: 'is', values: ['second'] },
+    ])
+    expect(state).toHaveLength(1)
+    expect(state[0]?.values).toEqual(['first'])
+  })
+
+  it('keeps the good entries alongside the bad ones', () => {
+    const state = parseFilters([
+      { columnId: 'a', type: 'nonsense', operator: 'is', values: ['x'] },
+      { columnId: 'b', type: 'option', operator: 'is', values: ['high'] },
+      'garbage',
+    ])
+    expect(state).toHaveLength(1)
+    expect(state[0]?.columnId).toBe('b')
+  })
+})
+
+describe('parseFilters resists prototype pollution', () => {
+  it('rejects a prototype-shaped column id', () => {
+    for (const id of ['__proto__', 'constructor', 'prototype']) {
+      expect(
+        parseFilters(
+          `[{"columnId":"${id}","type":"option","operator":"is","values":["x"]}]`,
+        ),
+      ).toEqual([])
+    }
+  })
+
+  it('does not pollute Object.prototype from a __proto__ payload', () => {
+    parseFilters('[{"__proto__":{"polluted":true},"columnId":"a","type":"option","operator":"is","values":["x"]}]')
+    parseFilters('{"__proto__":{"polluted":true}}')
+    const probe: Record<string, unknown> = {}
+    expect(probe['polluted']).toBeUndefined()
+    expect(Object.hasOwn(Object.prototype, 'polluted')).toBe(false)
+  })
+
+  it('does not read inherited properties as filter fields', () => {
+    // A parsed object whose fields live on its PROTOTYPE must not be
+    // accepted: only own properties count.
+    const inherited = Object.create({
+      columnId: 'a',
+      type: 'option',
+      operator: 'is',
+      values: ['x'],
+    }) as object
+    expect(parseFilters([inherited])).toEqual([])
+  })
+
+  it('never copies extra keys into the parsed model', () => {
+    const state = parseFilters([
+      {
+        columnId: 'a',
+        type: 'option',
+        operator: 'is',
+        values: ['x'],
+        extra: 'should not survive',
+      },
+    ])
+    expect(state[0]).toEqual({
+      columnId: 'a',
+      type: 'option',
+      operator: 'is',
+      values: ['x'],
+    })
+  })
+})

package/src/filter-core/columns.ts

@@ -0,0 +1,134 @@
+/**
+ * @package @lovett/ui
+ * @file filter-core/columns.ts
+ *
+ * Column config validation. This is where "a type we cannot handle" becomes a
+ * THROWN ERROR AT CONFIG TIME.
+ *
+ * The source had no such gate: its combinator listed cases for `option` and
+ * `multiOption` and fell through to `return true` for everything else
+ * (issue-filter-columns.tsx:187-188). Declaring a date column there did not
+ * fail loudly — it silently disabled filtering on that column, which looks
+ * exactly like "the filter matched everything".
+ */
+
+import { COLUMN_DATA_TYPES } from './types'
+import type { AnyColumnConfig, ColumnDataType } from './types'
+
+/** Column ids that would collide with object plumbing. Rejected outright. */
+const RESERVED_IDS: ReadonlySet<string> = new Set([
+  '__proto__',
+  'constructor',
+  'prototype',
+])
+
+function isColumnDataType(value: unknown): value is ColumnDataType {
+  return (
+    typeof value === 'string' &&
+    (COLUMN_DATA_TYPES as readonly string[]).includes(value)
+  )
+}
+
+/**
+ * Validate a column set and hand it back.
+ *
+ * Call this once, at module scope, next to where the columns are declared —
+ * a config error then throws at import rather than at first render.
+ *
+ * Throws on: an unknown `type`, a missing/blank/reserved/duplicate `id`, a
+ * missing accessor or display name, an option column whose `options` are
+ * malformed or contain duplicate values, or a number column with `min > max`.
+ */
+export function defineColumns<TData>(
+  columns: ReadonlyArray<AnyColumnConfig<TData>>,
+): ReadonlyArray<AnyColumnConfig<TData>> {
+  const seenIds = new Set<string>()
+
+  for (const column of columns) {
+    const label = column.id ? `"${column.id}"` : '<missing id>'
+
+    if (typeof column.id !== 'string' || column.id.trim() === '') {
+      throw new Error('[filter-core] every column needs a non-empty string id')
+    }
+    if (RESERVED_IDS.has(column.id)) {
+      throw new Error(`[filter-core] column id ${label} is reserved`)
+    }
+    if (seenIds.has(column.id)) {
+      throw new Error(`[filter-core] duplicate column id ${label}`)
+    }
+    seenIds.add(column.id)
+
+    if (!isColumnDataType(column.type)) {
+      throw new Error(
+        `[filter-core] column ${label} declares unsupported type ` +
+          `"${String(column.type)}". Supported: ${COLUMN_DATA_TYPES.join(', ')}. ` +
+          'A type with no predicate must fail here, not filter to everything.',
+      )
+    }
+    if (typeof column.accessor !== 'function') {
+      throw new Error(`[filter-core] column ${label} needs an accessor function`)
+    }
+    if (typeof column.displayName !== 'string' || column.displayName === '') {
+      throw new Error(`[filter-core] column ${label} needs a displayName`)
+    }
+
+    if (column.type === 'option' || column.type === 'multiOption') {
+      const options = column.options
+      if (options !== undefined) {
+        if (!Array.isArray(options)) {
+          throw new Error(`[filter-core] column ${label} options must be an array`)
+        }
+        const seenValues = new Set<string>()
+        for (const option of options) {
+          if (
+            typeof option?.value !== 'string' ||
+            option.value === '' ||
+            typeof option.label !== 'string'
+          ) {
+            throw new Error(
+              `[filter-core] column ${label} has a malformed option; ` +
+                'each needs a non-empty string value and a string label',
+            )
+          }
+          if (seenValues.has(option.value)) {
+            throw new Error(
+              `[filter-core] column ${label} has duplicate option value "${option.value}"`,
+            )
+          }
+          seenValues.add(option.value)
+        }
+      }
+    }
+
+    if (column.type === 'number') {
+      const { min, max } = column
+      if (typeof min === 'number' && typeof max === 'number' && min > max) {
+        throw new Error(`[filter-core] column ${label} has min greater than max`)
+      }
+    }
+  }
+
+  return columns
+}
+
+/** Index a column set by id, for O(1) lookup while filtering. */
+export function indexColumns<TData>(
+  columns: ReadonlyArray<AnyColumnConfig<TData>>,
+): ReadonlyMap<string, AnyColumnConfig<TData>> {
+  const index = new Map<string, AnyColumnConfig<TData>>()
+  for (const column of columns) index.set(column.id, column)
+  return index
+}
+
+/**
+ * Narrow a column of unknown type to one specific type.
+ *
+ * A real runtime check, not a cast: the discriminant is read before the
+ * predicate returns true.
+ */
+export function isColumnOfType<TData, TType extends ColumnDataType>(
+  column: AnyColumnConfig<TData>,
+  type: TType,
+): column is Extract<AnyColumnConfig<TData>, { type: TType }> {
+  return column.type === type
+}

package/src/filter-core/date-utils.ts

@@ -0,0 +1,38 @@
+/**
+ * @package @lovett/ui
+ * @file filter-core/date-utils.ts
+ *
+ * Day-granular date helpers.
+ *
+ * The source used date-fns. `date-fns` is not a dependency of @lovett/ui and
+ * these four functions are the whole of what was used, so they are inlined
+ * rather than pulling a runtime dependency into the design system (CLAUDE.md
+ * §1 — a new runtime dep needs an ADR).
+ *
+ * All boundaries are LOCAL time. A board filter reads "due today" against the
+ * user's calendar day, not UTC.
+ */
+
+/** Midnight at the start of `date`'s local day. */
+export function startOfDay(date: Date): Date {
+  const result = new Date(date.getTime())
+  result.setHours(0, 0, 0, 0)
+  return result
+}
+
+/** The last millisecond of `date`'s local day. */
+export function endOfDay(date: Date): Date {
+  const result = new Date(date.getTime())
+  result.setHours(23, 59, 59, 999)
+  return result
+}
+
+/** Whether two instants fall on the same local calendar day. */
+export function isSameDay(a: Date, b: Date): boolean {
+  return startOfDay(a).getTime() === startOfDay(b).getTime()
+}
+
+/** A `Date` that is not Invalid Date. */
+export function isValidDate(value: unknown): value is Date {
+  return value instanceof Date && !Number.isNaN(value.getTime())
+}

package/src/filter-core/examples/task-filter-columns.ts

@@ -0,0 +1,121 @@
+/**
+ * @package @lovett/ui
+ * @file filter-core/examples/task-filter-columns.ts
+ *
+ * EXAMPLE — NOT PART OF THE CORE, AND NOT EXPORTED FROM `filter-core/index`.
+ *
+ * This is what a Tasks-board column set looks like against the generic model.
+ * It is here so the intended usage is visible next to the code, and so the
+ * type gating is exercised by something shaped like the real thing. The real
+ * board declares its own columns in the lens, over the lens's own row type
+ * and its own lane/label data — do not import this into a lens.
+ *
+ * Two patterns worth copying:
+ *
+ *  1. THE SENTINEL. `number`/`date` filters exclude rows with no value (see
+ *     the note at the top of filter-fns.ts), and "unassigned" is a state a
+ *     user genuinely wants to filter FOR. So the accessor maps absence onto a
+ *     real option value rather than returning null. Same for priority `none`.
+ *
+ *  2. LANES AS OPTIONS. The board's columns are data, so `options` here is
+ *     built from the board rather than hardcoded — which is also what makes
+ *     the facet list able to show a lane with a count of zero.
+ */
+
+import { defineColumns } from '../columns'
+import type { AnyColumnConfig, ColumnOption } from '../types'
+
+/** The row shape this example filters. The real lens has its own. */
+export interface ExampleTaskRow {
+  readonly id: string
+  readonly title: string
+  readonly columnId: string
+  readonly priority: 'none' | 'low' | 'medium' | 'high'
+  readonly assigneeId: string | null
+  readonly dateLabel: Date | null
+  readonly endDate: Date | null
+  readonly labelIds: readonly string[]
+}
+
+/** The sentinel option value standing in for "nobody is assigned". */
+export const UNASSIGNED = 'unassigned'
+
+export const PRIORITY_OPTIONS: readonly ColumnOption[] = [
+  { value: 'none', label: 'No priority', icon: 'Minus' },
+  { value: 'low', label: 'Low', icon: 'SignalLow' },
+  { value: 'medium', label: 'Medium', icon: 'SignalMedium' },
+  { value: 'high', label: 'High', icon: 'SignalHigh' },
+]
+
+export interface ExampleBoardMeta {
+  /** The board's lanes, in board order. */
+  readonly lanes: readonly ColumnOption[]
+  /** Assignable people. The `unassigned` sentinel is prepended for you. */
+  readonly assignees: readonly ColumnOption[]
+  /** Labels available on this board. */
+  readonly labels: readonly ColumnOption[]
+}
+
+/**
+ * Build the Tasks board's filter columns.
+ *
+ * `defineColumns` validates at call time, so a typo in a type or a duplicate
+ * option value throws where the columns are declared rather than showing up
+ * as a filter that matches everything.
+ */
+export function createTaskFilterColumns(
+  meta: ExampleBoardMeta,
+): ReadonlyArray<AnyColumnConfig<ExampleTaskRow>> {
+  return defineColumns<ExampleTaskRow>([
+    {
+      id: 'title',
+      type: 'text',
+      displayName: 'Title',
+      accessor: (task) => task.title,
+    },
+    {
+      id: 'column',
+      type: 'option',
+      displayName: 'Column',
+      accessor: (task) => task.columnId,
+      options: meta.lanes,
+    },
+    {
+      id: 'priority',
+      type: 'option',
+      displayName: 'Priority',
+      accessor: (task) => task.priority,
+      options: PRIORITY_OPTIONS,
+    },
+    {
+      id: 'assignee',
+      type: 'option',
+      displayName: 'Assignee',
+      // The sentinel: absence becomes a filterable value.
+      accessor: (task) => task.assigneeId ?? UNASSIGNED,
+      options: [
+        { value: UNASSIGNED, label: 'Unassigned', icon: 'CircleDashed' },
+        ...meta.assignees,
+      ],
+    },
+    {
+      id: 'dateLabel',
+      type: 'date',
+      displayName: 'Date',
+      accessor: (task) => task.dateLabel,
+    },
+    {
+      id: 'endDate',
+      type: 'date',
+      displayName: 'Due',
+      accessor: (task) => task.endDate,
+    },
+    {
+      id: 'labels',
+      type: 'multiOption',
+      displayName: 'Labels',
+      accessor: (task) => task.labelIds,
+      options: meta.labels,
+    },
+  ])
+}