@kernhq/module-quire 0.8.0 → 0.9.0

package/src/client/database/property-types.ts

@@ -0,0 +1,294 @@
+import type { FilterOperator, PropertyType, ViewKind } from '../../contract/index.js'
+
+/**
+ * What every property type is, in one table.
+ *
+ * The interface asks the same four questions of a column over and over — which icon, which editor,
+ * may it be written, which operators may a filter offer — and answering each of them with its own
+ * `switch` is how a new property type ends up drawing nothing in one place and everything in
+ * another. One record, exhaustively typed: adding a type to the contract stops compiling here until
+ * it is described, which is the point.
+ *
+ * Icons are chosen from `@kernhq/ui`'s registry as it actually stands. An unregistered name renders
+ * a blank square and throws nothing, and there is no `table`, `sigma` or `arrow-down` in it.
+ */
+
+/** The family of editor a cell uses. `unsupported` renders read-only and says why. */
+export type CellEditor =
+  | 'text'
+  | 'number'
+  | 'select'
+  | 'date'
+  | 'person'
+  | 'checkbox'
+  | 'link'
+  | 'relation'
+  | 'computed'
+  | 'unsupported'
+
+export interface PropertyDescriptor {
+  icon: string
+  editor: CellEditor
+  /** written by the server, never by a person — a formula, a rollup, or an audit stamp */
+  readOnly: boolean
+  operators: FilterOperator[]
+  /** may a board be grouped by it */
+  canGroup: boolean
+  /** may a calendar be plotted on it */
+  canDate: boolean
+  /** may somebody choose it when adding a column */
+  creatable: boolean
+}
+
+const TEXTUAL: FilterOperator[] = [
+  'equals',
+  'not_equals',
+  'contains',
+  'not_contains',
+  'starts_with',
+  'ends_with',
+  'is_empty',
+  'is_not_empty',
+]
+const NUMERIC: FilterOperator[] = [
+  'equals',
+  'not_equals',
+  'greater_than',
+  'less_than',
+  'is_empty',
+  'is_not_empty',
+]
+const DATED: FilterOperator[] = [
+  'equals',
+  'on_or_before',
+  'on_or_after',
+  'greater_than',
+  'less_than',
+  'is_empty',
+  'is_not_empty',
+]
+const CHOSEN: FilterOperator[] = [
+  'equals',
+  'not_equals',
+  'is_any_of',
+  'is_none_of',
+  'is_empty',
+  'is_not_empty',
+]
+const MANY: FilterOperator[] = [
+  'contains',
+  'not_contains',
+  'is_any_of',
+  'is_none_of',
+  'is_empty',
+  'is_not_empty',
+]
+
+export const PROPERTY_TYPES: Record<PropertyType, PropertyDescriptor> = {
+  text: {
+    icon: 'file-text',
+    editor: 'text',
+    readOnly: false,
+    operators: TEXTUAL,
+    canGroup: false,
+    canDate: false,
+    creatable: true,
+  },
+  number: {
+    icon: 'hash',
+    editor: 'number',
+    readOnly: false,
+    operators: NUMERIC,
+    canGroup: false,
+    canDate: false,
+    creatable: true,
+  },
+  select: {
+    icon: 'chevron-down',
+    editor: 'select',
+    readOnly: false,
+    operators: CHOSEN,
+    canGroup: true,
+    canDate: false,
+    creatable: true,
+  },
+  multi_select: {
+    icon: 'tag',
+    editor: 'select',
+    readOnly: false,
+    operators: MANY,
+    canGroup: false,
+    canDate: false,
+    creatable: true,
+  },
+  status: {
+    icon: 'circle-check',
+    editor: 'select',
+    readOnly: false,
+    operators: CHOSEN,
+    canGroup: true,
+    canDate: false,
+    creatable: true,
+  },
+  date: {
+    icon: 'calendar',
+    editor: 'date',
+    readOnly: false,
+    operators: DATED,
+    canGroup: false,
+    canDate: true,
+    creatable: true,
+  },
+  person: {
+    icon: 'user',
+    editor: 'person',
+    readOnly: false,
+    operators: MANY,
+    canGroup: false,
+    canDate: false,
+    creatable: true,
+  },
+  /**
+   * Quire has no file handling at all — no upload path, no storage ticket — so a `files` column is
+   * drawn read-only and is not offered when adding one. A picker that produces a column nobody can
+   * fill is worse than an absent type.
+   */
+  files: {
+    icon: 'paperclip',
+    editor: 'unsupported',
+    readOnly: true,
+    operators: ['is_empty', 'is_not_empty'],
+    canGroup: false,
+    canDate: false,
+    creatable: false,
+  },
+  checkbox: {
+    icon: 'square-check-big',
+    editor: 'checkbox',
+    readOnly: false,
+    operators: ['equals', 'is_empty', 'is_not_empty'],
+    canGroup: true,
+    canDate: false,
+    creatable: true,
+  },
+  url: {
+    icon: 'link',
+    editor: 'link',
+    readOnly: false,
+    operators: TEXTUAL,
+    canGroup: false,
+    canDate: false,
+    creatable: true,
+  },
+  email: {
+    icon: 'at-sign',
+    editor: 'link',
+    readOnly: false,
+    operators: TEXTUAL,
+    canGroup: false,
+    canDate: false,
+    creatable: true,
+  },
+  phone: {
+    icon: 'smartphone',
+    editor: 'link',
+    readOnly: false,
+    operators: TEXTUAL,
+    canGroup: false,
+    canDate: false,
+    creatable: true,
+  },
+  relation: {
+    icon: 'git-branch',
+    editor: 'relation',
+    readOnly: false,
+    operators: MANY,
+    canGroup: false,
+    canDate: false,
+    creatable: true,
+  },
+  rollup: {
+    icon: 'chart-column',
+    editor: 'computed',
+    readOnly: true,
+    operators: NUMERIC,
+    canGroup: false,
+    canDate: false,
+    creatable: true,
+  },
+  formula: {
+    icon: 'code',
+    editor: 'computed',
+    readOnly: true,
+    operators: NUMERIC,
+    canGroup: false,
+    canDate: false,
+    creatable: true,
+  },
+  created_time: {
+    icon: 'clock',
+    editor: 'computed',
+    readOnly: true,
+    operators: DATED,
+    canGroup: false,
+    canDate: true,
+    creatable: true,
+  },
+  created_by: {
+    icon: 'circle-user',
+    editor: 'computed',
+    readOnly: true,
+    operators: CHOSEN,
+    canGroup: false,
+    canDate: false,
+    creatable: true,
+  },
+  edited_time: {
+    icon: 'clock',
+    editor: 'computed',
+    readOnly: true,
+    operators: DATED,
+    canGroup: false,
+    canDate: true,
+    creatable: true,
+  },
+  edited_by: {
+    icon: 'circle-user',
+    editor: 'computed',
+    readOnly: true,
+    operators: CHOSEN,
+    canGroup: false,
+    canDate: false,
+    creatable: true,
+  },
+}
+
+export const descriptorFor = (type: PropertyType): PropertyDescriptor => PROPERTY_TYPES[type]
+export const operatorsFor = (type: PropertyType): FilterOperator[] => PROPERTY_TYPES[type].operators
+export const isReadOnly = (type: PropertyType): boolean => PROPERTY_TYPES[type].readOnly
+
+/** The types somebody may choose when adding or retyping a column, in the order they are offered. */
+export const CREATABLE_TYPES: PropertyType[] = (Object.keys(PROPERTY_TYPES) as PropertyType[]).filter(
+  (type) => PROPERTY_TYPES[type].creatable,
+)
+
+/** Operators that take no value at all — the value editor is hidden rather than disabled. */
+export const VALUELESS_OPERATORS: FilterOperator[] = ['is_empty', 'is_not_empty']
+
+/**
+ * Timeline is declared by `ViewKind` and is not built.
+ *
+ * It needs a start and an end date per row, a scale and a horizontal virtualiser, and none of that
+ * exists — so it is left out of the kinds the interface offers rather than shipped as a tab that
+ * renders nothing. A view already saved as `timeline` falls back to the table.
+ */
+export const VIEW_KINDS: { kind: ViewKind; icon: string }[] = [
+  { kind: 'table', icon: 'columns-3' },
+  { kind: 'board', icon: 'kanban' },
+  { kind: 'gallery', icon: 'layout-grid' },
+  { kind: 'list', icon: 'list' },
+  { kind: 'calendar', icon: 'calendar-days' },
+]
+
+export const viewIcon = (kind: ViewKind): string =>
+  VIEW_KINDS.find((v) => v.kind === kind)?.icon ?? 'columns-3'

