@kernhq/module-tracker 0.10.1 → 0.11.1

package/src/client/module.ts

@@ -0,0 +1,491 @@
+import { defineClientModule } from '@kernhq/ui'
+import { t, trackerMessageBundles } from './i18n.js'
+import { TRACKER_PERMISSIONS } from './permissions.js'
+
+/**
+ * The tracker as the shell sees it.
+ *
+ * A module does not reach into the application: it declares what it contributes — navigation, pages,
+ * command-palette actions, keyboard shortcuts and how its objects are drawn elsewhere — and the shell
+ * composes that with whatever else is enabled for the workspace. Turning the tracker off in workspace
+ * settings removes all of it without a single conditional anywhere in the shell.
+ *
+ * Labels are getters rather than strings because a module is defined once at import time while the
+ * interface language can change afterwards; reading them on render keeps the rail and the palette in
+ * the language the person actually chose.
+ */
+export const trackerClientModule = defineClientModule({
+  id: 'tracker',
+  name: 'Issues',
+  icon: 'square-check-big',
+  messages: trackerMessageBundles,
+
+  nav: [
+    {
+      id: 'tracker',
+      get label() {
+        return t('nav')
+      },
+      icon: 'square-check-big',
+      href: '/tracker',
+      order: 20,
+      permission: TRACKER_PERMISSIONS.view,
+    },
+  ],
+
+  routes: [
+    {
+      path: '/tracker/reports',
+      component: () => import('./pages/ReportsPage.svelte'),
+      get title() {
+        return t('reports_title')
+      },
+      permission: TRACKER_PERMISSIONS.view,
+    },
+    {
+      path: '/tracker',
+      component: () => import('./pages/IssuesPage.svelte'),
+      get title() {
+        return t('title')
+      },
+      permission: TRACKER_PERMISSIONS.view,
+    },
+  ],
+
+  widgets: [
+    {
+      id: 'tracker.issues',
+      get title() {
+        return t('common.widget_issues_title')
+      },
+      get description() {
+        return t('common.widget_issues_desc')
+      },
+      icon: 'square-check-big',
+      permission: TRACKER_PERMISSIONS.view,
+      sizes: ['m', 'l', 'xl'],
+      defaultSize: 'l',
+      order: 10,
+      // One widget instead of six. Every one of these settings resolves into the KQL that
+      // `issues.query` already answers, which is why the same card can be placed twice showing two
+      // entirely different lists.
+      settings: [
+        {
+          kind: 'select',
+          key: 'preset',
+          get label() {
+            return t('common.setting_show')
+          },
+          default: 'assigned',
+          get options() {
+            return [
+              { value: 'assigned', label: t('preset_assigned') },
+              { value: 'active', label: t('preset_active') },
+              { value: 'backlog', label: t('preset_backlog') },
+              { value: 'created', label: t('preset_created') },
+              { value: 'subscribed', label: t('preset_subscribed') },
+              { value: 'triage', label: t('common.widget_preset_triage') },
+            ]
+          },
+        },
+        {
+          kind: 'select',
+          key: 'view',
+          get label() {
+            return t('common.widget_setting_saved_view')
+          },
+          default: null,
+          nullable: true,
+          get nullLabel() {
+            return t('common.widget_setting_no_view')
+          },
+          loadOptions: async (ctx) => {
+            const { getTrackerApi } = await import('./api-instance.js')
+            const views = await getTrackerApi().views.list({ workspaceId: ctx.workspaceId })
+            return views.map((v) => ({ value: v.id, label: v.name }))
+          },
+        },
+        {
+          kind: 'number',
+          key: 'limit',
+          get label() {
+            return t('common.setting_rows')
+          },
+          default: 8,
+          min: 3,
+          max: 20,
+        },
+      ],
+      component: () => import('./widgets/IssuesWidget.svelte'),
+    },
+    {
+      id: 'tracker.stat-assigned',
+      get title() {
+        return t('common.widget_assigned_title')
+      },
+      get description() {
+        return t('common.widget_assigned_desc')
+      },
+      icon: 'square-check-big',
+      permission: TRACKER_PERMISSIONS.view,
+      sizes: ['s'],
+      defaultSize: 's',
+      compact: true,
+      order: 20,
+      component: () => import('./widgets/AssignedCountWidget.svelte'),
+    },
+    {
+      id: 'tracker.stat-due-soon',
+      get title() {
+        return t('common.widget_due_soon_title')
+      },
+      get description() {
+        return t('common.widget_due_soon_desc')
+      },
+      icon: 'clock',
+      permission: TRACKER_PERMISSIONS.view,
+      sizes: ['s'],
+      defaultSize: 's',
+      compact: true,
+      order: 30,
+      component: () => import('./widgets/DueSoonCountWidget.svelte'),
+    },
+    {
+      id: 'tracker.cycle-progress',
+      get title() {
+        return t('common.widget_cycle_title')
+      },
+      get description() {
+        return t('common.widget_cycle_desc')
+      },
+      icon: 'gauge',
+      permission: TRACKER_PERMISSIONS.view,
+      sizes: ['m', 'l'],
+      defaultSize: 'm',
+      order: 40,
+      settings: [
+        {
+          kind: 'select',
+          key: 'project',
+          get label() {
+            return t('common.widget_setting_project')
+          },
+          default: null,
+          nullable: true,
+          get nullLabel() {
+            return t('common.any')
+          },
+          loadOptions: async (ctx) => {
+            const { getTrackerApi } = await import('./api-instance.js')
+            const projects = await getTrackerApi().projects.list({ workspaceId: ctx.workspaceId })
+            return projects.map((p) => ({ value: p.id, label: p.name }))
+          },
+        },
+      ],
+      component: () => import('./widgets/CycleWidget.svelte'),
+    },
+    {
+      id: 'tracker.velocity',
+      get title() {
+        return t('common.widget_velocity_title')
+      },
+      get description() {
+        return t('common.widget_velocity_desc')
+      },
+      icon: 'chart-column',
+      permission: TRACKER_PERMISSIONS.view,
+      // A grouped bar chart is unreadable in a quarter-width card, so `s` is not offered.
+      sizes: ['l', 'xl'],
+      defaultSize: 'l',
+      order: 60,
+      settings: [
+        {
+          kind: 'select',
+          key: 'project',
+          get label() {
+            return t('common.widget_setting_project')
+          },
+          default: null,
+          nullable: true,
+          get nullLabel() {
+            return t('common.any')
+          },
+          loadOptions: async (ctx) => {
+            const { getTrackerApi } = await import('./api-instance.js')
+            const projects = await getTrackerApi().projects.list({ workspaceId: ctx.workspaceId })
+            return projects.map((p) => ({ value: p.id, label: p.name }))
+          },
+        },
+        {
+          kind: 'number',
+          key: 'lastN',
+          get label() {
+            return t('common.widget_velocity_cycles')
+          },
+          default: 6,
+          min: 3,
+          max: 12,
+        },
+      ],
+      component: () => import('./widgets/VelocityWidget.svelte'),
+    },
+    {
+      id: 'tracker.created-vs-resolved',
+      get title() {
+        return t('common.widget_throughput_title')
+      },
+      get description() {
+        return t('common.widget_throughput_desc')
+      },
+      icon: 'chart-line',
+      permission: TRACKER_PERMISSIONS.view,
+      sizes: ['l', 'xl'],
+      defaultSize: 'xl',
+      order: 70,
+      settings: [
+        {
+          kind: 'select',
+          key: 'project',
+          get label() {
+            return t('common.widget_setting_project')
+          },
+          default: null,
+          nullable: true,
+          get nullLabel() {
+            return t('common.any')
+          },
+          loadOptions: async (ctx) => {
+            const { getTrackerApi } = await import('./api-instance.js')
+            const projects = await getTrackerApi().projects.list({ workspaceId: ctx.workspaceId })
+            return projects.map((p) => ({ value: p.id, label: p.name }))
+          },
+        },
+        {
+          kind: 'select',
+          key: 'range',
+          get label() {
+            return t('common.widget_setting_range')
+          },
+          default: '30',
+          get options() {
+            return [
+              { value: '14', label: t('common.widget_range_14') },
+              { value: '30', label: t('common.widget_range_30') },
+              { value: '90', label: t('common.widget_range_90') },
+            ]
+          },
+        },
+      ],
+      component: () => import('./widgets/ThroughputWidget.svelte'),
+    },
+    {
+      id: 'tracker.timer',
+      get title() {
+        return t('common.widget_timer_title')
+      },
+      get description() {
+        return t('common.widget_timer_desc')
+      },
+      icon: 'timer',
+      permission: TRACKER_PERMISSIONS.view,
+      sizes: ['s', 'm'],
+      defaultSize: 's',
+      compact: true,
+      order: 50,
+      component: () => import('./widgets/TimerWidget.svelte'),
+    },
+  ],
+
+  commands: [
+    {
+      id: 'tracker.new-issue',
+      get label() {
+        return t('new_issue')
+      },
+      icon: 'plus',
+      shortcut: ['c'],
+      permission: TRACKER_PERMISSIONS.create,
+      run: (ctx) => ctx.navigate('/tracker?new=1'),
+    },
+    {
+      id: 'tracker.issues',
+      get label() {
+        return t('cmd_open_list')
+      },
+      icon: 'list',
+      permission: TRACKER_PERMISSIONS.view,
+      run: (ctx) => ctx.navigate('/tracker'),
+    },
+    {
+      id: 'tracker.board',
+      get label() {
+        return t('cmd_open_board')
+      },
+      icon: 'columns-3',
+      permission: TRACKER_PERMISSIONS.view,
+      run: (ctx) => ctx.navigate('/tracker?view=board'),
+    },
+    {
+      id: 'tracker.my-issues',
+      get label() {
+        return t('cmd_my_issues')
+      },
+      icon: 'user',
+      permission: TRACKER_PERMISSIONS.view,
+      run: (ctx) => ctx.navigate('/tracker?preset=assigned'),
+    },
+    {
+      id: 'tracker.triage',
+      get label() {
+        return t('cmd_triage')
+      },
+      icon: 'inbox',
+      permission: TRACKER_PERMISSIONS.view,
+      run: (ctx) => ctx.navigate('/tracker?q=triage%20%3D%20true'),
+    },
+    {
+      id: 'tracker.reports',
+      get label() {
+        return t('reports_title')
+      },
+      icon: 'activity',
+      permission: TRACKER_PERMISSIONS.view,
+      run: (ctx) => ctx.navigate('/tracker/reports'),
+    },
+    {
+      id: 'tracker.by-project',
+      get label() {
+        return t('cmd_by_project')
+      },
+      icon: 'diamond',
+      permission: TRACKER_PERMISSIONS.view,
+      run: (ctx) => ctx.navigate('/tracker?group=project'),
+    },
+  ],
+
+  shortcuts: [
+    {
+      id: 'tracker.new-issue',
+      keys: ['c'],
+      get label() {
+        return t('new_issue')
+      },
+      scope: 'tracker',
+      run: (ctx) => ctx.navigate('/tracker?new=1'),
+    },
+  ],
+
+  sidebar: [
+    {
+      id: 'tracker',
+      match: ['tracker'],
+      permission: TRACKER_PERMISSIONS.view,
+      controls: () => import('./components/TrackerControls.svelte'),
+      component: () => import('./components/TrackerSidebar.svelte'),
+    },
+    {
+      // The three "my work" rows used to live in the application layout, where a workspace with the
+      // tracker switched off still saw them.
+      id: 'tracker.home',
+      match: [''],
+      order: 20,
+      permission: TRACKER_PERMISSIONS.view,
+      component: () => import('./components/HomeLinks.svelte'),
+    },
+  ],
+
+  /**
+   * Where the tracker is configured. The shell builds the settings nav from these — label, icon and
+   * permission — while the route itself is conventional (`/settings/<module>/<id>`), so a module
+   * does not have to mount pages dynamically to be configurable.
+   */
+  settingsPages: [
+    {
+      id: 'fields',
+      get label() {
+        return t('settings_fields')
+      },
+      icon: 'tag',
+      scope: 'workspace',
+      permission: TRACKER_PERMISSIONS.fieldManage,
+      order: 10,
+      component: () => import('./settings/FieldsSettings.svelte'),
+    },
+    {
+      id: 'workflows',
+      get label() {
+        return t('settings_workflows')
+      },
+      icon: 'git-branch',
+      scope: 'workspace',
+      permission: TRACKER_PERMISSIONS.workflowManage,
+      order: 25,
+      component: () => import('./settings/WorkflowsSettings.svelte'),
+    },
+    {
+      id: 'projects',
+      get label() {
+        return t('settings_projects')
+      },
+      icon: 'folder',
+      scope: 'workspace',
+      permission: TRACKER_PERMISSIONS.projectManage,
+      order: 5,
+      component: () => import('./settings/ProjectsSettings.svelte'),
+    },
+    {
+      id: 'repeating',
+      get label() {
+        return t('settings_repeating')
+      },
+      icon: 'refresh-cw',
+      scope: 'workspace',
+      permission: TRACKER_PERMISSIONS.projectManage,
+      order: 40,
+      component: () => import('./settings/RepeatingSettings.svelte'),
+    },
+    {
+      id: 'import',
+      get label() {
+        return t('settings_import')
+      },
+      icon: 'upload',
+      scope: 'workspace',
+      permission: TRACKER_PERMISSIONS.projectManage,
+      order: 50,
+      component: () => import('./settings/ImportSettings.svelte'),
+    },
+    {
+      id: 'planning',
+      get label() {
+        return t('settings_planning')
+      },
+      icon: 'diamond',
+      scope: 'workspace',
+      permission: TRACKER_PERMISSIONS.projectManage,
+      order: 30,
+      component: () => import('./settings/PlanningSettings.svelte'),
+    },
+    {
+      id: 'types',
+      get label() {
+        return t('settings_types')
+      },
+      icon: 'layout-grid',
+      scope: 'workspace',
+      permission: TRACKER_PERMISSIONS.typeManage,
+      order: 20,
+      component: () => import('./settings/TypesSettings.svelte'),
+    },
+  ],
+
+  presenters: [
+    {
+      type: 'issue',
+      inline: () => import('./components/IssueInline.svelte'),
+      page: (id, workspaceSlug) => `/${workspaceSlug}/tracker?issue=${encodeURIComponent(id)}`,
+    },
+  ],
+})
+
+export default trackerClientModule

