@kernhq/module-tracker 0.10.1 → 0.11.1

package/src/client/project/TemplatesPage.svelte

@@ -0,0 +1,321 @@
+<script lang="ts">
+import {
+  Button,
+  Dialog,
+  DropdownMenu,
+  EmptyState,
+  IconButton,
+  Input,
+  type MenuItem,
+  Textarea,
+  toast,
+} from '@kernhq/ui'
+import { createMutation, createQuery, useQueryClient } from '@tanstack/svelte-query'
+import { getTrackerApi } from '../api-instance.js'
+import { t } from '../i18n.js'
+import type { IssueTemplate } from '../index.js'
+import { projectTargets, trackerHref } from '../nav.js'
+import { canTracker } from '../permissions.js'
+import { trackerKeys } from '../query.js'
+import { useRouteProject } from './context.svelte.js'
+import ProjectShell from './ProjectShell.svelte'
+
+/**
+ * A project's issue templates: the starting point for work somebody raises again and again.
+ *
+ * `issues.templates.create` has existed since the module did and nothing ever called it, so the one
+ * screen that listed templates could only delete them. A template is a name, what the issue it
+ * raises is called, and the note that goes in its description.
+ */
+const api = getTrackerApi()
+const queryClient = useQueryClient()
+
+const at = useRouteProject()
+const slug = $derived(at.slug)
+const workspaceId = $derived(at.workspaceId)
+const projectId = $derived(at.projectId)
+const canManage = $derived(canTracker('projectManage'))
+const canCreate = $derived(canTracker('create'))
+
+const templatesQuery = createQuery(() => ({
+  queryKey: trackerKeys.issueTemplates(workspaceId, projectId),
+  queryFn: () => api.issues.templates.list({ workspaceId, projectId }),
+  enabled: Boolean(projectId),
+}))
+const templates = $derived(templatesQuery.data ?? [])
+
+const invalidate = () => void queryClient.invalidateQueries({ queryKey: ['tracker', 'issue-template'] })
+const fail = (error: Error) => toast.error(error.message)
+
+let editing = $state<IssueTemplate | null>(null)
+let creating = $state(false)
+let draftName = $state('')
+let draftTitle = $state('')
+let draftBody = $state('')
+/** Named on screen before it happens, never straight off a menu. */
+let confirming = $state<IssueTemplate | null>(null)
+
+const open = (template: IssueTemplate | null) => {
+  editing = template
+  creating = template === null
+  draftName = template?.name ?? ''
+  draftTitle = (template?.defaults?.title as string | undefined) ?? ''
+  draftBody = template?.description ?? ''
+}
+const close = () => {
+  editing = null
+  creating = false
+}
+
+const save = createMutation(() => ({
+  mutationFn: () => {
+    const name = draftName.trim()
+    // Without a title of its own the issue starts with the template's name, which is what somebody
+    // means by "Incident review" far more often than an empty title.
+    const body = {
+      name,
+      description: draftBody.trim() || null,
+      defaults: { title: draftTitle.trim() || name },
+    }
+    return editing
+      ? api.issues.templates.update({ workspaceId, id: editing.id, patch: body } as never)
+      : api.issues.templates.create({ workspaceId, projectId, ...body } as never)
+  },
+  onSuccess: () => {
+    close()
+    invalidate()
+  },
+  onError: fail,
+}))
+
+const remove = createMutation(() => ({
+  mutationFn: (id: string) => api.issues.templates.delete({ workspaceId, id }),
+  onSuccess: () => {
+    confirming = null
+    invalidate()
+  },
+  onError: fail,
+}))
+
+const menuFor = (template: IssueTemplate): MenuItem[] =>
+  canManage
+    ? [
+        { type: 'item', id: 'edit', label: t('common.edit'), icon: 'pencil', onSelect: () => open(template) },
+        {
+          type: 'item',
+          id: 'delete',
+          label: t('common.delete'),
+          icon: 'trash-2',
+          danger: true,
+          onSelect: () => (confirming = template),
+        },
+      ]
+    : []
+
+/** Raising one: the issue dialog opens on this project, with the list it belongs to underneath. */
+const newIssueHref = $derived(
+  projectId ? `${trackerHref(slug, projectTargets(projectId).issues)}&new=1&project=${projectId}` : '',
+)
+</script>
+
+<ProjectShell
+  project={at.project}
+  pending={at.pending}
+  {slug}
+  projectKey={at.projectKey}
+  title={t('template_title')}
+  subtitle={t('templates_count', { count: templates.length })}
+>
+  {#snippet headerActions()}
+    {#if canManage}
+      <Button size="sm" icon="plus" onclick={() => open(null)} data-testid="template-new">
+        {t('template_new')}
+      </Button>
+    {/if}
+  {/snippet}
+
+  {#snippet children()}
+    {#if templatesQuery.isPending}
+      <p class="quiet">{t('common.loading')}</p>
+    {:else if !templates.length}
+      <EmptyState icon="copy" title={t('template_empty')} description={t('template_hint')}>
+        {#snippet actions()}
+          {#if canManage}
+            <Button size="sm" icon="plus" onclick={() => open(null)}>{t('template_new')}</Button>
+          {/if}
+        {/snippet}
+      </EmptyState>
+    {:else}
+      <div class="list" data-testid="template-list">
+        {#each templates as template (template.id)}
+          <article class="card" data-item={template.name}>
+            <div class="what">
+              <h3>{template.name}</h3>
+              {#if template.defaults?.title}
+                <p class="starts">{t('template_starts', { title: template.defaults.title })}</p>
+              {/if}
+              {#if template.description}<p class="note">{template.description}</p>{/if}
+              {#if template.subItems.length}
+                <span class="chip">{t('template_subitems', { count: template.subItems.length })}</span>
+              {/if}
+            </div>
+            <div class="acts">
+              {#if canCreate}
+                <Button size="xs" variant="secondary" href={newIssueHref}>{t('template_use')}</Button>
+              {/if}
+              {#if menuFor(template).length}
+                <DropdownMenu items={menuFor(template)} align="end">
+                  {#snippet trigger(props)}
+                    <IconButton
+                      {...props}
+                      icon="ellipsis"
+                      size={26}
+                      label={t('template_actions', { name: template.name })}
+                    />
+                  {/snippet}
+                </DropdownMenu>
+              {/if}
+            </div>
+          </article>
+        {/each}
+      </div>
+    {/if}
+  {/snippet}
+</ProjectShell>
+
+<Dialog
+  open={creating || editing !== null}
+  title={editing ? t('template_edit') : t('template_new')}
+  size="sm"
+  onOpenChange={(next: boolean) => {
+    if (!next) close()
+  }}
+>
+  <div class="form">
+    <label class="frow">
+      <span class="lbl">{t('template_name')}</span>
+      <Input bind:value={draftName} data-testid="template-name" />
+    </label>
+    <label class="frow">
+      <span class="lbl">{t('template_issue_title')}</span>
+      <Input bind:value={draftTitle} data-testid="template-title" />
+    </label>
+    <label class="frow">
+      <span class="lbl">{t('project_description')}</span>
+      <Textarea bind:value={draftBody} rows={3} data-testid="template-body" />
+    </label>
+  </div>
+
+  {#snippet footer()}
+    <Button variant="ghost" size="sm" onclick={close}>{t('common.cancel')}</Button>
+    <Button
+      size="sm"
+      disabled={!draftName.trim()}
+      loading={save.isPending}
+      onclick={() => save.mutate()}
+      data-testid="template-save"
+    >
+      {t('common.save')}
+    </Button>
+  {/snippet}
+</Dialog>
+
+<Dialog
+  open={confirming !== null}
+  title={t('planning_remove', { name: confirming?.name ?? '' })}
+  size="sm"
+  onOpenChange={(next: boolean) => {
+    if (!next) confirming = null
+  }}
+>
+  <p class="body">{t('planning_remove_body', { name: confirming?.name ?? '' })}</p>
+
+  {#snippet footer()}
+    <Button variant="ghost" size="sm" onclick={() => (confirming = null)}>{t('common.cancel')}</Button>
+    <Button
+      size="sm"
+      variant="danger"
+      loading={remove.isPending}
+      onclick={() => confirming && remove.mutate(confirming.id)}
+      data-testid="template-delete-confirm"
+    >
+      {t('common.delete')}
+    </Button>
+  {/snippet}
+</Dialog>
+
+<style>
+.list {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+.card {
+  display: flex;
+  align-items: flex-start;
+  gap: 14px;
+  background: var(--kern-surface-raised);
+  border: 1px solid var(--kern-border);
+  border-radius: var(--kern-r-2xl);
+  padding: 14px 16px;
+}
+.what {
+  flex: 1;
+  min-width: 0;
+}
+h3 {
+  margin: 0;
+  font-size: 14.5px;
+  font-weight: 500;
+  color: var(--kern-ink-900);
+}
+.starts {
+  margin: 4px 0 0;
+  font-size: 13px;
+  color: var(--kern-ink-500);
+}
+.note {
+  margin: 6px 0 0;
+  font-size: 13px;
+  line-height: 1.5;
+  color: var(--kern-ink-450);
+}
+.chip {
+  display: inline-flex;
+  align-items: center;
+  height: 24px;
+  margin-top: 10px;
+  padding: 0 9px;
+  border-radius: var(--kern-r-md);
+  background: var(--kern-surface-chip);
+  color: var(--kern-ink-500);
+  font-size: 12px;
+}
+.acts {
+  flex: none;
+  display: flex;
+  align-items: center;
+  gap: 4px;
+}
+.quiet {
+  margin: 0;
+  font-size: 13px;
+  color: var(--kern-ink-400);
+}
+.form {
+  display: grid;
+  gap: 12px;
+}
+.frow {
+  display: grid;
+  gap: 4px;
+}
+.lbl {
+  font-size: 12px;
+  color: var(--kern-ink-550);
+}
+.body {
+  margin: 0;
+  font-size: 13px;
+}
+</style>

package/src/client/project/context.svelte.ts

@@ -0,0 +1,58 @@
+import { navigation, session } from '@kernhq/ui'
+import { createQuery } from '@tanstack/svelte-query'
+import { getTrackerApi } from '../api-instance.js'
+import type { Project } from '../index.js'
+import { trackerKeys } from '../query.js'
+
+/**
+ * The project a page is about, taken from the URL.
+ *
+ * Every one of a project's pages needs the same three things — the workspace, the project and
+ * whether it has arrived yet — and they must not each resolve them differently. The list itself is
+ * one query the whole tracker shares, so asking for it here costs nothing beyond the first page.
+ */
+export interface RouteProject {
+  readonly slug: string
+  readonly workspaceId: string
+  readonly projectKey: string
+  readonly project: Project | null
+  readonly projectId: string
+  readonly pending: boolean
+}
+
+export function useRouteProject(): RouteProject {
+  const api = getTrackerApi()
+
+  const slug = $derived(navigation.workspaceSlug)
+  const workspaceId = $derived(session.workspaces.find((w) => w.slug === slug)?.id ?? '')
+  const projectKey = $derived((navigation.params.key ?? '').toUpperCase())
+
+  const projectsQuery = createQuery(() => ({
+    queryKey: trackerKeys.projects(workspaceId),
+    queryFn: () => api.projects.list({ workspaceId }),
+    enabled: Boolean(workspaceId),
+  }))
+
+  const project = $derived((projectsQuery.data ?? []).find((p) => p.key === projectKey) ?? null)
+
+  return {
+    get slug() {
+      return slug
+    },
+    get workspaceId() {
+      return workspaceId
+    },
+    get projectKey() {
+      return projectKey
+    },
+    get project() {
+      return project
+    },
+    get projectId() {
+      return project?.id ?? ''
+    },
+    get pending() {
+      return projectsQuery.isPending
+    },
+  }
+}

package/src/client/query.ts

@@ -0,0 +1,50 @@
+/**
+ * Query keys for the tracker.
+ *
+ * Same convention as the core keys in `$lib/query`: `[module, entity, ...scope]`. The realtime
+ * gateway sends `{module, entity, id}` for every change, so a tracker event invalidates exactly the
+ * lists and panels that depend on it instead of refetching the whole page.
+ */
+export const trackerKeys = {
+  projects: (workspaceId: string) => ['tracker', 'project', workspaceId] as const,
+  project: (workspaceId: string, projectId: string) =>
+    ['tracker', 'project', workspaceId, projectId] as const,
+  statuses: (workspaceId: string) => ['tracker', 'status', workspaceId] as const,
+  types: (workspaceId: string) => ['tracker', 'type', workspaceId] as const,
+  labels: (workspaceId: string) => ['tracker', 'label', workspaceId] as const,
+  fields: (workspaceId: string) => ['tracker', 'field', workspaceId] as const,
+  cycles: (workspaceId: string, projectId: string | null) =>
+    ['tracker', 'cycle', workspaceId, projectId ?? 'all'] as const,
+  milestones: (workspaceId: string, projectId: string | null) =>
+    ['tracker', 'milestone', workspaceId, projectId ?? 'all'] as const,
+  components: (workspaceId: string, projectId: string | null) =>
+    ['tracker', 'component', workspaceId, projectId ?? 'all'] as const,
+  versions: (workspaceId: string, projectId: string | null) =>
+    ['tracker', 'version', workspaceId, projectId ?? 'all'] as const,
+  /** a project's issue templates: what somebody raises again and again */
+  issueTemplates: (workspaceId: string, projectId: string | null) =>
+    ['tracker', 'issue-template', workspaceId, projectId ?? 'all'] as const,
+  views: (workspaceId: string) => ['tracker', 'view', workspaceId] as const,
+  worklogs: (workspaceId: string, issueId: string) => ['tracker', 'worklog', workspaceId, issueId] as const,
+  /** the caller's running timer, which is theirs rather than any issue's */
+  timer: (workspaceId: string) => ['tracker', 'timer', workspaceId] as const,
+  /** one entry per distinct query: the KQL string and ordering are the scope */
+  issues: (workspaceId: string, scope: string) => ['tracker', 'issue', workspaceId, scope] as const,
+  issue: (workspaceId: string, issueId: string) => ['tracker', 'issue', workspaceId, issueId] as const,
+  comments: (workspaceId: string, issueId: string) => ['tracker', 'comment', workspaceId, issueId] as const,
+  attachments: (workspaceId: string, issueId: string) =>
+    ['tracker', 'attachment', workspaceId, issueId] as const,
+  relations: (workspaceId: string, issueId: string) => ['tracker', 'relation', workspaceId, issueId] as const,
+  links: (workspaceId: string, issueId: string) => ['tracker', 'link', workspaceId, issueId] as const,
+  approvals: (workspaceId: string, issueId: string) => ['tracker', 'approval', workspaceId, issueId] as const,
+  /** an issue's sub-issues — an issue query, but keyed to the parent it hangs off */
+  children: (workspaceId: string, issueId: string) =>
+    ['tracker', 'issue', workspaceId, 'children', issueId] as const,
+  history: (workspaceId: string, issueId: string) => ['tracker', 'history', workspaceId, issueId] as const,
+  transitions: (workspaceId: string, issueId: string) =>
+    ['tracker', 'transition', workspaceId, issueId] as const,
+  kqlFields: (workspaceId: string) => ['tracker', 'kql-field', workspaceId] as const,
+  /** the resolved field layout of one work item type in one project */
+  layout: (workspaceId: string, typeId: string, projectId: string | null) =>
+    ['tracker', 'type', workspaceId, 'layout', typeId, projectId ?? 'none'] as const,
+}

package/src/client/recurrence.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest'
+import { describeRecurrence } from './recurrence.js'
+
+const rule = (over: Record<string, unknown>) =>
+  ({ freq: 'weekly', interval: 1, at: '09:00', ...over }) as never
+
+describe('describeRecurrence', () => {
+  it('says the plain cases plainly', () => {
+    expect(describeRecurrence(rule({ freq: 'daily' }))).toBe('Every day at 09:00')
+    expect(describeRecurrence(rule({ freq: 'weekly' }))).toBe('Every week at 09:00')
+    expect(describeRecurrence(rule({ freq: 'monthly' }))).toBe('Every month at 09:00')
+  })
+
+  it('says the interval when it is not one', () => {
+    expect(describeRecurrence(rule({ freq: 'weekly', interval: 2 }))).toBe('Every 2 weeks at 09:00')
+  })
+
+  it('names the days of the week', () => {
+    // 0 is Sunday, which is the one that is easy to get wrong.
+    expect(describeRecurrence(rule({ byWeekday: [1] }))).toBe('Every week on Monday at 09:00')
+    expect(describeRecurrence(rule({ byWeekday: [0] }))).toBe('Every week on Sunday at 09:00')
+    expect(describeRecurrence(rule({ byWeekday: [1, 4] }))).toBe('Every week on Monday, Thursday at 09:00')
+  })
+
+  it('names the day of the month', () => {
+    expect(describeRecurrence(rule({ freq: 'monthly', byMonthDay: 1 }))).toBe(
+      'Every month on the 1st at 09:00',
+    )
+  })
+
+  it('says when it stops, because that is part of what somebody is agreeing to', () => {
+    expect(describeRecurrence(rule({ count: 6 }))).toBe('Every week at 09:00, 6 times')
+    expect(describeRecurrence(rule({ until: '2026-12-31T00:00:00.000Z' }))).toBe(
+      'Every week at 09:00, until 2026-12-31',
+    )
+  })
+})

package/src/client/recurrence.ts

@@ -0,0 +1,89 @@
+import type { RecurrenceRule } from './index.js'
+
+/**
+ * A recurrence rule, said the way somebody would say it.
+ *
+ * `{freq: 'weekly', interval: 2, byWeekday: [1], at: '09:00'}` is precise and unreadable. Somebody
+ * setting up a fortnightly review needs to see "Every 2 weeks on Monday at 09:00" and know at a
+ * glance whether they got it right — a schedule you cannot read is a schedule you cannot check.
+ *
+ * The wording is passed in rather than imported. A module that reaches for `$msg` cannot be
+ * unit-tested — SvelteKit's aliases come from `svelte.config.js`, which vitest does not read — and
+ * a sentence-builder nobody can test is exactly the kind that gets Sunday wrong.
+ */
+export interface RecurrenceStrings {
+  every: (unit: string) => string
+  everyN: (n: number, unit: string) => string
+  day: string
+  week: string
+  month: string
+  year: string
+  on: (when: string, days: string) => string
+  dayOfMonth: (day: string) => string
+  at: (when: string, time: string) => string
+  times: (text: string, count: number) => string
+  until: (text: string, date: string) => string
+}
+
+/** Plain English, and what the tests read against. */
+export const ENGLISH: RecurrenceStrings = {
+  every: (unit) => `Every ${unit}`,
+  everyN: (n, unit) => `Every ${n} ${unit}s`,
+  day: 'day',
+  week: 'week',
+  month: 'month',
+  year: 'year',
+  on: (when, days) => `${when} on ${days}`,
+  dayOfMonth: (day) => `the ${day}`,
+  at: (when, time) => `${when} at ${time}`,
+  times: (text, count) => `${text}, ${count} times`,
+  until: (text, date) => `${text}, until ${date}`,
+}
+
+/** Sunday-first, matching `byWeekday` where 0 is Sunday. */
+const weekdayName = (day: number, locale: string): string =>
+  new Intl.DateTimeFormat(locale, { weekday: 'long' }).format(
+    // 2024-01-07 was a Sunday, so adding the index lands on the right day.
+    new Date(Date.UTC(2024, 0, 7 + day)),
+  )
+
+const ordinal = (day: number, locale: string): string =>
+  locale.startsWith('en') && new Intl.PluralRules(locale, { type: 'ordinal' }).select(day) === 'one'
+    ? `${day}st`
+    : String(day)
+
+export function describeRecurrence(
+  rule: RecurrenceRule,
+  strings: RecurrenceStrings = ENGLISH,
+  locale = 'en',
+): string {
+  const every = (unit: string) =>
+    rule.interval > 1 ? strings.everyN(rule.interval, unit) : strings.every(unit)
+
+  let when: string
+  switch (rule.freq) {
+    case 'daily':
+      when = every(strings.day)
+      break
+    case 'weekly': {
+      when = every(strings.week)
+      const days = (rule.byWeekday ?? []).map((d) => weekdayName(d, locale))
+      if (days.length) when = strings.on(when, days.join(', '))
+      break
+    }
+    case 'monthly': {
+      when = every(strings.month)
+      if (rule.byMonthDay) when = strings.on(when, strings.dayOfMonth(ordinal(rule.byMonthDay, locale)))
+      break
+    }
+    default:
+      when = every(strings.year)
+  }
+
+  let text = strings.at(when, rule.at)
+  // An end condition changes what somebody is agreeing to, so it is part of the sentence rather
+  // than a detail on another line.
+  if (rule.count) text = strings.times(text, rule.count)
+  else if (rule.until) text = strings.until(text, rule.until.slice(0, 10))
+  return text
+}