package/src/client/database/view-config.test.ts

@@ -0,0 +1,148 @@
+/**
+ * `updateView` replaces `config` wholesale, so every one of these assertions is about the same
+ * failure: a write that carried a fragment and silently deleted the rest of somebody's view.
+ */
+import { describe, expect, it } from 'vitest'
+import type { Database, Filter, Property, Row, Sort, ViewConfig } from '../../contract/index.js'
+import {
+  columnTemplate,
+  EMPTY_GROUP,
+  groupsOf,
+  groupValue,
+  mergeConfig,
+  visiblePropertiesOf,
+} from './view-config.js'
+
+const config = (over: Partial<ViewConfig> = {}): ViewConfig => ({
+  filters: [],
+  filterMode: 'and',
+  sorts: [],
+  groupBy: null,
+  dateProperty: null,
+  visibleProperties: null,
+  columnWidths: {},
+  cardSize: 'medium',
+  coverProperty: null,
+  ...over,
+})
+
+const property = (key: string, over: Partial<Property> = {}): Property =>
+  ({
+    id: `p-${key}`,
+    databaseId: 'db',
+    key,
+    name: key,
+    type: 'text',
+    config: {},
+    position: key,
+    hidden: false,
+    ...over,
+  }) as Property
+
+const row = (id: string, props: Record<string, unknown>): Row =>
+  ({
+    id,
+    databaseId: 'db',
+    title: id,
+    icon: null,
+    props,
+    computed: {},
+    createdBy: null,
+    updatedBy: null,
+    createdAt: '',
+    updatedAt: '',
+  }) as Row
+
+describe('mergeConfig', () => {
+  it('keeps everything the patch does not mention', () => {
+    const filter: Filter = { propertyKey: 'status', operator: 'equals', value: 'done' }
+    const merged = mergeConfig(config({ filters: [filter], groupBy: 'status', cardSize: 'large' }), {
+      sorts: [],
+    })
+    expect(merged.filters, 'a partial write deleted the filters — the whole point of this helper').toEqual([
+      filter,
+    ])
+    expect(merged.groupBy).toBe('status')
+    expect(merged.cardSize).toBe('large')
+  })
+
+  it('lets a patch clear a nullable field rather than treating null as absent', () => {
+    const merged = mergeConfig(config({ groupBy: 'status', coverProperty: 'cover' }), { groupBy: null })
+    expect(merged.groupBy).toBeNull()
+    expect(merged.coverProperty, 'only groupBy was cleared').toBe('cover')
+  })
+
+  it('replaces a list wholesale, because that is what removing a sort means', () => {
+    const sort: Sort = { propertyKey: 'n', direction: 'asc' }
+    expect(mergeConfig(config({ sorts: [sort] }), { sorts: [] }).sorts).toEqual([])
+  })
+})
+
+describe('visiblePropertiesOf', () => {
+  const database = {
+    properties: [
+      property('b', { position: 'b' }),
+      property('a', { position: 'a' }),
+      property('c', { position: 'c', hidden: true }),
+    ],
+  } as Database
+
+  it('means every non-hidden column, in position order, when nobody has chosen', () => {
+    const view = { config: config() } as never
+    expect(visiblePropertiesOf(database, view).map((p) => p.key)).toEqual(['a', 'b'])
+  })
+
+  it('draws nothing but what was chosen once somebody has', () => {
+    const view = { config: config({ visibleProperties: ['b'] }) } as never
+    expect(visiblePropertiesOf(database, view).map((p) => p.key)).toEqual(['b'])
+  })
+
+  it('falls back to every column when there is no view yet', () => {
+    expect(visiblePropertiesOf(database, null).map((p) => p.key)).toEqual(['a', 'b'])
+  })
+})
+
+describe('columnTemplate', () => {
+  it('gives the title the flexible track and every other column its stored width', () => {
+    expect(columnTemplate([property('a'), property('b')], { a: 260 })).toBe(
+      'minmax(240px, 1fr) 260px 180px 84px',
+    )
+  })
+
+  it('refuses a width nobody could read', () => {
+    expect(columnTemplate([property('a')], { a: 4 })).toContain('90px')
+  })
+})
+
+describe('groupsOf', () => {
+  const status = property('status', {
+    type: 'status',
+    config: {
+      options: [
+        { id: 'todo', label: 'To do', colour: 'slate' },
+        { id: 'doing', label: 'Doing', colour: 'accent' },
+      ],
+    },
+  })
+
+  it('keeps the option lanes in declaration order and puts the uncategorised one last', () => {
+    const lanes = groupsOf(status, [row('r1', { status: 'doing' }), row('r2', {})])
+    expect(lanes.map((l) => l.id)).toEqual(['todo', 'doing', EMPTY_GROUP])
+    expect(lanes[1]?.rows.map((r) => r.id)).toEqual(['r1'])
+  })
+
+  it('puts a row with no value in the uncategorised lane rather than dropping it', () => {
+    const lanes = groupsOf(status, [row('r2', { status: null }), row('r3', {})])
+    expect(lanes.at(-1)?.rows.map((r) => r.id)).toEqual(['r2', 'r3'])
+  })
+
+  it('puts a row whose value names no option in the uncategorised lane, never nowhere', () => {
+    const lanes = groupsOf(status, [row('r4', { status: 'deleted-option' })])
+    expect(lanes.at(-1)?.rows.map((r) => r.id)).toEqual(['r4'])
+  })
+
+  it('reads the uncategorised lane as clearing the value', () => {
+    expect(groupValue(EMPTY_GROUP)).toBeNull()
+    expect(groupValue('doing')).toBe('doing')
+  })
+})

