@lovett/ui 0.0.10 → 0.1.0

package/src/filter-core/EXPORTS.md

@@ -0,0 +1,85 @@
+# filter-core — export wiring
+
+`packages/ui/src/filter-core/**` is self-contained and currently reachable
+only by its own path. Nothing outside this directory was edited.
+
+## The one line to add
+
+Append to `packages/ui/src/index.ts`:
+
+```ts
+// Board filter model — pure TypeScript, no React. See src/filter-core/index.ts.
+export * from './filter-core'
+```
+
+`filter-core/index.ts` is an explicit barrel (no wildcard re-exports of its
+own), so `export *` here surfaces exactly the list below and nothing else.
+Every type is exported with `export type`, so `verbatimModuleSyntax` is
+satisfied and none of it survives into the JS bundle.
+
+### If you would rather namespace it
+
+The alternative, if `@lovett/ui`'s top level should stay component-only:
+
+```json
+// packages/ui/package.json — "exports"
+"./filter-core": "./src/filter-core/index.ts"
+```
+
+…plus the matching `publishConfig.exports` entry and a second `tsup` entry
+(`entry: { index: 'src/index.ts', 'filter-core': 'src/filter-core/index.ts' }`).
+That is three edits instead of one; the flat `export *` is the cheaper default
+and there are no name collisions (checked against the current `src/index.ts`).
+
+## What that line surfaces
+
+**Values**
+
+```
+COLUMN_DATA_TYPES
+DEFAULT_OPERATORS, FILTER_OPERATOR_DETAILS
+textFilterOperators, numberFilterOperators, dateFilterOperators,
+optionFilterOperators, multiOptionFilterOperators
+operatorsForType, operatorDetails, operatorValueArity, relatedOperators,
+isOperatorOf, negateOperator, determineNewOperator
+defineColumns, indexColumns, isColumnOfType
+textFilterFn, numberFilterFn, dateFilterFn, optionFilterFn, multiOptionFilterFn
+rowMatchesFilter, rowMatchesFilters, pruneFilters, filterRows
+facetedCounts, facetedRowsFor, facetedMinMax
+getFilter, upsertFilter, removeFilter, clearFilters, setFilterOperator
+setTextFilter, setNumberFilter, setDateFilter, setOptionFilter,
+setMultiOptionFilter, toggleOptionValue, toggleMultiOptionValue
+FILTERS_SEARCH_PARAM, serializeFilters, parseFilters
+```
+
+**Types**
+
+```
+Nullable, ElementType
+ColumnDataType, OptionBasedColumnDataType, ColumnDataNativeMap, ColumnValueMap
+ColumnOption, ColumnAccessor, ColumnConfig, AnyColumnConfig
+FilterValues, FilterModel, FiltersState
+FilterOperators, FilterOperatorTarget, FilterOperatorArity
+FilterOperatorDetails, FilterOperatorDetailsShape, FilterDetails,
+FilterTypeOperatorDetails
+TextFilterOperator, NumberFilterOperator, DateFilterOperator,
+OptionFilterOperator, MultiOptionFilterOperator
+```
+
+## What it deliberately does NOT surface
+
+`./examples/task-filter-columns` — the Tasks-board column set is illustration,
+not API. The lens declares its own columns over its own row type. Import it
+only from a test or while reading.
+
+## Notes for whoever wires this
+
+- **No new dependency.** Nothing was added to `package.json` and nothing was
+  installed. `date-fns` (four helpers) is inlined in `date-utils.ts`.
+- **`zod` was asked for and is NOT used**, because zod is not a dependency of
+  `@lovett/ui` and adding one to the design system is an ADR-level call plus a
+  `package.json` edit — outside this change's scope. `url.ts` hand-validates to
+  the same standard (every field, every bound, fresh object literals) and is
+  funnelled through a single `parseEntry` so a zod schema can replace it in one
+  place if you want it later.
+- **CSS: none.** Nothing to add to `styles.css`.

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

