@lovett/ui 0.0.11 → 0.1.0

package/src/filter-core/types.ts

@@ -0,0 +1,247 @@
+/**
+ * @package @lovett/ui
+ * @file filter-core/types.ts
+ *
+ * The type layer for the board filter model.
+ *
+ * Ported (not copied) from bazza/ui's `data-table-filter` core, as vendored
+ * in continuity-control. Everything React, i18n and domain-specific has been
+ * stripped: this file is pure TypeScript and imports nothing.
+ *
+ * The one idea worth keeping verbatim is the TYPE GATING on `ColumnConfig`:
+ * `options` exists only on option-ish columns, `min`/`max` only on number
+ * columns, expressed as conditional types resolving to `never`. An illegal
+ * config does not compile — the config is the schema.
+ *
+ * Deliberate divergences from the source:
+ *   - `FilterModel` defaults to a DISCRIMINATED UNION over `type` rather than
+ *     `any`, so the combinator can switch exhaustively and a missed case is a
+ *     compile error (source used `TType extends ColumnDataType = any`).
+ *   - `multiOption` filter values are a FLAT `string[]`. The source's types say
+ *     flat while its predicate reads `values[0]` as an array — the two never
+ *     agreed. Flat is the honest shape.
+ *   - `ColumnOption.icon` is a string (a Lucide icon NAME), not a React
+ *     element. Icon resolution is the UI layer's job; this layer stays pure.
+ */
+
+/** `T`, or absent. Accessors are allowed to return nothing for a row. */
+export type Nullable<T> = T | null | undefined
+
+/** The element type of an array; `T` itself when `T` is not an array. */
+export type ElementType<T> = T extends readonly (infer U)[] ? U : T
+
+/**
+ * Every column data type we handle, as a runtime list AND a union.
+ *
+ * The runtime list is load-bearing: `defineColumns` validates a declared
+ * `type` against it and THROWS on anything else. The source's combinator
+ * instead fell through to a silent `return true` for text/number/date, which
+ * meant adding a date column quietly disabled filtering on it.
+ */
+export const COLUMN_DATA_TYPES = [
+  'text',
+  'number',
+  'date',
+  'option',
+  'multiOption',
+] as const
+
+export type ColumnDataType = (typeof COLUMN_DATA_TYPES)[number]
+
+/** The two types that draw their values from a fixed option list. */
+export type OptionBasedColumnDataType = Extract<
+  ColumnDataType,
+  'option' | 'multiOption'
+>
+
+/** Maps a column data type to the native value a row carries for it. */
+export type ColumnDataNativeMap = {
+  text: string
+  number: number
+  date: Date
+  option: string
+  multiOption: readonly string[]
+}
+
+/** What a column accessor is allowed to return, per type. Absent is legal. */
+export type ColumnValueMap = {
+  [K in ColumnDataType]: Nullable<ColumnDataNativeMap[K]>
+}
+
+/**
+ * The values carried by a filter, per column type. ALWAYS an array, even for
+ * single-value operators — one shape to serialise, one shape to validate.
+ */
+export type FilterValues<T extends ColumnDataType> = Array<
+  ElementType<ColumnDataNativeMap[T]>
+>
+
+/** A selectable value on an `option` / `multiOption` column. */
+export interface ColumnOption {
+  /** Stable id. This is what lands in `FilterModel.values` and in the URL. */
+  readonly value: string
+  /** Human label. */
+  readonly label: string
+  /**
+   * OPTIONAL Lucide icon name (e.g. `'CircleCheck'`), resolved by the UI
+   * layer. A string, never a component — this module must stay React-free.
+   */
+  readonly icon?: string
+}
+
+/** Reads the filterable value for one column out of one row. */
+export type ColumnAccessor<TData, TType extends ColumnDataType> = (
+  row: TData,
+) => ColumnValueMap[TType]
+
+/**
+ * The configuration for one filterable column.
+ *
+ * Type gating (the reason this is a conditional type and not a flat object):
+ *
+ *   defineColumns<Task>([
+ *     { id: 'title', type: 'text', accessor: r => r.title, displayName: 'Title',
+ *       min: 3 },            // <- compile error: min is `never` on text
+ *     { id: 'priority', type: 'option', accessor: r => r.priority,
+ *       displayName: 'Priority', options: [...] },   // <- fine
+ *   ])
+ */
+export type ColumnConfig<
+  TData,
+  TType extends ColumnDataType = ColumnDataType,
+> = {
+  /** Stable id. Matches `FilterModel.columnId` and is what the URL carries. */
+  readonly id: string
+  readonly accessor: ColumnAccessor<TData, TType>
+  readonly displayName: string
+  readonly type: TType
+  /** Option list. Only legal on `option` / `multiOption`. */
+  readonly options?: TType extends OptionBasedColumnDataType
+    ? readonly ColumnOption[]
+    : never
+  /** Declared lower bound. Only legal on `number`. */
+  readonly min?: TType extends 'number' ? number : never
+  /** Declared upper bound. Only legal on `number`. */
+  readonly max?: TType extends 'number' ? number : never
+}
+
+/**
+ * A column config of any type, as a discriminated union over `type`.
+ *
+ * This is what collections are typed as. It is NOT `ColumnConfig<TData>` with
+ * the default union parameter: the conditional gates distribute there and
+ * would re-admit `options` on a text column.
+ */
+export type AnyColumnConfig<TData> = {
+  [K in ColumnDataType]: ColumnConfig<TData, K>
+}[ColumnDataType]
+
+/* ------------------------------------------------------------------ */
+/* Operators                                                           */
+/* ------------------------------------------------------------------ */
+
+export type TextFilterOperator = 'contains' | 'does not contain'
+
+export type NumberFilterOperator =
+  | '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'
+
+export type DateFilterOperator =
+  | 'is'
+  | 'is not'
+  | 'is before'
+  | 'is on or after'
+  | 'is after'
+  | 'is on or before'
+  | 'is between'
+  | 'is not between'
+
+export type OptionFilterOperator = 'is' | 'is not' | 'is any of' | 'is none of'
+
+export type MultiOptionFilterOperator =
+  | 'include'
+  | 'exclude'
+  | 'include any of'
+  | 'include all of'
+  | 'exclude if any of'
+  | 'exclude if all'
+
+/** Maps a column data type to its operator union. */
+export type FilterOperators = {
+  text: TextFilterOperator
+  number: NumberFilterOperator
+  date: DateFilterOperator
+  option: OptionFilterOperator
+  multiOption: MultiOptionFilterOperator
+}
+
+/** How many values an operator applies to, as a coarse UI hint. */
+export type FilterOperatorTarget = 'single' | 'multiple'
+
+/**
+ * How many values an operator REQUIRES. This is the declarative replacement
+ * for the source's `operator in ['is between', 'is not between']` guard —
+ * `in` on an array tests indices, so that guard never fired (filter-fns.ts:80).
+ * An arity that lives in the operator table cannot be written that way.
+ */
+export type FilterOperatorArity = 'one' | 'two' | 'many'
+
+/** Metadata for one operator of one column type. */
+export type FilterOperatorDetails<
+  TOperator,
+  TType extends ColumnDataType,
+> = {
+  /** The operator itself. Also its display string — there is no i18n here. */
+  readonly value: TOperator
+  readonly target: FilterOperatorTarget
+  readonly arity: FilterOperatorArity
+  /** This operator is the SINGULAR of X: promote to X past one value. */
+  readonly singularOf?: FilterOperators[TType]
+  /** This operator is the PLURAL of Y: demote to Y at one value or fewer. */
+  readonly pluralOf?: FilterOperators[TType]
+  readonly isNegated: boolean
+  /** For a positive operator, its negated twin. */
+  readonly negation?: FilterOperators[TType]
+  /** For a negated operator, its positive twin. */
+  readonly negationOf?: FilterOperators[TType]
+}
+
+/** Every operator of one column type, keyed by operator. */
+export type FilterDetails<T extends ColumnDataType> = {
+  [K in FilterOperators[T]]: FilterOperatorDetails<K, T>
+}
+
+/** Every operator of every column type. */
+export type FilterTypeOperatorDetails = {
+  [K in ColumnDataType]: FilterDetails<K>
+}
+
+/* ------------------------------------------------------------------ */
+/* Filter state                                                        */
+/* ------------------------------------------------------------------ */
+
+/**
+ * One column's filter.
+ *
+ * With no type argument this distributes into a discriminated union over
+ * `type`, which is what makes the combinator exhaustively checkable.
+ * `FilterModel<'date'>` picks out the single date member.
+ */
+export type FilterModel<TType extends ColumnDataType = ColumnDataType> =
+  TType extends ColumnDataType
+    ? {
+        readonly columnId: string
+        readonly type: TType
+        readonly operator: FilterOperators[TType]
+        readonly values: FilterValues<TType>
+      }
+    : never
+
+/** The whole filter state. At most one entry per column. */
+export type FiltersState = FilterModel[]