package/src/client/nav.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest'
+import {
+  isProjectSection,
+  isTrackerTarget,
+  projectKql,
+  projectSectionHref,
+  projectTargets,
+  trackerHref,
+} from './nav.js'
+
+const PROJECT = '01920000-0000-7000-8000-0000000000a1'
+
+describe('tracker sidebar links', () => {
+  it('quotes a project id, because KQL would read a bare uuid as a number', () => {
+    expect(projectKql(PROJECT)).toBe(`project = "${PROJECT}"`)
+  })
+
+  it('asks for nothing it does not need', () => {
+    expect(trackerHref('northstar')).toBe('/northstar/tracker')
+    expect(trackerHref('northstar', { preset: 'assigned' })).toBe('/northstar/tracker?preset=assigned')
+  })
+
+  it('carries the query and the grouping a project view stands for', () => {
+    const href = trackerHref('northstar', projectTargets(PROJECT).byComponent)
+    const params = new URL(href, 'https://example.test').searchParams
+    expect(params.get('q')).toBe(projectKql(PROJECT))
+    expect(params.get('group')).toBe('component')
+  })
+
+  it('marks a row current only when the screen shows exactly what it asks for', () => {
+    const at = (search: string) => new URL(`https://example.test/x${search}`).searchParams
+    const components = projectTargets(PROJECT).byComponent
+
+    expect(isTrackerTarget(at(''), {})).toBe(true)
+    expect(isTrackerTarget(at('?preset=assigned'), { preset: 'assigned' })).toBe(true)
+    // the same query grouped differently is a different row
+    expect(isTrackerTarget(at(`?q=${encodeURIComponent(components.q!)}`), components)).toBe(false)
+    expect(isTrackerTarget(at(`?q=${encodeURIComponent(components.q!)}&group=component`), components)).toBe(
+      true,
+    )
+    // "All issues" must not light up while a filtered list is on screen
+    expect(isTrackerTarget(at('?preset=assigned'), {})).toBe(false)
+  })
+
+  it('addresses a project page by the key people know it by', () => {
+    expect(projectSectionHref('northstar', 'KRN', 'milestones')).toBe(
+      '/northstar/tracker/projects/KRN/milestones',
+    )
+    // an unknown section in the URL must not render a blank page
+    expect(isProjectSection('components')).toBe(true)
+    expect(isProjectSection('nonsense')).toBe(false)
+    expect(isProjectSection(undefined)).toBe(false)
+  })
+
+  it('gives no row to a saved view, which has one of its own', () => {
+    const params = new URL('https://example.test/x?view_id=v1').searchParams
+    expect(isTrackerTarget(params, {})).toBe(false)
+  })
+})

