@kernhq/module-tracker 0.10.1 → 0.11.1

package/src/client/components/TrackerControls.svelte

@@ -0,0 +1,109 @@
+<script lang="ts">
+import { Button, DropdownMenu, IconButton, type MenuItem, navigation } from '@kernhq/ui'
+import { t } from '../i18n.js'
+import { canTracker } from '../permissions.js'
+
+/**
+ * The tracker's control strip.
+ *
+ * A module that owns the sidebar owns the row above it: the shell's ⌘K box steps aside so this can
+ * sit where a "New issue" button belongs, rather than being stacked under a second search field.
+ * Split out of `TrackerSidebar` so the shell can place the two independently.
+ */
+interface Props {
+  workspaceSlug: string
+}
+let { workspaceSlug }: Props = $props()
+
+const inTracker = $derived(navigation.pathname === `/${workspaceSlug}/tracker`)
+const canCreate = $derived(canTracker('create'))
+const canManageProjects = $derived(canTracker('projectManage'))
+
+/**
+ * Opening a dialog is a parameter on the page you are on, not a jump to a blank one: raising an
+ * issue from a filtered list keeps that list underneath.
+ */
+function ask(flag: string) {
+  /**
+   * Built from `navigation` rather than the router's URL object: a module cannot read `$app/state`,
+   * and it does not need an absolute URL to ask the shell to go somewhere.
+   */
+  const path = inTracker ? navigation.pathname : `/${workspaceSlug}/tracker`
+  const params = new URLSearchParams(inTracker ? navigation.search : {})
+  params.set(flag, '1')
+  void navigation.go(`${path}?${params.toString()}`, { keepFocus: true, noScroll: true })
+}
+
+const createMenu = $derived<MenuItem[]>([
+  ...(canCreate
+    ? [
+        {
+          type: 'item' as const,
+          id: 'issue',
+          label: t('new_issue'),
+          icon: 'square-check-big',
+          shortcut: ['c'],
+          onSelect: () => ask('new'),
+        },
+      ]
+    : []),
+  ...(canManageProjects
+    ? [
+        {
+          type: 'item' as const,
+          id: 'project',
+          label: t('project_new'),
+          icon: 'folder',
+          onSelect: () => ask('new_project'),
+        },
+        {
+          type: 'item' as const,
+          id: 'import',
+          label: t('settings_import'),
+          icon: 'upload',
+          href: `/${workspaceSlug}/settings/tracker/import`,
+        },
+      ]
+    : []),
+])
+</script>
+
+{#if canCreate || canManageProjects}
+  <div class="controls">
+    <Button
+      icon="plus"
+      rounded="xl"
+      class="cta"
+      onclick={() => ask(canCreate ? 'new' : 'new_project')}
+      data-testid="sidebar-new-issue"
+    >
+      {canCreate ? t('new_issue') : t('project_new')}
+    </Button>
+    {#if createMenu.length > 1}
+      <DropdownMenu items={createMenu} align="end">
+        {#snippet trigger(props)}
+          <IconButton
+            {...props}
+            icon="chevron-down"
+            label={t('create_more')}
+            size={34}
+            radius={9}
+            variant="outline"
+            data-testid="sidebar-create-menu"
+          />
+        {/snippet}
+      </DropdownMenu>
+    {/if}
+  </div>
+{/if}
+
+<style>
+  .controls {
+    display: flex;
+    gap: 6px;
+    align-items: center;
+  }
+  .controls :global(.cta) {
+    flex: 1;
+  }
+</style>

package/src/client/components/TrackerSidebar.svelte

@@ -0,0 +1,96 @@
+<script lang="ts">
+import { navigation, SidebarGroup, SidebarItem } from '@kernhq/ui'
+import { t } from '../i18n.js'
+import { isTrackerTarget, type TrackerTarget, trackerHref } from '../nav.js'
+import SidebarProjects from './SidebarProjects.svelte'
+import SidebarViews from './SidebarViews.svelte'
+
+/**
+ * The tracker, in the application sidebar (DESIGN.md 2.3).
+ *
+ * The rail switches modules and the sidebar holds the one you are in, so this is the tracker's own
+ * navigation: what you look at, the queries somebody named, and the projects with the ways each of
+ * them is planned. Every row is a link to a query the issues screen reads out of the URL — no row
+ * puts the page into a state that cannot be linked to, shared or gone back from.
+ *
+ * The control strip above it is `TrackerControls`, contributed separately so the shell can place
+ * the two independently.
+ */
+interface Props {
+  workspaceSlug: string
+}
+let { workspaceSlug }: Props = $props()
+
+const slug = $derived(workspaceSlug)
+const params = $derived(new URLSearchParams(navigation.search))
+const inTracker = $derived(navigation.pathname === `/${slug}/tracker`)
+
+/** Saving a view or making a project is a parameter on the page you are on, not a jump elsewhere. */
+function ask(flag: string) {
+  /**
+   * Built from `navigation` rather than the router's URL object: a module cannot read `$app/state`,
+   * and it does not need an absolute URL to ask the shell to go somewhere.
+   */
+  const path = inTracker ? navigation.pathname : `/${workspaceSlug}/tracker`
+  const params = new URLSearchParams(inTracker ? navigation.search : {})
+  params.set(flag, '1')
+  void navigation.go(`${path}?${params.toString()}`, { keepFocus: true, noScroll: true })
+}
+
+/** How the whole workspace's work is looked at, before any one project's. */
+const rows: { id: string; label: () => string; icon: string; target: TrackerTarget }[] = [
+  { id: 'mine', label: () => t('cmd_my_issues'), icon: 'circle-user', target: { preset: 'assigned' } },
+  { id: 'all', label: () => t('all_issues'), icon: 'square-check-big', target: {} },
+  {
+    id: 'projects',
+    label: () => t('all_projects'),
+    icon: 'layout-grid',
+    target: { group: 'project' },
+  },
+]
+</script>
+
+<div class="tsb">
+  <SidebarGroup title={t('title')}>
+    {#each rows as row (row.id)}
+      <SidebarItem
+        label={row.label()}
+        icon={row.icon}
+        href={trackerHref(slug, row.target)}
+        active={inTracker && isTrackerTarget(params, row.target)}
+        data-testid="tracker-nav-{row.id}"
+      />
+    {/each}
+    <SidebarItem
+      label={t('reports_title')}
+      icon="chart-line"
+      href="/{slug}/tracker/reports"
+      active={navigation.pathname === `/${slug}/tracker/reports`}
+    />
+  </SidebarGroup>
+
+  <SidebarViews onsave={() => ask('save')} />
+  <SidebarProjects oncreate={() => ask('new_project')} />
+</div>
+
+<style>
+.tsb {
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  min-height: 0;
+}
+/* DESIGN.md 2.3 control strip: the primary action takes the row, the menu takes what is left. */
+.controls {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 12px 12px 4px;
+  flex: none;
+}
+.controls :global(.cta) {
+  flex: 1;
+  min-width: 0;
+  height: 34px;
+}
+</style>

package/src/client/context.svelte.ts

@@ -0,0 +1,105 @@
+import { getContext, setContext } from 'svelte'
+import type {
+  Component,
+  Cycle,
+  FieldDef,
+  Label,
+  Milestone,
+  Project,
+  StatusInfo,
+  WorkItemType,
+} from './index.js'
+
+export interface Person {
+  id: string
+  name: string
+  avatarUrl: string | null
+}
+
+/**
+ * The reference data every tracker view needs to turn ids into something a person can read.
+ *
+ * Issues carry ids, not names: a row has a `projectId`, a `statusId` and `assigneeIds`. Rather than
+ * threading six lists through every component, the page loads them once and publishes them here, and
+ * the rows, cards and detail panel look up what they need. Kept in runes so a refetch (or a realtime
+ * change) redraws the views that read it.
+ */
+export class TrackerCatalogue {
+  projects = $state<Project[]>([])
+  statuses = $state<StatusInfo[]>([])
+  types = $state<WorkItemType[]>([])
+  labels = $state<Label[]>([])
+  cycles = $state<Cycle[]>([])
+  milestones = $state<Milestone[]>([])
+  components = $state<Component[]>([])
+  people = $state<Person[]>([])
+  /** The workspace's custom fields, so cards and group headings can read a value's label. */
+  fields = $state<FieldDef[]>([])
+
+  #projects = $derived(new Map(this.projects.map((p) => [p.id, p])))
+  #statuses = $derived(new Map(this.statuses.map((s) => [s.id, s])))
+  #types = $derived(new Map(this.types.map((t) => [t.id, t])))
+  #labels = $derived(new Map(this.labels.map((l) => [l.id, l])))
+  #cycles = $derived(new Map(this.cycles.map((c) => [c.id, c])))
+  #milestones = $derived(new Map(this.milestones.map((ms) => [ms.id, ms])))
+  #components = $derived(new Map(this.components.map((c) => [c.id, c])))
+  #people = $derived(new Map(this.people.map((p) => [p.id, p])))
+  #fields = $derived(new Map(this.fields.map((f) => [f.key, f])))
+
+  project = (id: string | null | undefined) => (id ? this.#projects.get(id) : undefined)
+  status = (id: string | null | undefined) => (id ? this.#statuses.get(id) : undefined)
+  type = (id: string | null | undefined) => (id ? this.#types.get(id) : undefined)
+  label = (id: string | null | undefined) => (id ? this.#labels.get(id) : undefined)
+  cycle = (id: string | null | undefined) => (id ? this.#cycles.get(id) : undefined)
+  milestone = (id: string | null | undefined) => (id ? this.#milestones.get(id) : undefined)
+  component = (id: string | null | undefined) => (id ? this.#components.get(id) : undefined)
+  person = (id: string | null | undefined) => (id ? this.#people.get(id) : undefined)
+  field = (key: string | null | undefined) => (key ? this.#fields.get(key) : undefined)
+
+  /**
+   * What a value of a custom field is called.
+   *
+   * A `select` stores an option id, so a group heading that showed the raw value would read
+   * `opt_7f3a` instead of `Sev 1`.
+   */
+  customValueLabel = (fieldKey: string, value: string): string => {
+    const field = this.#fields.get(fieldKey)
+    if (!field) return value
+    const option = field.options.find((o) => o.id === value)
+    if (option) return option.label
+    if (field.type === 'user' || field.type === 'multiuser') return this.person(value)?.name ?? value
+    return value
+  }
+
+  /**
+   * What a sum of estimates is said in.
+   *
+   * Per-issue the unit comes off the issue, but a group heading adds several up: they can only be
+   * added at all when the projects in view agree, and where they do not, points is what a mixed sum
+   * already meant.
+   */
+  estimateUnit = $derived.by<'points' | 'hours' | 'none'>(() => {
+    const units = new Set(this.projects.map((p) => p.settings.estimation))
+    const only = units.size === 1 ? [...units][0] : null
+    return only === 'hours' ? 'hours' : 'points'
+  })
+
+  /** The active cycle drives the sprint progress bar in the header. */
+  activeCycle = $derived(this.cycles.find((c) => c.status === 'active') ?? null)
+
+  /** Workflow order of a status, used to sort list groups and board columns. */
+  statusOrder = (id: string) => this.status(id)?.order ?? 99
+  statusCategory = (id: string) => this.status(id)?.category ?? 'todo'
+}
+
+const KEY = Symbol('tracker.catalogue')
+
+export function setTrackerCatalogue(catalogue: TrackerCatalogue): TrackerCatalogue {
+  return setContext(KEY, catalogue)
+}
+
+export function getTrackerCatalogue(): TrackerCatalogue {
+  const catalogue = getContext<TrackerCatalogue | undefined>(KEY)
+  if (!catalogue) throw new Error('Tracker components must be rendered inside the tracker page')
+  return catalogue
+}

package/src/client/core-api.ts

@@ -0,0 +1,35 @@
+import type { core } from '@kernhq/contracts'
+
+/**
+ * The slice of core's API tracker reaches for, named by shape.
+ *
+ * Tracker needs the workspace's members to fill an assignee picker and draw an avatar on a row.
+ * Typing the seam structurally keeps the dependency pointing one way: tracker does not import
+ * core's router type, and core does not know tracker exists.
+ */
+export interface CoreMember {
+  userId: string
+  user: {
+    id: string
+    name: string | null
+    email: string
+    username?: string | null
+    avatarUrl?: string | null
+  }
+}
+
+export interface CoreApi {
+  workspaces: {
+    members: {
+      list(input: { workspaceId: string; limit?: number }): Promise<{ items: CoreMember[] }>
+    }
+  }
+  files: {
+    downloadUrl(input: {
+      id: string
+      disposition?: 'inline' | 'attachment'
+      thumbnail?: boolean
+    }): Promise<{ url: string }>
+    get(input: { id: string }): Promise<core.FileObject>
+  }
+}

package/src/client/csv.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest'
+import { previewCsv, splitLine } from './csv.js'
+
+describe('splitLine', () => {
+  it('splits on the delimiter', () => {
+    expect(splitLine('a,b,c')).toEqual(['a', 'b', 'c'])
+    expect(splitLine('a;b', ';')).toEqual(['a', 'b'])
+  })
+
+  it('keeps a quoted field whole, delimiter and all', () => {
+    // The single most common way a naive import mangles every row after the first title.
+    expect(splitLine('1,"Crash, then burn",high')).toEqual(['1', 'Crash, then burn', 'high'])
+  })
+
+  it('reads a doubled quote as one quote', () => {
+    expect(splitLine('"He said ""no""",x')).toEqual(['He said "no"', 'x'])
+  })
+
+  it('keeps empty fields, so the columns still line up', () => {
+    expect(splitLine('a,,c')).toEqual(['a', '', 'c'])
+    expect(splitLine(',')).toEqual(['', ''])
+  })
+})
+
+describe('previewCsv', () => {
+  const file = 'Title,Priority\nFix the thing,high\nAnother,low\n'
+
+  it('takes the column names from the header', () => {
+    expect(previewCsv(file).columns).toEqual(['Title', 'Priority'])
+    expect(previewCsv(file).rows[0]).toEqual(['Fix the thing', 'high'])
+  })
+
+  it('numbers the columns from zero without a header, matching what the server indexes by', () => {
+    // Showing 1,2,3 where the server counts 0,1,2 maps every field one place out.
+    const preview = previewCsv(file, { hasHeader: false })
+    expect(preview.columns).toEqual(['0', '1'])
+    expect(preview.rows[0]).toEqual(['Title', 'Priority'])
+  })
+
+  it('ignores blank lines and stops after a few rows', () => {
+    const many = ['H', ...Array.from({ length: 20 }, (_, i) => `row ${i}`), '', ''].join('\n')
+    const preview = previewCsv(many)
+    expect(preview.rows).toHaveLength(3)
+  })
+
+  it('has nothing to show for an empty file', () => {
+    expect(previewCsv('')).toEqual({ columns: [], rows: [] })
+    expect(previewCsv('\n\n')).toEqual({ columns: [], rows: [] })
+  })
+})

package/src/client/csv.ts

@@ -0,0 +1,60 @@
+/**
+ * Just enough CSV to show somebody what they are about to import.
+ *
+ * The server parses the file properly; this reads the first few lines so the mapping screen can
+ * offer the real column names and a row of real values. Guessing at column names, or asking
+ * somebody to map "column 3", turns a five-minute import into a spreadsheet-counting exercise.
+ */
+
+/** Split one CSV line, honouring quotes — a title with a comma in it is one field, not two. */
+export function splitLine(line: string, delimiter = ','): string[] {
+  const fields: string[] = []
+  let current = ''
+  let quoted = false
+  for (let i = 0; i < line.length; i++) {
+    const char = line[i]!
+    if (quoted) {
+      // "" inside a quoted field is one literal quote.
+      if (char === '"' && line[i + 1] === '"') {
+        current += '"'
+        i++
+      } else if (char === '"') quoted = false
+      else current += char
+      continue
+    }
+    if (char === '"') quoted = true
+    else if (char === delimiter) {
+      fields.push(current.trim())
+      current = ''
+    } else current += char
+  }
+  fields.push(current.trim())
+  return fields
+}
+
+export interface CsvPreview {
+  columns: string[]
+  /** the first rows, for showing what a column actually holds */
+  rows: string[][]
+}
+
+/**
+ * Column names and a few rows from the start of a file.
+ *
+ * Without a header row the columns are numbered, because that is what the server will index them
+ * by — showing "1, 2, 3" where the server counts "0, 1, 2" would map every field one place out.
+ */
+export function previewCsv(text: string, opts: { delimiter?: string; hasHeader?: boolean } = {}): CsvPreview {
+  const delimiter = opts.delimiter || ','
+  const hasHeader = opts.hasHeader ?? true
+  const lines = text
+    .split(/\r?\n/)
+    .filter((line) => line.trim() !== '')
+    .slice(0, 6)
+  if (!lines.length) return { columns: [], rows: [] }
+
+  const first = splitLine(lines[0]!, delimiter)
+  const columns = hasHeader ? first : first.map((_, i) => String(i))
+  const rows = (hasHeader ? lines.slice(1) : lines).map((line) => splitLine(line, delimiter))
+  return { columns, rows: rows.slice(0, 3) }
+}

package/src/client/filters.ts

@@ -0,0 +1,94 @@
+import { parseKql } from './kql.js'
+import type { Priority } from './types.js'
+
+/**
+ * The visual filter, and how it becomes KQL.
+ *
+ * The toolbar has two ways to narrow the list, and they must not fight: the Filter menu builds a
+ * structured filter, the query box takes anything KQL can express. They are combined with `and`, so
+ * picking two labels and typing `due <= +7d` means what it looks like it means, and clearing the
+ * chip never touches what you typed.
+ *
+ * Deliberately free of interface strings, so the composition rules can be unit-tested on their own;
+ * the names these appear under live in `./labels`.
+ */
+export interface TrackerFilters {
+  projectIds: string[]
+  statusIds: string[]
+  priorities: Priority[]
+  assigneeIds: string[]
+  labelIds: string[]
+}
+
+export const emptyFilters = (): TrackerFilters => ({
+  projectIds: [],
+  statusIds: [],
+  priorities: [],
+  assigneeIds: [],
+  labelIds: [],
+})
+
+export const filterCount = (f: TrackerFilters): number =>
+  f.projectIds.length + f.statusIds.length + f.priorities.length + f.assigneeIds.length + f.labelIds.length
+
+/** Ids are quoted: a uuid starts with a digit, which KQL would otherwise read as a number. */
+const clause = (field: string, values: string[], quote = true): string | null => {
+  if (values.length === 0) return null
+  const rendered = values.map((v) => (quote ? JSON.stringify(v) : v))
+  return values.length === 1 ? `${field} = ${rendered[0]}` : `${field} in (${rendered.join(', ')})`
+}
+
+export function filtersToKql(f: TrackerFilters): string {
+  return [
+    clause('project', f.projectIds),
+    clause('status', f.statusIds),
+    clause('priority', f.priorities, false),
+    clause('assignee', f.assigneeIds),
+    clause('label', f.labelIds),
+  ]
+    .filter((c): c is string => c !== null)
+    .join(' and ')
+}
+
+/** The saved queries behind the preset tabs (DESIGN.md 2.5). */
+export type Preset = 'assigned' | 'active' | 'backlog' | 'created' | 'subscribed' | 'all'
+
+export const PRESETS: Preset[] = ['assigned', 'active', 'backlog', 'created', 'subscribed', 'all']
+
+export function presetKql(preset: Preset): string {
+  switch (preset) {
+    case 'assigned':
+      return 'assignee = currentUser()'
+    case 'active':
+      return 'statusCategory in (todo, in_progress)'
+    case 'backlog':
+      return 'statusCategory in (backlog, triage)'
+    case 'created':
+      return 'reporter = currentUser()'
+    case 'subscribed':
+      return 'watcher = currentUser()'
+    default:
+      return ''
+  }
+}
+
+/**
+ * A part has to be bracketed before it is joined with `and`, or its `or` swallows the parts around
+ * it: `assignee = currentUser() and priority = urgent or priority = high` means "mine and urgent, or
+ * anyone's high", which quietly shows other people's issues. Asking the parser is the only reliable
+ * test — `OR` is a keyword whatever its case, and the word may equally appear inside a quoted value
+ * ("editor or reviewer"), where it means nothing. A part we cannot parse is bracketed anyway: the
+ * server rejects it either way, and this keeps the failure the user's typo rather than ours.
+ */
+const needsBrackets = (part: string): boolean => {
+  const parsed = parseKql(part)
+  if (!parsed.ok || !parsed.ast) return true
+  return parsed.ast.where?.kind === 'or'
+}
+
+/** Everything the list is narrowed by, as one query the server can answer. */
+export function composeKql(preset: Preset, filters: TrackerFilters, manual: string): string {
+  const parts = [presetKql(preset), filtersToKql(filters), manual.trim()].filter((part) => part.length > 0)
+  if (parts.length < 2) return parts[0] ?? ''
+  return parts.map((part) => (needsBrackets(part) ? `(${part})` : part)).join(' and ')
+}