@kernhq/module-tracker 0.10.1 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kernhq/module-tracker",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Kern tracker module: projects, work item types, custom fields, workflows, issues, KQL, cycles, views, reports, intake, time tracking (server + client skeleton)",
   "homepage": "https://kernaio.com",
   "license": "AGPL-3.0-only",
@@ -56,21 +56,34 @@
     "@orpc/contract": "^1.15.0",
     "@orpc/server": "^1.15.0",
     "drizzle-orm": "^0.45.0",
+    "svelte-dnd-action": "^0.9.0",
     "zod": "^4.1.0"
   },
   "devDependencies": {
     "@kernhq/tsconfig": "^0.1.0",
+    "@kernhq/ui": "^0.7.0",
+    "@tanstack/svelte-query": "^6.1.0",
     "@types/node": "^24.0.0",
     "@types/pg": "^8.15.0",
     "drizzle-kit": "^0.31.0",
     "pg": "^8.16.0",
+    "svelte": "^5.46.0",
+    "svelte-check": "^4.0.0",
     "typescript": "~5.9.3",
     "vitest": "^4.0.0"
   },
   "peerDependencies": {
-    "svelte": "^5.0.0"
+    "@kernhq/ui": "^0.7.0",
+    "@tanstack/svelte-query": "^6.1.0",
+    "svelte": "^5.46.0"
   },
   "peerDependenciesMeta": {
+    "@kernhq/ui": {
+      "optional": true
+    },
+    "@tanstack/svelte-query": {
+      "optional": true
+    },
     "svelte": {
       "optional": true
     }
@@ -78,7 +91,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "dev": "tsc -p tsconfig.json --watch --preserveWatchOutput",
-    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.client.json --noEmit",
+    "typecheck": "tsc -p tsconfig.json --noEmit && svelte-check --tsconfig ./tsconfig.client.json --threshold error",
     "lint": "biome check .",
     "test": "vitest run",
     "test:unit": "vitest run --exclude 'src/**/*.int.test.ts'",

package/src/client/api-instance.ts

@@ -0,0 +1,34 @@
+import { getHost } from '@kernhq/ui'
+import { createTrackerClient, type TrackerApi } from './api.js'
+import { createMockTrackerApi } from './mock.js'
+
+/**
+ * The tracker API client.
+ *
+ * A module is reached at `/api/<module>`, so every module gets its own client built from its own
+ * contract; this is the tracker's, alongside `getApi()` for core. `PUBLIC_API_MOCK=1` swaps in the
+ * in-memory implementation from `./mock`, which satisfies the same contract types, so no view has a
+ * second code path for demos and end-to-end tests.
+ */
+export type { TrackerApi }
+
+let cached: TrackerApi | null = null
+
+export function getTrackerApi(): TrackerApi {
+  if (cached) return cached
+  cached = getHost().isMock ? (createMockTrackerApi() as unknown as TrackerApi) : createReal()
+  return cached
+}
+
+function createReal(): TrackerApi {
+  return createTrackerClient({
+    // empty base URL keeps requests same-origin: the dev server proxies /api, and in production the
+    // reverse proxy routes it, so the session cookie works without CORS in both
+    baseUrl: getHost().apiBaseUrl,
+  })
+}
+
+/** Test seam: lets tests install a fake without touching module state elsewhere. */
+export function __setTrackerApi(api: TrackerApi | null) {
+  cached = api
+}

package/src/client/components/BoardCard.svelte

@@ -0,0 +1,182 @@
+<script lang="ts">
+import { Avatar, Icon, realtime } from '@kernhq/ui'
+import { getTrackerCatalogue } from '../context.svelte.js'
+import { t } from '../i18n.js'
+import { formatDuration, type Issue } from '../index.js'
+import { estimateLabel, priorityLabel } from '../labels.js'
+import DueDate from './DueDate.svelte'
+import PriorityGlyph from './PriorityGlyph.svelte'
+import StatusIcon from './StatusIcon.svelte'
+
+/**
+ * A board card (DESIGN.md 3.3): status and key on top with the assignee on the far side, the title,
+ * a row of chips for the properties worth seeing without opening anything, and a footer of numbers.
+ * The comment count disappears when there are no comments rather than showing a zero.
+ */
+interface Props {
+  issue: Issue
+  onopen: (issue: Issue) => void
+}
+let { issue, onopen }: Props = $props()
+
+const cat = getTrackerCatalogue()
+const project = $derived(cat.project(issue.projectId))
+const status = $derived(cat.status(issue.statusId))
+const milestone = $derived(cat.milestone(issue.milestoneId))
+const assignee = $derived(cat.person(issue.assigneeIds[0]))
+const online = $derived(assignee ? realtime.online.has(assignee.id) : false)
+</script>
+
+<article class="kcard" data-testid="board-card" data-issue-key={issue.key}>
+  <button type="button" class="body" onclick={() => onopen(issue)}>
+    <span class="top">
+      <StatusIcon
+        category={issue.statusCategory}
+        statusId={issue.statusId}
+        name={status?.name}
+        size={15}
+        label={status?.name}
+      />
+      <span class="key">{issue.key}</span>
+      <span class="sp"></span>
+      {#if assignee}
+        <span class="dot" class:on={online}></span>
+        <Avatar name={assignee.name} src={assignee.avatarUrl} id={assignee.id} size={22} />
+      {/if}
+    </span>
+
+    <span class="title">{issue.title}</span>
+
+    <span class="chips">
+      {#if issue.priority !== 'none'}
+        <span class="chip pri" title={priorityLabel(issue.priority)}>
+          <PriorityGlyph priority={issue.priority} size={14} />
+        </span>
+      {/if}
+      {#if project}
+        <span class="chip">
+          <Icon name="diamond" size={12} strokeWidth={1.7} />
+          <span class="chip-t">{project.name}</span>
+        </span>
+      {/if}
+      {#if milestone}
+        <span class="chip">
+          <Icon name="flag" size={12} strokeWidth={1.7} />
+          <span class="chip-t">{milestone.name}</span>
+        </span>
+      {/if}
+      {#if issue.dueDate}
+        <span class="chip"><DueDate date={issue.dueDate} /></span>
+      {/if}
+    </span>
+  </button>
+
+  <footer class="foot">
+    <span class="stat"><Icon name="clock" size={13} strokeWidth={1.6} />{formatDuration(issue.timeSpentSec)}</span>
+    {#if issue.estimate !== null}
+      <span class="stat">{estimateLabel(issue.estimate, issue.estimateUnit)}</span>
+    {/if}
+    <span class="sp"></span>
+    {#if issue.commentCount > 0}
+      <span class="stat">
+        <Icon name="message-circle" size={13} strokeWidth={1.6} />{issue.commentCount}
+      </span>
+    {/if}
+  </footer>
+</article>
+
+<style>
+  .kcard {
+    background: var(--kern-surface-raised);
+    border: 1px solid var(--kern-border);
+    border-radius: var(--kern-r-card);
+    overflow: hidden;
+    transition: border-color 80ms;
+  }
+  .kcard:hover {
+    border-color: var(--kern-border-hover);
+  }
+  .body {
+    display: block;
+    width: 100%;
+    padding: 13px 14px 14px;
+    text-align: start;
+  }
+  .top {
+    display: flex;
+    align-items: center;
+    gap: 7px;
+  }
+  .key {
+    font-family: var(--kern-font-mono);
+    font-size: 11.5px;
+    letter-spacing: -0.01em;
+    color: var(--kern-ink-250);
+  }
+  .sp {
+    flex: 1;
+  }
+  .dot {
+    width: 7px;
+    height: 7px;
+    border-radius: var(--kern-r-full);
+    background: var(--kern-success);
+    opacity: 0;
+    flex: none;
+  }
+  .dot.on {
+    opacity: 1;
+  }
+  .title {
+    display: block;
+    margin-top: 9px;
+    font-size: 14px;
+    line-height: 1.42;
+    letter-spacing: -0.005em;
+    color: var(--kern-ink-900);
+    text-wrap: pretty;
+  }
+  .chips {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 5px;
+    margin-top: 10px;
+  }
+  .chip {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    height: 26px;
+    padding: 0 8px;
+    border-radius: var(--kern-r-md);
+    background: var(--kern-surface-chip);
+    color: var(--kern-ink-580);
+    font-size: 12.5px;
+    white-space: nowrap;
+  }
+  .chip.pri {
+    padding: 0 7px;
+  }
+  .chip-t {
+    max-width: 120px;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+  .foot {
+    display: flex;
+    align-items: center;
+    gap: 14px;
+    height: 38px;
+    padding: 0 14px;
+    border-top: 1px solid var(--kern-surface-chip);
+    font-family: var(--kern-font-mono);
+    font-size: 11.5px;
+    letter-spacing: -0.01em;
+    color: var(--kern-ink-300);
+  }
+  .stat {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+  }
+</style>

package/src/client/components/BoardView.svelte

@@ -0,0 +1,248 @@
+<script lang="ts">
+import { Icon } from '@kernhq/ui'
+import { dndzone, SHADOW_ITEM_MARKER_PROPERTY_NAME } from 'svelte-dnd-action'
+import { t } from '../i18n.js'
+import { byRank, type Issue, type StatusInfo, statusStyle } from '../index.js'
+import BoardCard from './BoardCard.svelte'
+import StatusIcon from './StatusIcon.svelte'
+
+/**
+ * The board (DESIGN.md 3.3).
+ *
+ * One column per value of whatever the board is grouped by — a workflow status by default, or a
+ * custom field's options — each headed by a 2px rule that starts as a stub of the column's colour
+ * and fades to a hairline. Cards are dragged between columns with svelte-dnd-action; dropping one
+ * reports the column it landed in and the neighbours it landed between, so the page can apply
+ * whatever that column means and the new rank in one go.
+ *
+ * The board does not know what a column *is*: the page says how to read a card's column and what a
+ * drop means. That is what lets the same board group by status and by Severity without a second
+ * implementation.
+ *
+ * A WIP limit is shown as `used/limit` and turns red when a column is over it. It warns rather than
+ * refuses: a hard block just makes people rename columns.
+ */
+export interface BoardColumnInfo {
+  id: string
+  name: string
+  /** the colour of the header rule; a status derives one, a field option carries its own */
+  color: string
+  /** present only for a status column, which draws its glyph */
+  status?: StatusInfo
+}
+
+interface Props {
+  issues: Issue[]
+  columns: BoardColumnInfo[]
+  /** which column a card belongs in — the page decides, because it knows the grouping */
+  columnOf: (issue: Issue) => string[]
+  wipLimits?: Record<string, number | undefined>
+  /** false when the viewer may not move work between statuses; cards stay readable, just not draggable */
+  draggable?: boolean
+  onopen: (issue: Issue) => void
+  onmove: (issue: Issue, toColumnId: string, afterId: string | null, beforeId: string | null) => void
+  oncreate?: (columnId: string) => void
+}
+let {
+  issues,
+  columns,
+  columnOf,
+  wipLimits = {},
+  draggable = true,
+  onopen,
+  onmove,
+  oncreate,
+}: Props = $props()
+
+const FLIP = 160
+
+type Lane = { column: BoardColumnInfo; items: Issue[] }
+
+/**
+ * `$state.raw` matters here: the drag library tracks items by identity, and a deep-reactive proxy
+ * hands it a different object every read, which it reads as an endless stream of changes.
+ */
+let lanes = $state.raw<Lane[]>([])
+let dragging = $state(false)
+
+const replaceLane = (index: number, items: Issue[]) => {
+  lanes = lanes.map((lane, i) => (i === index ? { column: lane.column, items } : lane))
+}
+
+// mirror the query into local lists the drag library can reorder, but leave them alone mid-drag
+$effect(() => {
+  if (dragging) return
+  const sorted = [...issues].sort(byRank)
+  lanes = columns.map((column) => ({
+    column,
+    items: sorted.filter((issue) => columnOf(issue).includes(column.id)),
+  }))
+})
+
+const isShadow = (issue: Issue) =>
+  (issue as unknown as Record<string, unknown>)[SHADOW_ITEM_MARKER_PROPERTY_NAME] === true
+
+function consider(index: number, event: CustomEvent<{ items: Issue[] }>) {
+  dragging = true
+  replaceLane(index, event.detail.items)
+}
+
+function finalize(index: number, event: CustomEvent<{ items: Issue[]; info: { id: string } }>) {
+  dragging = false
+  const lane = lanes[index]
+  if (!lane) return
+  const items = event.detail.items
+  replaceLane(index, items)
+
+  const at = items.findIndex((i) => i.id === event.detail.info.id)
+  const moved = items[at]
+  // the drop reports on both the source and the target lane; only the target holds the card
+  if (!moved) return
+  onmove(moved, lane.column.id, items[at - 1]?.id ?? null, items[at + 1]?.id ?? null)
+}
+
+const laneRule = (column: BoardColumnInfo) =>
+  `linear-gradient(to var(--kern-lane-dir, right), ${column.color} 0 34px, var(--kern-border) 34px)`
+</script>
+
+<div class="kboard" data-testid="board">
+  {#each lanes as lane, index (lane.column.id)}
+    {@const limit = wipLimits[lane.column.id]}
+    {@const over = limit !== undefined && lane.items.length > limit}
+    <section class="col" data-column={lane.column.id}>
+      <header class="head">
+        {#if lane.column.status}
+          <StatusIcon
+            category={lane.column.status.category}
+            statusId={lane.column.status.id}
+            name={lane.column.status.name}
+            size={15}
+          />
+        {:else}
+          <!-- A field's value has no glyph of its own, so the column's colour is the whole cue. -->
+          <span class="swatch" style:background={lane.column.color}></span>
+        {/if}
+        <h2 class="name">{lane.column.name}</h2>
+        <span class="count" class:over title={over ? t('wip_exceeded') : undefined}>
+          {limit === undefined ? lane.items.length : `${lane.items.length}/${limit}`}
+        </span>
+        <span class="sp"></span>
+        {#if oncreate}
+          <button
+            type="button"
+            class="add"
+            aria-label={t('new_issue')}
+            onclick={() => oncreate(lane.column.id)}
+          >
+            <Icon name="plus" size={13} strokeWidth={1.9} />
+          </button>
+        {/if}
+      </header>
+      <div class="rule" style:background={laneRule(lane.column)}></div>
+
+      <!-- svelte-ignore a11y_no_static_element_interactions -->
+      <div
+        class="stack"
+        use:dndzone={{
+          items: lane.items,
+          flipDurationMs: FLIP,
+          type: 'tracker-issues',
+          dragDisabled: !draggable,
+          dropTargetStyle: {},
+        }}
+        onconsider={(e) => consider(index, e)}
+        onfinalize={(e) => finalize(index, e)}
+      >
+        {#each lane.items as issue (issue.id)}
+          <div class="slot" class:shadow={isShadow(issue)}>
+            <BoardCard {issue} {onopen} />
+          </div>
+        {/each}
+      </div>
+    </section>
+  {/each}
+</div>
+
+<style>
+  .kboard {
+    display: flex;
+    align-items: flex-start;
+    gap: 20px;
+    padding: 22px 28px 30px;
+    overflow: auto;
+    height: 100%;
+  }
+  :global([dir='rtl']) .kboard {
+    --kern-lane-dir: left;
+  }
+  .col {
+    width: var(--kern-board-col-w);
+    flex: none;
+  }
+  .head {
+    display: flex;
+    align-items: center;
+    gap: 9px;
+    height: 30px;
+  }
+  .name {
+    margin: 0;
+    font-size: 13.5px;
+    font-weight: 600;
+    letter-spacing: -0.01em;
+    color: var(--kern-ink-900);
+    white-space: nowrap;
+  }
+  .count {
+    font-family: var(--kern-font-mono);
+    font-size: 11.5px;
+    letter-spacing: -0.01em;
+    color: var(--kern-ink-250);
+  }
+  .count.over {
+    color: var(--kern-danger);
+    font-weight: 500;
+  }
+  .sp {
+    flex: 1;
+  }
+  .add {
+    width: 22px;
+    height: 22px;
+    border-radius: var(--kern-r-md);
+    display: grid;
+    place-items: center;
+    color: var(--kern-ink-250);
+  }
+  .add:hover {
+    background: var(--kern-surface-hover);
+    color: var(--kern-ink-900);
+  }
+  .swatch {
+    width: 9px;
+    height: 9px;
+    border-radius: 3px;
+    flex: none;
+  }
+  .rule {
+    height: 2px;
+    border-radius: 1px;
+  }
+  .stack {
+    display: flex;
+    flex-direction: column;
+    gap: 10px;
+    margin-top: 14px;
+    min-height: 80px;
+    padding-bottom: 4px;
+  }
+  .slot.shadow {
+    opacity: 0.35;
+  }
+  @media (max-width: 768px) {
+    .kboard {
+      padding: 16px;
+      gap: 14px;
+    }
+  }
+</style>