package/src/client/database/view-config.ts

@@ -0,0 +1,102 @@
+import type { Database, Property, Row, SelectOption, View, ViewConfig } from '../../contract/index.js'
+
+/**
+ * Reading and writing a view's configuration.
+ *
+ * **`updateView` replaces `config` wholesale.** It is one jsonb column and the service writes what
+ * it is given, so sending `{ sorts: [...] }` destroys the filters, the grouping, the column widths
+ * and the visible properties in the same request. Every write goes through `mergeConfig`, which is
+ * the only reason this module exists.
+ */
+
+/** The complete configuration, with the patch applied. Never send a partial one. */
+export function mergeConfig(current: ViewConfig, patch: Partial<ViewConfig>): ViewConfig {
+  return {
+    filters: patch.filters ?? current.filters,
+    filterMode: patch.filterMode ?? current.filterMode,
+    sorts: patch.sorts ?? current.sorts,
+    groupBy: patch.groupBy !== undefined ? patch.groupBy : current.groupBy,
+    dateProperty: patch.dateProperty !== undefined ? patch.dateProperty : current.dateProperty,
+    visibleProperties:
+      patch.visibleProperties !== undefined ? patch.visibleProperties : current.visibleProperties,
+    columnWidths: patch.columnWidths ?? current.columnWidths,
+    cardSize: patch.cardSize ?? current.cardSize,
+    coverProperty: patch.coverProperty !== undefined ? patch.coverProperty : current.coverProperty,
+  }
+}
+
+/**
+ * The columns a view draws, in position order.
+ *
+ * `visibleProperties: null` means "every column that is not hidden" rather than "none" — a view
+ * created before anybody chose has no list, and reading null as an empty list draws a table with no
+ * columns at all.
+ */
+export function visiblePropertiesOf(database: Database, view: View | null): Property[] {
+  const ordered = [...database.properties].sort((a, b) => (a.position < b.position ? -1 : 1))
+  const chosen = view?.config.visibleProperties ?? null
+  if (!chosen) return ordered.filter((p) => !p.hidden)
+  return ordered.filter((p) => chosen.includes(p.key))
+}
+
+/** Every column, hidden ones included, in position order — what the properties editor lists. */
+export const orderedProperties = (database: Database): Property[] =>
+  [...database.properties].sort((a, b) => (a.position < b.position ? -1 : 1))
+
+export const DEFAULT_COLUMN_WIDTH = 180
+export const MIN_COLUMN_WIDTH = 90
+export const MAX_COLUMN_WIDTH = 640
+/** The title column absorbs the extra width — DESIGN.md §2.7: a working view fills. */
+export const TITLE_COLUMN = 'minmax(240px, 1fr)'
+/** Room for the row's hover actions, which sit outside the last cell. */
+export const ACTIONS_COLUMN = '84px'
+
+/** The grid template for a table: title, then each visible column at its stored or default width. */
+export function columnTemplate(properties: Property[], widths: Record<string, number>): string {
+  const cols = properties.map((p) => `${clampWidth(widths[p.key] ?? DEFAULT_COLUMN_WIDTH)}px`)
+  return [TITLE_COLUMN, ...cols, ACTIONS_COLUMN].join(' ')
+}
+
+export const clampWidth = (px: number): number =>
+  Math.min(MAX_COLUMN_WIDTH, Math.max(MIN_COLUMN_WIDTH, Math.round(px)))
+
+/** The minimum width the table needs before it starts scrolling inside its own wrapper. */
+export function tableMinWidth(properties: Property[], widths: Record<string, number>): number {
+  const cols = properties.reduce((total, p) => total + clampWidth(widths[p.key] ?? DEFAULT_COLUMN_WIDTH), 0)
+  return 240 + cols + 84 + (properties.length + 2) * 12
+}
+
+/** The lane a row with no value falls into. Not a valid option id — options are at least one char. */
+export const EMPTY_GROUP = '__none__'
+
+export interface Lane {
+  id: string
+  option: SelectOption | null
+  rows: Row[]
+}
+
+/**
+ * The lanes of a board, in the order the column's options are declared.
+ *
+ * The uncategorised lane is last and always present: a board that hides it hides the rows nobody
+ * has triaged yet, which are the ones the board exists to surface.
+ */
+export function groupsOf(property: Property | null, rows: Row[]): Lane[] {
+  const options = property?.config.options ?? []
+  const lanes: Lane[] = options.map((option) => ({ id: option.id, option, rows: [] }))
+  const none: Lane = { id: EMPTY_GROUP, option: null, rows: [] }
+
+  for (const row of rows) {
+    const raw = property ? row.props[property.key] : null
+    const value = Array.isArray(raw) ? raw[0] : raw
+    const lane = value == null ? undefined : lanes.find((l) => l.id === String(value))
+    ;(lane ?? none).rows.push(row)
+  }
+  return [...lanes, none]
+}
+
+/** The value to write when a card is dropped in a lane; the uncategorised lane means "no value". */
+export const groupValue = (laneId: string): string | null => (laneId === EMPTY_GROUP ? null : laneId)
+
+/** The status bands, in workflow order, so a status menu is grouped rather than alphabetical. */
+export const STATUS_GROUPS = ['todo', 'doing', 'done'] as const