package/src/client/nav.ts

@@ -0,0 +1,84 @@
+import type { Project } from './index.js'
+
+/**
+ * Where the tracker's sidebar sends you.
+ *
+ * Every row in the sidebar is a link to a query, not a mode the page is put into: the issues screen
+ * reads what it shows from the URL, so "the components of Marketing" is `q` plus `group` and
+ * nothing else — it can be linked to, opened in a second tab and gone back from. Built here rather
+ * than inline so the row that produces a URL and the row that decides it is the current one cannot
+ * drift apart.
+ *
+ * Project ids rather than keys: `project` compiles to a uuid column, and KQL reads an unquoted
+ * value starting with a digit as a number.
+ */
+export const projectKql = (projectId: string): string => `project = ${JSON.stringify(projectId)}`
+
+export interface TrackerTarget {
+  /** the KQL the row asks for, or '' for none */
+  q?: string
+  /** the grouping, or undefined for the default (status) */
+  group?: string
+  preset?: string
+}
+
+/** A tracker link, with only the parameters the target actually needs. */
+export function trackerHref(workspaceSlug: string, target: TrackerTarget = {}): string {
+  const params = new URLSearchParams()
+  if (target.preset) params.set('preset', target.preset)
+  if (target.q) params.set('q', target.q)
+  if (target.group) params.set('group', target.group)
+  const query = params.toString()
+  return `/${workspaceSlug}/tracker${query ? `?${query}` : ''}`
+}
+
+/** Whether the screen is showing exactly what this row asks for. */
+export function isTrackerTarget(params: URLSearchParams, target: TrackerTarget = {}): boolean {
+  // a saved view is its own row: while one is open no plain row is the current one
+  if (params.get('view_id')) return false
+  return (
+    (params.get('preset') ?? '') === (target.preset ?? '') &&
+    (params.get('q') ?? '') === (target.q ?? '') &&
+    (params.get('group') ?? '') === (target.group ?? '')
+  )
+}
+
+/**
+ * A project's work, as queries.
+ *
+ * The groupings stay because the pages link into them — a component is worth opening as "the issues
+ * in it" once you are looking at the component itself — but they are not what the sidebar's
+ * Components row does any more: that opens the page where components are made.
+ */
+export const projectTargets = (projectId: string) => ({
+  issues: { q: projectKql(projectId) } satisfies TrackerTarget,
+  byComponent: { q: projectKql(projectId), group: 'component' } satisfies TrackerTarget,
+  byMilestone: { q: projectKql(projectId), group: 'milestone' } satisfies TrackerTarget,
+  byCycle: { q: projectKql(projectId), group: 'cycle' } satisfies TrackerTarget,
+  triage: { q: `${projectKql(projectId)} and triage = true` } satisfies TrackerTarget,
+})
+
+/**
+ * A project's own pages, addressed by key.
+ *
+ * Components, milestones, cycles and templates are things a team makes, so each is a page rather
+ * than a grouping of the issue list: `/tracker/projects/KRN/components` is where you add one.
+ */
+export const PROJECT_SECTIONS = ['components', 'milestones', 'cycles', 'templates'] as const
+export type ProjectSection = (typeof PROJECT_SECTIONS)[number]
+
+export const isProjectSection = (value: string | undefined): value is ProjectSection =>
+  PROJECT_SECTIONS.includes((value ?? '') as ProjectSection)
+
+export const projectSectionHref = (
+  workspaceSlug: string,
+  projectKey: string,
+  section: ProjectSection,
+): string => `/${workspaceSlug}/tracker/projects/${encodeURIComponent(projectKey)}/${section}`
+
+/** Settings pages take the project in the URL, so a menu can land on the one you clicked. */
+export const projectSettingsHref = (workspaceSlug: string, page: string, projectId: string): string =>
+  `/${workspaceSlug}/settings/tracker/${page}?project=${encodeURIComponent(projectId)}`
+
+/** A project's colour square falls back to the neutral the design system uses for "no colour". */
+export const projectColor = (project: Project): string => project.color ?? 'var(--kern-ink-330)'