@kernhq/module-quire 0.8.0 → 0.9.0

package/src/client/database/cells/PersonCell.svelte

@@ -0,0 +1,116 @@
+<script lang="ts">
+import { Avatar, DropdownMenu, type MenuItem } from '@kernhq/ui'
+import type { PropertyConfig } from '../../../contract/index.js'
+import type { Person } from '../../core-api.js'
+import { t } from '../../i18n.js'
+
+/**
+ * One or more people, stored as user ids.
+ *
+ * The face comes before the name in the menu, because a person is recognised by their picture
+ * faster than by their name — which is what `MenuItem`'s `avatar` field is for.
+ */
+interface Props {
+  value: unknown
+  name: string
+  config: PropertyConfig
+  people: Person[]
+  editable: boolean
+  reason?: string
+  onchange: (value: unknown) => void
+}
+const { value, name, config, people, editable, reason, onchange }: Props = $props()
+
+const many = $derived(config.multiple !== false)
+const chosen = $derived(
+  value == null ? [] : (Array.isArray(value) ? value : [value]).map(String).filter((v) => v !== ''),
+)
+const personFor = (id: string) => people.find((p) => p.id === id) ?? null
+
+const commit = (next: string[]) => onchange(many ? next : (next[0] ?? null))
+const toggle = (id: string, on: boolean) => {
+  if (many) commit(on ? [...chosen.filter((v) => v !== id), id] : chosen.filter((v) => v !== id))
+  else commit(on ? [id] : [])
+}
+
+const items = $derived.by(() => {
+  const list: MenuItem[] = people.map((person) => ({
+    type: 'checkbox' as const,
+    id: person.id,
+    label: person.name,
+    avatar: { id: person.id, name: person.name, src: person.avatarUrl },
+    checked: chosen.includes(person.id),
+    onCheckedChange: (on: boolean) => toggle(person.id, on),
+  }))
+  if (list.length === 0) return [{ type: 'label' as const, label: t('db_people_none') }]
+  if (chosen.length > 0)
+    list.push(
+      { type: 'separator' },
+      { id: 'clear', label: t('db_select_clear'), icon: 'x', onSelect: () => commit([]) },
+    )
+  return list
+})
+</script>
+
+{#snippet faces()}
+  {#if chosen.length === 0}
+    <span class="muted">{t('db_cell_empty')}</span>
+  {:else}
+    {#each chosen as id (id)}
+      <span class="who">
+        <Avatar id={id} name={personFor(id)?.name ?? null} src={personFor(id)?.avatarUrl ?? null} size={20} />
+        <span class="nm">{personFor(id)?.name ?? id}</span>
+      </span>
+    {/each}
+  {/if}
+{/snippet}
+
+{#if editable}
+  <DropdownMenu {items} align="start">
+    {#snippet trigger(props: Record<string, unknown>)}
+      <button {...props} type="button" class="cell-trigger" aria-label={name}>{@render faces()}</button>
+    {/snippet}
+  </DropdownMenu>
+{:else}
+  <span class="cell-trigger static" title={reason}>{@render faces()}</span>
+{/if}
+
+<style>
+.cell-trigger {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  max-width: 100%;
+  min-height: 26px;
+  padding: 2px 6px;
+  margin-inline-start: -6px;
+  border: 0;
+  border-radius: var(--kern-r-sm);
+  background: none;
+  color: inherit;
+  font: inherit;
+  font-size: 13px;
+  text-align: start;
+  overflow: hidden;
+}
+button.cell-trigger:hover {
+  background: var(--kern-surface-active);
+}
+.cell-trigger.static {
+  cursor: default;
+}
+.who {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  min-width: 0;
+}
+.nm {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.muted {
+  color: var(--kern-ink-450);
+}
+</style>

package/src/client/database/cells/RelationCell.svelte

@@ -0,0 +1,222 @@
+<script lang="ts">
+import { Icon, IconButton, Popover, SearchBox, Spinner } from '@kernhq/ui'
+import { createQuery } from '@tanstack/svelte-query'
+import type { PropertyConfig, RowRef } from '../../../contract/index.js'
+import { getQuireApi } from '../../api-instance.js'
+import { t } from '../../i18n.js'
+import { quireKeys } from '../../query.js'
+
+/**
+ * Rows linked from another database.
+ *
+ * A relation stores page ids and nothing else, so both jobs this cell has — drawing the links it
+ * already holds and finding the next one — are `databases.lookup` calls against the database on the
+ * other side. Without the first, the column is a list of uuids.
+ *
+ * The write goes through `updateRow`'s props like every other cell; the server splits relation keys
+ * out and routes them to `setRelation`, so the join table and the mirror in `props` cannot diverge
+ * whichever surface did the editing.
+ */
+interface Props {
+  value: unknown
+  name: string
+  config: PropertyConfig
+  workspaceId: string
+  editable: boolean
+  reason?: string
+  onchange: (value: unknown) => void
+}
+const { value, name, config, workspaceId, editable, reason, onchange }: Props = $props()
+
+const api = getQuireApi()
+
+const ids = $derived(
+  value == null ? [] : (Array.isArray(value) ? value : [value]).map(String).filter((v) => v !== ''),
+)
+const targetId = $derived(config.relationDatabaseId ?? null)
+
+let open = $state(false)
+let term = $state('')
+
+/** The names of what is already linked. Keyed by the ids so it re-resolves when they change. */
+const linked = createQuery(() => ({
+  queryKey: [...quireKeys.lookup(workspaceId, targetId ?? '', 'ids'), ids.join(',')],
+  enabled: Boolean(workspaceId && targetId) && ids.length > 0,
+  queryFn: () => api.databases.lookup({ workspaceId, databaseId: targetId!, ids, query: '', limit: 100 }),
+}))
+
+const search = createQuery(() => ({
+  queryKey: quireKeys.lookup(workspaceId, targetId ?? '', term),
+  enabled: Boolean(workspaceId && targetId) && open,
+  queryFn: () =>
+    api.databases.lookup({ workspaceId, databaseId: targetId!, query: term, ids: [], limit: 25 }),
+}))
+
+/** An id whose row has been deleted still has to draw as something. */
+const chips = $derived<RowRef[]>(
+  ids.map((id) => (linked.data ?? []).find((r) => r.id === id) ?? { id, title: t('untitled'), icon: null }),
+)
+
+const results = $derived((search.data ?? []).filter((r) => !ids.includes(r.id)))
+
+const link = (id: string) => {
+  onchange([...ids, id])
+  term = ''
+}
+const unlink = (id: string) => onchange(ids.filter((v) => v !== id))
+</script>
+
+<span class="rel">
+  {#each chips as chip (chip.id)}
+    <span class="chip">
+      <span class="nm">{chip.title.trim() || t('untitled')}</span>
+      {#if editable}
+        <button
+          type="button"
+          class="x"
+          aria-label={t('db_relation_unlink', { title: chip.title.trim() || t('untitled') })}
+          onclick={() => unlink(chip.id)}
+        >
+          <Icon name="x" size={11} strokeWidth={2} />
+        </button>
+      {/if}
+    </span>
+  {/each}
+
+  {#if ids.length === 0 && !editable}
+    <span class="muted" title={reason}>{t('db_cell_empty')}</span>
+  {/if}
+
+  {#if editable}
+    {#if !targetId}
+      <!-- Not disabled-with-no-reason: the column has nothing on the other side to link to yet. -->
+      <span class="muted" title={t('db_relation_untargeted')}>{t('db_relation_untargeted')}</span>
+    {:else}
+      <Popover bind:open align="start" width="300px" onOpenChange={(o) => !o && (term = '')}>
+        {#snippet trigger(props: Record<string, unknown>)}
+          <button {...props} type="button" class="add" aria-label={t('db_relation_link')}>
+            <Icon name="plus" size={13} strokeWidth={1.9} />
+          </button>
+        {/snippet}
+        <div class="picker">
+          <SearchBox
+            bind:value={term}
+            placeholder={t('db_relation_search')}
+            label={t('db_relation_search')}
+            height={32}
+          />
+          {#if search.isLoading}
+            <div class="state"><Spinner size={16} /></div>
+          {:else if search.isError}
+            <p class="state">{t('common.error')}</p>
+          {:else if results.length === 0}
+            <p class="state">{t('db_relation_none')}</p>
+          {:else}
+            <ul class="results">
+              {#each results as row (row.id)}
+                <li>
+                  <button type="button" class="result" onclick={() => link(row.id)}>
+                    <Icon name="file-text" size={13} strokeWidth={1.7} />
+                    <span class="nm">{row.title.trim() || t('untitled')}</span>
+                  </button>
+                </li>
+              {/each}
+            </ul>
+          {/if}
+        </div>
+      </Popover>
+    {/if}
+  {/if}
+</span>
+
+<style>
+.rel {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  min-width: 0;
+  overflow: hidden;
+}
+.chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 2px;
+  max-width: 160px;
+  padding-inline: 7px 2px;
+  padding-block: 2px;
+  border-radius: var(--kern-r-md);
+  background: var(--kern-surface-chip);
+  color: var(--kern-ink-550);
+  font-size: 12px;
+}
+.nm {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.x,
+.add {
+  flex: none;
+  display: inline-grid;
+  place-items: center;
+  width: 24px;
+  height: 24px;
+  border: 0;
+  border-radius: var(--kern-r-sm);
+  background: none;
+  color: var(--kern-ink-450);
+}
+.x:hover,
+.add:hover {
+  background: var(--kern-surface-active);
+  color: var(--kern-ink-900);
+}
+.picker {
+  padding: 10px;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.results {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+  max-height: 240px;
+  overflow-y: auto;
+}
+.result {
+  display: flex;
+  align-items: center;
+  gap: 7px;
+  width: 100%;
+  min-height: 30px;
+  padding: 4px 8px;
+  border: 0;
+  border-radius: var(--kern-r-md);
+  background: none;
+  color: var(--kern-ink-700);
+  font: inherit;
+  font-size: 13px;
+  text-align: start;
+}
+.result:hover {
+  background: var(--kern-surface-popover-hover);
+}
+.state {
+  margin: 0;
+  padding: 12px 4px;
+  text-align: center;
+  font-size: 12.5px;
+  color: var(--kern-ink-450);
+}
+.muted {
+  color: var(--kern-ink-450);
+  font-size: 13px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+</style>

package/src/client/database/cells/SelectCell.svelte

@@ -0,0 +1,133 @@
+<script lang="ts">
+import { DropdownMenu, type MenuItem } from '@kernhq/ui'
+import type { PropertyConfig, PropertyType } from '../../../contract/index.js'
+import { t } from '../../i18n.js'
+import OptionChip from '../OptionChip.svelte'
+import { STATUS_GROUPS } from '../view-config.js'
+
+/**
+ * select, multi_select and status.
+ *
+ * A menu rather than an inline list, because the table cell clips (`.ktd` is `overflow: hidden`)
+ * and `DropdownMenu` portals out of it. A status groups its options into the workflow bands it
+ * declares, so "Done" is not sitting between "Blocked" and "Doing" in alphabetical order.
+ */
+interface Props {
+  value: unknown
+  name: string
+  type: PropertyType
+  config: PropertyConfig
+  editable: boolean
+  reason?: string
+  onchange: (value: unknown) => void
+}
+const { value, name, type, config, editable, reason, onchange }: Props = $props()
+
+const many = $derived(type === 'multi_select')
+const options = $derived(config.options ?? [])
+
+const chosen = $derived.by(() => {
+  if (value == null) return [] as string[]
+  return (Array.isArray(value) ? value : [value]).map(String).filter((v) => v !== '')
+})
+const optionFor = (id: string) => options.find((o) => o.id === id) ?? null
+
+const commit = (next: string[]) => onchange(many ? next : (next[0] ?? null))
+
+const toggle = (id: string, on: boolean) => {
+  if (many) commit(on ? [...chosen.filter((v) => v !== id), id] : chosen.filter((v) => v !== id))
+  else commit(on ? [id] : [])
+}
+
+/** Status options in band order; everything else in the order the column declares them. */
+const ordered = $derived.by(() => {
+  if (type !== 'status') return options.map((option) => ({ option, band: null as string | null }))
+  const out: { option: (typeof options)[number]; band: string | null }[] = []
+  for (const band of STATUS_GROUPS)
+    for (const option of options.filter((o) => o.group === band)) out.push({ option, band })
+  for (const option of options.filter((o) => !o.group || !STATUS_GROUPS.includes(o.group)))
+    out.push({ option, band: null })
+  return out
+})
+
+const items = $derived.by(() => {
+  const list: MenuItem[] = []
+  let band: string | null | undefined
+  for (const entry of ordered) {
+    if (type === 'status' && entry.band && entry.band !== band) {
+      list.push({ type: 'label', label: t(`db_status_${entry.band}`) })
+      band = entry.band
+    }
+    list.push({
+      type: 'checkbox',
+      id: entry.option.id,
+      label: entry.option.label,
+      checked: chosen.includes(entry.option.id),
+      onCheckedChange: (on: boolean) => toggle(entry.option.id, on),
+    })
+  }
+  if (list.length === 0) list.push({ type: 'label', label: t('db_options_none') })
+  else if (chosen.length > 0)
+    list.push(
+      { type: 'separator' },
+      { id: 'clear', label: t('db_select_clear'), icon: 'x', onSelect: () => commit([]) },
+    )
+  return list
+})
+</script>
+
+{#if editable}
+  <DropdownMenu items={items} align="start">
+    {#snippet trigger(props: Record<string, unknown>)}
+      <button {...props} type="button" class="cell-trigger" aria-label={name}>
+        {#if chosen.length === 0}
+          <span class="muted">{t('db_cell_empty')}</span>
+        {:else}
+          {#each chosen as id (id)}
+            <OptionChip option={optionFor(id)} label={optionFor(id) ? undefined : id} compact />
+          {/each}
+        {/if}
+      </button>
+    {/snippet}
+  </DropdownMenu>
+{:else}
+  <span class="cell-trigger static" title={reason}>
+    {#if chosen.length === 0}
+      <span class="muted">{t('db_cell_empty')}</span>
+    {:else}
+      {#each chosen as id (id)}
+        <OptionChip option={optionFor(id)} label={optionFor(id) ? undefined : id} compact />
+      {/each}
+    {/if}
+  </span>
+{/if}
+
+<style>
+.cell-trigger {
+  display: inline-flex;
+  align-items: center;
+  flex-wrap: nowrap;
+  gap: 4px;
+  max-width: 100%;
+  min-height: 26px;
+  padding: 2px 6px;
+  margin-inline-start: -6px;
+  border: 0;
+  border-radius: var(--kern-r-sm);
+  background: none;
+  color: inherit;
+  font: inherit;
+  font-size: 13px;
+  text-align: start;
+  overflow: hidden;
+}
+button.cell-trigger:hover {
+  background: var(--kern-surface-active);
+}
+.cell-trigger.static {
+  cursor: default;
+}
+.muted {
+  color: var(--kern-ink-450);
+}
+</style>

package/src/client/database/cells/TextCell.svelte

@@ -0,0 +1,85 @@
+<script lang="ts">
+import { t } from '../../i18n.js'
+
+/**
+ * A bare input that only looks like a control while somebody is in it (DESIGN.md §3.13).
+ *
+ * Committed on blur and on Enter, never per keystroke: each edit is its own mutation, and a request
+ * per character is both slow and impossible to reason about when one of them fails.
+ */
+interface Props {
+  value: unknown
+  name: string
+  editable: boolean
+  reason?: string
+  onchange: (value: unknown) => void
+}
+const { value, name, editable, reason, onchange }: Props = $props()
+
+const text = $derived(value == null ? '' : String(value))
+
+/** An empty field is a cleared cell, and `null` is how the API says that. */
+const commit = (next: string) => {
+  if (next === text) return
+  onchange(next === '' ? null : next)
+}
+</script>
+
+{#if editable}
+  <input
+    class="cell-input"
+    value={text}
+    aria-label={name}
+    placeholder={t('db_cell_empty')}
+    onblur={(e) => commit(e.currentTarget.value)}
+    onkeydown={(e) => {
+      if (e.key === 'Enter') e.currentTarget.blur()
+      if (e.key === 'Escape') {
+        e.currentTarget.value = text
+        e.currentTarget.blur()
+      }
+    }}
+  />
+{:else}
+  <span class="cell-static" title={reason}>
+    {#if text}{text}{:else}<span class="muted">{t('db_cell_empty')}</span>{/if}
+  </span>
+{/if}
+
+<style>
+.cell-input {
+  width: 100%;
+  min-width: 0;
+  min-height: 26px;
+  padding: 2px 6px;
+  margin-inline-start: -6px;
+  border: 1px solid transparent;
+  border-radius: var(--kern-r-sm);
+  background: none;
+  color: inherit;
+  font: inherit;
+  font-size: 13px;
+}
+.cell-input:hover {
+  background: var(--kern-surface-active);
+}
+.cell-input:focus {
+  border-color: var(--kern-border);
+  background: var(--kern-surface-raised);
+  outline: none;
+}
+.cell-input::placeholder {
+  color: var(--kern-ink-350);
+}
+.cell-static {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  cursor: default;
+  font-size: 13px;
+}
+.muted {
+  color: var(--kern-ink-450);
+}
+</style>

package/src/client/database/colours.ts

@@ -0,0 +1,27 @@
+/**
+ * The colours a select option may wear.
+ *
+ * Closed on purpose. `SelectOption.colour` is free text in the contract, so painting it directly
+ * means one typo renders a chip with no background — and, worse, a colour pair nobody has measured.
+ * Every pair here is one the design tokens already tuned for contrast in light and dark; an unknown
+ * name falls back to grey rather than to nothing.
+ */
+export interface Tone {
+  bg: string
+  fg: string
+}
+
+export const TONES: Record<string, Tone> = {
+  grey: { bg: 'var(--kern-surface-chip)', fg: 'var(--kern-ink-550)' },
+  slate: { bg: 'var(--kern-slate-tint)', fg: 'var(--kern-slate)' },
+  accent: { bg: 'var(--kern-accent-tint)', fg: 'var(--kern-accent-deep)' },
+  success: { bg: 'var(--kern-success-tint)', fg: 'var(--kern-success-chip)' },
+  warning: { bg: 'var(--kern-warning-tint)', fg: 'var(--kern-warning)' },
+  danger: { bg: 'var(--kern-danger-tint)', fg: 'var(--kern-danger)' },
+  info: { bg: 'var(--kern-info-tint)', fg: 'var(--kern-info)' },
+  purple: { bg: 'var(--kern-purple-tint)', fg: 'var(--kern-purple)' },
+}
+
+export const OPTION_COLOURS = Object.keys(TONES)
+
+export const toneFor = (colour: string | undefined | null): Tone => TONES[colour ?? 'grey'] ?? TONES.grey!

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

@@ -0,0 +1,64 @@
+/**
+ * The property-type table is what every branch in the database interface reads instead of
+ * re-switching on the type. These assertions are about the two ways it can be wrong and nothing
+ * will say so: a type with no entry (which draws nothing), and an operator offered for a column
+ * that cannot answer it (which silently matches no rows).
+ */
+import { describe, expect, it } from 'vitest'
+import { PropertyType } from '../../contract/index.js'
+import {
+  CREATABLE_TYPES,
+  descriptorFor,
+  isReadOnly,
+  operatorsFor,
+  PROPERTY_TYPES,
+  VIEW_KINDS,
+} from './property-types.js'
+
+describe('the property type table', () => {
+  it('describes every type the contract declares', () => {
+    for (const type of PropertyType.options) {
+      const descriptor = descriptorFor(type)
+      expect(descriptor, `${type} has no descriptor, so its column draws nothing`).toBeDefined()
+      expect(descriptor.icon.length, `${type} icon`).toBeGreaterThan(0)
+    }
+    expect(Object.keys(PROPERTY_TYPES).sort()).toEqual([...PropertyType.options].sort())
+  })
+
+  it('marks exactly the server-written types read-only', () => {
+    const readOnly = PropertyType.options.filter((t) => isReadOnly(t)).sort()
+    expect(readOnly).toEqual(
+      ['created_by', 'created_time', 'edited_by', 'edited_time', 'files', 'formula', 'rollup'].sort(),
+    )
+  })
+
+  it('offers a checkbox equality and not a substring', () => {
+    expect(operatorsFor('checkbox')).toContain('equals')
+    expect(operatorsFor('checkbox')).not.toContain('contains')
+  })
+
+  it('offers a multi-select membership and not a prefix', () => {
+    expect(operatorsFor('multi_select')).toContain('is_any_of')
+    expect(operatorsFor('multi_select')).not.toContain('starts_with')
+  })
+
+  it('never offers an operator with no value editor for a type that needs one', () => {
+    for (const type of PropertyType.options)
+      expect(operatorsFor(type).length, `${type} can be filtered by nothing at all`).toBeGreaterThan(0)
+  })
+
+  it('keeps files out of the picker, because nothing can fill one', () => {
+    expect(CREATABLE_TYPES).not.toContain('files')
+    expect(CREATABLE_TYPES).toContain('text')
+  })
+
+  it('only groups a board by a column whose values are a closed set', () => {
+    const groupable = PropertyType.options.filter((t) => descriptorFor(t).canGroup).sort()
+    expect(groupable).toEqual(['checkbox', 'select', 'status'])
+  })
+
+  it('leaves timeline out of the kinds it offers, because none of it is built', () => {
+    expect(VIEW_KINDS.map((v) => v.kind)).not.toContain('timeline')
+    expect(VIEW_KINDS.map((v) => v.kind)).toEqual(['table', 'board', 'gallery', 'list', 'calendar'])
+  })
+})