@@ -0,0 +1,159 @@
+/**
+ * Config-time validation.
+ *
+ * BUG 2, the other half: a column type with no predicate must FAIL LOUDLY
+ * where the columns are declared. In the source, declaring a date column was
+ * accepted and then silently filtered to everything.
+ */
+import { describe, expect, it } from 'vitest'
+import { defineColumns, indexColumns, isColumnOfType } from '../index'
+import type { AnyColumnConfig } from '../index'
+
+interface Row {
+  readonly id: string
+  readonly name: string
+}
+
+/**
+ * Build a config the type system would reject, to exercise the RUNTIME gate.
+ * The double assertion is confined to this helper and is the only way to
+ * reach a validator whose whole job is catching what types cannot.
+ */
+function illegal(config: unknown): AnyColumnConfig<Row> {
+  return config as AnyColumnConfig<Row>
+}
+
+const ok = { id: 'name', displayName: 'Name', accessor: (r: Row) => r.name }
+
+describe('defineColumns', () => {
+  it('returns the columns it was given', () => {
+    const columns = defineColumns<Row>([{ ...ok, type: 'text' }])
+    expect(columns).toHaveLength(1)
+    expect(columns[0]?.id).toBe('name')
+  })
+
+  it('throws on an unsupported column type', () => {
+    expect(() =>
+      defineColumns<Row>([illegal({ ...ok, type: 'boolean' })]),
+    ).toThrow(/unsupported type "boolean"/)
+  })
+
+  it('throws on a missing type', () => {
+    expect(() => defineColumns<Row>([illegal({ ...ok })])).toThrow(
+      /unsupported type/,
+    )
+  })
+
+  it('throws on a blank id', () => {
+    expect(() =>
+      defineColumns<Row>([illegal({ ...ok, id: '  ', type: 'text' })]),
+    ).toThrow(/non-empty string id/)
+  })
+
+  it('throws on a reserved id', () => {
+    expect(() =>
+      defineColumns<Row>([illegal({ ...ok, id: '__proto__', type: 'text' })]),
+    ).toThrow(/reserved/)
+  })
+
+  it('throws on duplicate ids', () => {
+    expect(() =>
+      defineColumns<Row>([
+        { ...ok, type: 'text' },
+        { ...ok, type: 'text' },
+      ]),
+    ).toThrow(/duplicate column id/)
+  })
+
+  it('throws on a missing accessor or displayName', () => {
+    expect(() =>
+      defineColumns<Row>([illegal({ id: 'x', displayName: 'X', type: 'text' })]),
+    ).toThrow(/accessor function/)
+    expect(() =>
+      defineColumns<Row>([illegal({ ...ok, displayName: '', type: 'text' })]),
+    ).toThrow(/displayName/)
+  })
+
+  it('throws on a malformed option', () => {
+    expect(() =>
+      defineColumns<Row>([
+        illegal({ ...ok, type: 'option', options: [{ label: 'No value' }] }),
+      ]),
+    ).toThrow(/malformed option/)
+  })
+
+  it('throws on duplicate option values', () => {
+    expect(() =>
+      defineColumns<Row>([
+        {
+          ...ok,
+          type: 'option',
+          options: [
+            { value: 'a', label: 'A' },
+            { value: 'a', label: 'Also A' },
+          ],
+        },
+      ]),
+    ).toThrow(/duplicate option value/)
+  })
+
+  it('throws when a number column has min above max', () => {
+    expect(() =>
+      defineColumns<Row>([
+        illegal({ ...ok, type: 'number', min: 10, max: 1 }),
+      ]),
+    ).toThrow(/min greater than max/)
+  })
+
+  it('accepts every supported type', () => {
+    const columns = defineColumns<Row>([
+      { id: 'a', displayName: 'A', type: 'text', accessor: (r) => r.name },
+      { id: 'b', displayName: 'B', type: 'number', accessor: () => 1, min: 0, max: 5 },
+      { id: 'c', displayName: 'C', type: 'date', accessor: () => new Date() },
+      {
+        id: 'd',
+        displayName: 'D',
+        type: 'option',
+        accessor: (r) => r.name,
+        options: [{ value: 'x', label: 'X' }],
+      },
+      {
+        id: 'e',
+        displayName: 'E',
+        type: 'multiOption',
+        accessor: () => ['x'],
+        options: [{ value: 'x', label: 'X' }],
+      },
+    ])
+    expect(columns).toHaveLength(5)
+  })
+})
+
+describe('indexColumns / isColumnOfType', () => {
+  const columns = defineColumns<Row>([
+    { id: 'a', displayName: 'A', type: 'text', accessor: (r) => r.name },
+    {
+      id: 'b',
+      displayName: 'B',
+      type: 'option',
+      accessor: (r) => r.name,
+      options: [{ value: 'x', label: 'X' }],
+    },
+  ])
+
+  it('indexes by id', () => {
+    const index = indexColumns(columns)
+    expect(index.get('a')?.type).toBe('text')
+    expect(index.get('missing')).toBeUndefined()
+  })
+
+  it('narrows on the discriminant', () => {
+    const column = columns[1]
+    if (!column) throw new Error('fixture missing')
+    expect(isColumnOfType(column, 'option')).toBe(true)
+    expect(isColumnOfType(column, 'text')).toBe(false)
+    if (isColumnOfType(column, 'option')) {
+      expect(column.options?.[0]?.value).toBe('x')
+    }
+  })
+})

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