package/src/filter-core/url.ts

@@ -0,0 +1,261 @@
+/**
+ * @package @lovett/ui
+ * @file filter-core/url.ts
+ *
+ * Filter state <-> URL search param.
+ *
+ * Filters belong in the URL: a compound filtered board is then a shareable
+ * link, and back/forward work. The consumer wires this to React Router's
+ * `useSearchParams`; this module knows nothing about React or the router.
+ *
+ * PARSING IS DEFENSIVE, NOT TRUSTING. A query string is untrusted input that
+ * a user can hand-edit and a third party can hand someone in a link, so
+ * `parseFilters` VALIDATES every entry and DROPS the ones that do not hold
+ * up, rather than throwing and taking the board down with them. CLAUDE.md:
+ * parse once at the boundary, constrain lengths and ranges as well as shapes,
+ * and pass validated types inward.
+ *
+ * NOTE ON ZOD. The brief called for zod, and zod is a workspace dependency —
+ * but it is NOT a dependency of `@lovett/ui`, and adding one to the design
+ * system is an ADR-level decision (CLAUDE.md §1) plus an edit to
+ * package.json, which is outside this change's scope. The validation below is
+ * hand-written to the same standard: every field checked, every bound
+ * enforced, nothing inferred from the input's own shape. It is deliberately
+ * structured as one `parseEntry` funnel so swapping in a zod schema later is
+ * a local change.
+ *
+ * WHAT IS ENFORCED
+ *   - the payload is JSON, is an array, and is under a size cap
+ *   - `columnId` is a non-empty, bounded string and not a prototype key
+ *   - `type` is one of the five declared column data types
+ *   - `operator` is a member of THAT type's operator table
+ *   - `values` is a real array, bounded in length, with every element valid
+ *     for the type (bounded string / finite number / parseable date)
+ *   - the value COUNT satisfies the operator's arity, so nothing that
+ *     survives parsing can later make a predicate throw
+ *   - at most one filter per column, first occurrence wins
+ */
+
+import { operatorValueArity, isOperatorOf } from './operators'
+import { COLUMN_DATA_TYPES } from './types'
+import type { ColumnDataType, FilterModel, FiltersState } from './types'
+
+/** The conventional search-param name. Callers may use another. */
+export const FILTERS_SEARCH_PARAM = 'filters'
+
+/** Bounds. Generous for real use, small enough that a hostile link is inert. */
+const MAX_RAW_LENGTH = 8192
+const MAX_FILTERS = 32
+const MAX_VALUES_PER_FILTER = 64
+const MAX_STRING_LENGTH = 256
+const MAX_COLUMN_ID_LENGTH = 128
+
+/** Keys that must never be accepted as a column id. */
+const FORBIDDEN_COLUMN_IDS: ReadonlySet<string> = new Set([
+  '__proto__',
+  'constructor',
+  'prototype',
+])
+
+/* ------------------------------------------------------------------ */
+/* Serialise                                                           */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Encode a filter state for a search param.
+ *
+ * An empty state serialises to the EMPTY STRING, which is the caller's cue to
+ * delete the param rather than write `?filters=[]`. Dates go out as ISO
+ * strings; everything else is already JSON-native.
+ */
+export function serializeFilters(state: FiltersState): string {
+  if (state.length === 0) return ''
+
+  const wire = state.map((filter) => ({
+    columnId: filter.columnId,
+    type: filter.type,
+    operator: filter.operator,
+    values:
+      filter.type === 'date'
+        ? filter.values.map((value) => value.toISOString())
+        : filter.values,
+  }))
+
+  return JSON.stringify(wire)
+}
+
+/* ------------------------------------------------------------------ */
+/* Parse                                                               */
+/* ------------------------------------------------------------------ */
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    !Array.isArray(value) &&
+    !(value instanceof Date)
+  )
+}
+
+/** Own-property read. An inherited or prototype-shaped key reads as absent. */
+function ownProp(record: Record<string, unknown>, key: string): unknown {
+  return Object.hasOwn(record, key) ? record[key] : undefined
+}
+
+function asColumnId(value: unknown): string | null {
+  if (typeof value !== 'string') return null
+  if (value === '' || value.length > MAX_COLUMN_ID_LENGTH) return null
+  if (FORBIDDEN_COLUMN_IDS.has(value)) return null
+  return value
+}
+
+function asColumnDataType(value: unknown): ColumnDataType | null {
+  if (typeof value !== 'string') return null
+  for (const type of COLUMN_DATA_TYPES) if (type === value) return type
+  return null
+}
+
+function asRawValues(value: unknown): unknown[] | null {
+  if (!Array.isArray(value)) return null
+  if (value.length > MAX_VALUES_PER_FILTER) return null
+  return value
+}
+
+function asStrings(raw: readonly unknown[]): string[] | null {
+  const out: string[] = []
+  for (const item of raw) {
+    if (typeof item !== 'string') return null
+    if (item.length > MAX_STRING_LENGTH) return null
+    out.push(item)
+  }
+  return out
+}
+
+function asNumbers(raw: readonly unknown[]): number[] | null {
+  const out: number[] = []
+  for (const item of raw) {
+    if (typeof item !== 'number' || !Number.isFinite(item)) return null
+    out.push(item)
+  }
+  return out
+}
+
+function asDates(raw: readonly unknown[]): Date[] | null {
+  const out: Date[] = []
+  for (const item of raw) {
+    if (item instanceof Date) {
+      if (Number.isNaN(item.getTime())) return null
+      out.push(new Date(item.getTime()))
+      continue
+    }
+    if (typeof item !== 'string' || item.length > MAX_STRING_LENGTH) return null
+    const parsed = new Date(item)
+    if (Number.isNaN(parsed.getTime())) return null
+    out.push(parsed)
+  }
+  return out
+}
+
+function arityHolds(
+  type: ColumnDataType,
+  operator: string,
+  count: number,
+): boolean {
+  if (!isOperatorOf(type, operator)) return false
+  const [min, max] = operatorValueArity(type, operator)
+  return count >= min && count <= max
+}
+
+/**
+ * Validate one wire entry into a `FilterModel`, or `null` if it does not hold
+ * up. Every branch builds a FRESH object literal from validated primitives —
+ * the parsed input is never spread, so a `__proto__`-shaped key cannot ride
+ * along into the model.
+ */
+function parseEntry(raw: unknown): FilterModel | null {
+  if (!isPlainRecord(raw)) return null
+
+  const columnId = asColumnId(ownProp(raw, 'columnId'))
+  if (columnId === null) return null
+
+  const type = asColumnDataType(ownProp(raw, 'type'))
+  if (type === null) return null
+
+  const operator = ownProp(raw, 'operator')
+  if (typeof operator !== 'string') return null
+
+  const rawValues = asRawValues(ownProp(raw, 'values'))
+  if (rawValues === null) return null
+
+  if (!arityHolds(type, operator, rawValues.length)) return null
+
+  switch (type) {
+    case 'text': {
+      const values = asStrings(rawValues)
+      if (!values || !isOperatorOf('text', operator)) return null
+      return { columnId, type: 'text', operator, values }
+    }
+    case 'number': {
+      const values = asNumbers(rawValues)
+      if (!values || !isOperatorOf('number', operator)) return null
+      return { columnId, type: 'number', operator, values }
+    }
+    case 'date': {
+      const values = asDates(rawValues)
+      if (!values || !isOperatorOf('date', operator)) return null
+      return { columnId, type: 'date', operator, values }
+    }
+    case 'option': {
+      const values = asStrings(rawValues)
+      if (!values || !isOperatorOf('option', operator)) return null
+      return { columnId, type: 'option', operator, values }
+    }
+    case 'multiOption': {
+      const values = asStrings(rawValues)
+      if (!values || !isOperatorOf('multiOption', operator)) return null
+      return { columnId, type: 'multiOption', operator, values }
+    }
+  }
+}
+
+/**
+ * Decode a filter state from a search param.
+ *
+ * Accepts the raw param string (what `URLSearchParams.get` returns, including
+ * `null`) or an already-parsed value. NEVER THROWS: a malformed payload, a
+ * malformed entry, an unknown operator, a wrong-shaped value list or a
+ * value count the operator cannot use all resolve to that entry being
+ * dropped. A caller that wants to know it happened compares lengths, or
+ * re-serialises the result and rewrites the param.
+ */
+export function parseFilters(raw: unknown): FiltersState {
+  let source: unknown = raw
+
+  if (source === null || source === undefined) return []
+
+  if (typeof source === 'string') {
+    const trimmed = source.trim()
+    if (trimmed === '' || trimmed.length > MAX_RAW_LENGTH) return []
+    try {
+      source = JSON.parse(trimmed)
+    } catch {
+      return []
+    }
+  }
+
+  if (!Array.isArray(source)) return []
+
+  const state: FiltersState = []
+  const seen = new Set<string>()
+
+  for (const entry of source) {
+    if (state.length >= MAX_FILTERS) break
+    const filter = parseEntry(entry)
+    if (!filter) continue
+    if (seen.has(filter.columnId)) continue
+    seen.add(filter.columnId)
+    state.push(filter)
+  }
+
+  return state
+}

package/src/filter-dropdown.tsx

@@ -51,6 +51,12 @@ export interface FilterDropdownProps<T extends string = string> {
   neutralValue?: T
   /** Defaults to the option label. */
   triggerValueLabel?: string
+  /**
+   * Optional adornment at the leading edge of the trigger — a funnel, a
+   * category glyph. It inherits the trigger's colour, so it flips with the
+   * active state like the rest of the chip and never needs its own variant.
+   */
+  icon?: ReactNode
   className?: string
   align?: 'left' | 'right'
 }
@@ -62,6 +68,7 @@ export function FilterDropdown<T extends string = string>({
   options,
   neutralValue = 'all' as T,
   triggerValueLabel,
+  icon,
   className,
   align = 'left',
 }: FilterDropdownProps<T>) {
@@ -173,6 +180,11 @@ export function FilterDropdown<T extends string = string>({
           borderRadius: 999,
         }}
       >
+        {icon ? (
+          <span className="shrink-0 inline-flex items-center" aria-hidden="true">
+            {icon}
+          </span>
+        ) : null}
         <span
           className="font-semibold"
           style={{