package/src/client/formula.test.ts

@@ -0,0 +1,139 @@
+/**
+ * The formula language.
+ *
+ * The first test is the one that matters: a formula is text a workspace member types and the server
+ * evaluates. If it ever reaches `eval` or `new Function`, everything else here is irrelevant.
+ */
+import { describe, expect, it } from 'vitest'
+import { evaluateFormula, type FormulaValue, formulaDependencies, parseFormula } from './formula.js'
+
+const run = (src: string, props: Record<string, FormulaValue> = {}) =>
+  evaluateFormula(parseFormula(src), { prop: (n) => props[n] ?? null })
+
+describe('what a formula cannot do', () => {
+  it('refuses anything that is not in the function table', () => {
+    for (const attack of [
+      'constructor("return 1")()',
+      'process.exit(1)',
+      'require("fs")',
+      'globalThis',
+      'eval("1")',
+    ]) {
+      expect(() => parseFormula(attack), attack).toThrow()
+    }
+  })
+
+  it('refuses a formula that nests beyond the limit rather than blowing the stack', () => {
+    const deep = `${'abs('.repeat(200)}1${')'.repeat(200)}`
+    expect(() => run(deep)).toThrow(/nests too deeply/i)
+  })
+
+  it('refuses an unterminated string and a stray character', () => {
+    expect(() => parseFormula('concat("oops')).toThrow()
+    expect(() => parseFormula('1 § 2')).toThrow()
+  })
+})
+
+describe('arithmetic and precedence', () => {
+  it('binds multiplication tighter than addition', () => {
+    expect(run('1 + 2 * 3')).toBe(7)
+    expect(run('(1 + 2) * 3')).toBe(9)
+  })
+
+  it('treats ^ as right-associative', () => {
+    expect(run('2 ^ 3 ^ 2')).toBe(512)
+  })
+
+  it('gives a blank rather than Infinity when dividing by nothing', () => {
+    expect(run('1 / 0')).toBeNull()
+    expect(run('1 % 0')).toBeNull()
+  })
+
+  it('negates', () => {
+    expect(run('-3 + 1')).toBe(-2)
+  })
+})
+
+describe('text and numbers together', () => {
+  it('concatenates when either side is text, and adds when neither is', () => {
+    expect(run('"a" + 1')).toBe('a1')
+    expect(run('1 + 1')).toBe(2)
+  })
+
+  it('reads a property by the name somebody typed', () => {
+    expect(run('prop("Estimate") * 2', { Estimate: 4 })).toBe(8)
+    expect(run('prop("Nothing") + 1')).toBe(1)
+  })
+})
+
+describe('logic', () => {
+  it('short-circuits, so the right side of a false && is never evaluated', () => {
+    let touched = false
+    const ast = parseFormula('false && prop("x")')
+    evaluateFormula(ast, {
+      prop: () => {
+        touched = true
+        return 1
+      },
+    })
+    expect(touched).toBe(false)
+  })
+
+  it('chooses with if()', () => {
+    expect(run('if(prop("Done"), "yes", "no")', { Done: true })).toBe('yes')
+    expect(run('if(prop("Done"), "yes", "no")', { Done: false })).toBe('no')
+  })
+
+  it('treats = and == the same, because both are what people type', () => {
+    expect(run('1 = 1')).toBe(true)
+    expect(run('1 == 1')).toBe(true)
+  })
+})
+
+describe('functions', () => {
+  it('does text', () => {
+    expect(run('upper(concat("ab", "c"))')).toBe('ABC')
+    expect(run('length("hello")')).toBe(5)
+    expect(run('replace("a-b", "-", "+")')).toBe('a+b')
+  })
+
+  it('does numbers', () => {
+    expect(run('round(3.14159, 2)')).toBe(3.14)
+    expect(run('max(1, 9, 3)')).toBe(9)
+    expect(run('sum(1, 2, 3)')).toBe(6)
+  })
+
+  it('counts days between two dates', () => {
+    expect(run('dateBetween("2026-01-01", "2026-01-11")')).toBe(10)
+  })
+
+  it('finds a function whatever case it was typed in', () => {
+    // Names are camelCase for readability but a person typing one should not have to remember
+    // that. Lowercasing at the lookup rather than at the key is what keeps them reachable.
+    expect(run('datebetween("2026-01-01", "2026-01-03")')).toBe(2)
+    expect(run('DATEBETWEEN("2026-01-01", "2026-01-03")')).toBe(2)
+    expect(run('toNumber("42") + 1')).toBe(43)
+    expect(run('isEmpty(prop("nothing"))')).toBe(true)
+  })
+})
+
+describe('the AST is data, not a promise', () => {
+  it('does not make an if node thenable', async () => {
+    // An object with a `then` property is thenable: `await` calls it as a promise. This node's
+    // `then` would have been an AST node rather than a function, so returning one from an async
+    // function would silently resolve to the wrong value — with no error where the mistake is.
+    const ast = parseFormula('if(true, 1, 2)')
+    expect(Object.hasOwn(ast, 'then'), 'an if node must never carry a `then`').toBe(false)
+
+    const wrapped = await (async () => ast)()
+    expect(wrapped, 'awaiting the node changed it into something else').toEqual(ast)
+    expect(await Promise.resolve(ast)).toEqual(ast)
+  })
+})
+
+describe('dependencies', () => {
+  it('reports every property a formula reads, so a change recomputes only what depends on it', () => {
+    const ast = parseFormula('if(prop("A") > 1, prop("B"), prop("C") + prop("A"))')
+    expect([...formulaDependencies(ast)].sort()).toEqual(['A', 'B', 'C'])
+  })
+})