@@ -0,0 +1,193 @@
+/**
+ * Faceted counts.
+ *
+ * BUG 3 — the source computed counts inside a `useMemo` with an EMPTY
+ * dependency array (filter-value.tsx:481-489), so they froze at popover
+ * mount and disagreed with the board from the first filter onwards. These
+ * are pure functions of the rows passed in, so the same call with different
+ * rows must give different answers.
+ */
+import { describe, expect, it } from 'vitest'
+import {
+  defineColumns,
+  facetedCounts,
+  facetedMinMax,
+  facetedRowsFor,
+  filterRows,
+} from '../index'
+import type { AnyColumnConfig, FiltersState } from '../index'
+
+interface Task {
+  readonly id: string
+  readonly priority: string | null
+  readonly labels: readonly string[]
+  readonly points: number | null
+}
+
+const columns = defineColumns<Task>([
+  {
+    id: 'priority',
+    type: 'option',
+    displayName: 'Priority',
+    accessor: (t) => t.priority,
+    options: [
+      { value: 'low', label: 'Low' },
+      { value: 'medium', label: 'Medium' },
+      { value: 'high', label: 'High' },
+    ],
+  },
+  {
+    id: 'labels',
+    type: 'multiOption',
+    displayName: 'Labels',
+    accessor: (t) => t.labels,
+    options: [
+      { value: 'bug', label: 'Bug' },
+      { value: 'ui', label: 'UI' },
+      { value: 'perf', label: 'Perf' },
+    ],
+  },
+  {
+    id: 'points',
+    type: 'number',
+    displayName: 'Points',
+    accessor: (t) => t.points,
+  },
+])
+
+function columnById(id: string): AnyColumnConfig<Task> {
+  const column = columns.find((candidate) => candidate.id === id)
+  if (!column) throw new Error(`no column ${id}`)
+  return column
+}
+
+const rows: Task[] = [
+  { id: 'a', priority: 'high', labels: ['bug'], points: 3 },
+  { id: 'b', priority: 'high', labels: ['ui', 'bug'], points: 8 },
+  { id: 'c', priority: 'low', labels: [], points: null },
+  { id: 'd', priority: null, labels: ['ui'], points: 5 },
+]
+
+describe('facetedCounts', () => {
+  it('counts option values', () => {
+    const counts = facetedCounts(rows, columnById('priority'))
+    expect(counts.get('high')).toBe(2)
+    expect(counts.get('low')).toBe(1)
+  })
+
+  it('keeps declared options with no rows as zero buckets', () => {
+    const counts = facetedCounts(rows, columnById('priority'))
+    expect(counts.has('medium')).toBe(true)
+    expect(counts.get('medium')).toBe(0)
+  })
+
+  it('lists declared options first, in declaration order', () => {
+    const counts = facetedCounts(rows, columnById('priority'))
+    expect([...counts.keys()]).toEqual(['low', 'medium', 'high'])
+  })
+
+  it('ignores rows with no value rather than inventing a bucket', () => {
+    const counts = facetedCounts(rows, columnById('priority'))
+    const total = [...counts.values()].reduce((sum, n) => sum + n, 0)
+    expect(total).toBe(3)
+  })
+
+  it('counts each member of a multiOption column', () => {
+    const counts = facetedCounts(rows, columnById('labels'))
+    expect(counts.get('bug')).toBe(2)
+    expect(counts.get('ui')).toBe(2)
+    expect(counts.get('perf')).toBe(0)
+  })
+
+  it('counts a row once per distinct value, not once per occurrence', () => {
+    const duplicated: Task[] = [
+      { id: 'x', priority: null, labels: ['bug', 'bug'], points: null },
+    ]
+    expect(facetedCounts(duplicated, columnById('labels')).get('bug')).toBe(1)
+  })
+
+  it('appends an undeclared value found in the data', () => {
+    const extra: Task[] = [
+      { id: 'x', priority: 'urgent', labels: [], points: null },
+    ]
+    const counts = facetedCounts(extra, columnById('priority'))
+    expect([...counts.keys()]).toEqual(['low', 'medium', 'high', 'urgent'])
+    expect(counts.get('urgent')).toBe(1)
+  })
+
+  it('throws for a column type with no facets', () => {
+    expect(() => facetedCounts(rows, columnById('points'))).toThrow(
+      /only defined for option and multiOption/,
+    )
+  })
+
+  // BUG 3
+  it('recomputes from the rows it is given, so counts cannot go stale', () => {
+    const priority = columnById('priority')
+    const before = facetedCounts(rows, priority)
+    expect(before.get('high')).toBe(2)
+
+    const narrowed = filterRows(rows, columns, [
+      { columnId: 'labels', type: 'multiOption', operator: 'include', values: ['ui'] },
+    ])
+    const after = facetedCounts(narrowed, priority)
+
+    expect(after.get('high')).toBe(1)
+    // And the first result was not mutated by the second call.
+    expect(before.get('high')).toBe(2)
+  })
+})
+
+describe('facetedRowsFor', () => {
+  const state: FiltersState = [
+    { columnId: 'priority', type: 'option', operator: 'is', values: ['high'] },
+    { columnId: 'labels', type: 'multiOption', operator: 'include', values: ['ui'] },
+  ]
+
+  it('excludes the column its own facet list is for', () => {
+    // Without this, picking "high" would zero every other priority bucket and
+    // the list could never be widened.
+    const forPriority = facetedRowsFor(rows, columns, state, 'priority')
+    expect(forPriority.map((t) => t.id)).toEqual(['b', 'd'])
+    const counts = facetedCounts(forPriority, columnById('priority'))
+    expect(counts.get('high')).toBe(1)
+    expect(counts.get('low')).toBe(0)
+  })
+
+  it('still applies every other column filter', () => {
+    const forLabels = facetedRowsFor(rows, columns, state, 'labels')
+    expect(forLabels.map((t) => t.id)).toEqual(['a', 'b'])
+  })
+})
+
+describe('facetedMinMax', () => {
+  it('reports the observed range', () => {
+    expect(facetedMinMax(rows, columnById('points'))).toEqual([3, 8])
+  })
+
+  it('returns null when no row has a value', () => {
+    expect(facetedMinMax([], columnById('points'))).toBeNull()
+  })
+
+  it('prefers declared bounds over observed ones', () => {
+    const bounded = defineColumns<Task>([
+      {
+        id: 'points',
+        type: 'number',
+        displayName: 'Points',
+        accessor: (t) => t.points,
+        min: 0,
+        max: 100,
+      },
+    ])
+    const column = bounded[0]
+    if (!column) throw new Error('fixture missing')
+    expect(facetedMinMax(rows, column)).toEqual([0, 100])
+  })
+
+  it('throws for a non-number column', () => {
+    expect(() => facetedMinMax(rows, columnById('priority'))).toThrow(
+      /only defined for number columns/,
+    )
+  })
+})