@taskmark/ui 0.3.0 → 0.3.1

package/lib/taskmark/dev-reload-token.ts

@@ -2,4 +2,4 @@
  * Touched by `taskmark dev` when board markdown changes so Next Fast Refresh
  * re-runs server components that import this module.
  */
-export const DEV_RELOAD_TOKEN = "0"
+export const DEV_RELOAD_TOKEN = "1788031107000"

package/lib/taskmark/discover.ts

@@ -14,13 +14,10 @@ import {
 import type { DiscoveredProject } from "@/lib/taskmark/types"
 
 function hasBoardMarkers(boardPath: string): boolean {
-  return (
-    fs.existsSync(path.join(boardPath, "INDEX.md")) ||
-    fs.existsSync(path.join(boardPath, "epics"))
-  )
+  return fs.existsSync(path.join(boardPath, "epics"))
 }
 
-/** Single-project layout: `<project>/taskmark/` with INDEX.md or epics/. */
+/** Single-project layout: `<project>/taskmark/` with epics/. */
 export function nestedBoardPath(candidateProjectRoot: string): string | null {
   const boardPath = path.join(candidateProjectRoot, "taskmark")
   try {
@@ -33,7 +30,7 @@ export function nestedBoardPath(candidateProjectRoot: string): string | null {
 
 /**
  * Multi-project layout: dedicated `<name>-taskmark` repo whose root is the board
- * (INDEX.md / epics/ at the folder root — no nested taskmark/).
+ * (`epics/` at the folder root — no nested taskmark/).
  */
 export function flatBoardPath(candidateRoot: string): string | null {
   if (!isDedicatedBoardRepoName(path.basename(candidateRoot))) return null
@@ -95,7 +92,7 @@ function shouldSkipDir(name: string): boolean {
  * Walk a master folder and find Taskmark boards in subfolders.
  *
  * Recognizes:
- * - Single-project: any directory with a nested `taskmark/` board (INDEX.md or epics/)
+ * - Single-project: any directory with a nested `taskmark/epics/` board
  * - Multi-project: dedicated `*-taskmark` folders with board files at the repo root
  *
  * Does not require a board at the master root, but includes the master itself if it

package/lib/taskmark/epic-types.ts

@@ -8,7 +8,6 @@ export type EpicSummary = {
   priority: string
   size: string
   points: number | null
-  estimateMinutes: number | null
   actualMinutes: number | null
   actualMs: number | null
   tags: string[]
@@ -16,6 +15,8 @@ export type EpicSummary = {
   resolvers: ContributorIdentity[]
   /** Frontmatter created date (YYYY-MM-DD or ISO). */
   created: string
+  /** Frontmatter updated date (YYYY-MM-DD or ISO). */
+  updated: string
   /** Frontmatter completed_at (ISO) when solved; empty if open. */
   completedAt: string
   /** Stories + tasks + bugs under this epic (story children and epic-direct). */

package/lib/taskmark/flat-work-item-types.ts

@@ -12,7 +12,6 @@ export type FlatWorkItemRow = {
   priority: string
   size: string
   points: number | null
-  estimateMinutes: number | null
   actualMinutes: number | null
   actualMs: number | null
   epicId: string | null
@@ -36,7 +35,6 @@ export type StoryWithEpicRow = {
   priority: string
   size: string
   points: number | null
-  estimateMinutes: number | null
   actualMinutes: number | null
   actualMs: number | null
   epicId: string
@@ -60,7 +58,6 @@ export type TaskWithParentsRow = {
   priority: string
   size: string
   points: number | null
-  estimateMinutes: number | null
   actualMinutes: number | null
   actualMs: number | null
   epicId: string
@@ -87,7 +84,6 @@ export type WorkItemsViewRow = {
   priority: string
   size: string
   points: number | null
-  estimateMinutes: number | null
   actualMinutes: number | null
   actualMs: number | null
   epicId: string
@@ -96,6 +92,7 @@ export type WorkItemsViewRow = {
   reporters: ContributorIdentity[]
   resolvers: ContributorIdentity[]
   created: string
+  updated: string
   /** Frontmatter completed_at when solved; empty if open. */
   completedAt: string
   /** Child tasks/bugs under a story; 0 for epic-direct leaves. */

package/lib/taskmark/identity.ts

@@ -123,13 +123,13 @@ export function buildAttributionAvatars(
     const name = acc.identity.name || "Unknown"
     if (acc.created && acc.resolved) {
       role = "both"
-      label = `Created and developed by ${name}`
+      label = `Reported and implemented by ${name}`
     } else if (acc.created) {
       role = "created"
-      label = `Created by ${name}`
+      label = `Reported by ${name}`
     } else {
       role = "resolved"
-      label = `Resolved by ${name}`
+      label = `Implemented by ${name}`
     }
     out.push({ identity: acc.identity, role, label })
   }

package/lib/taskmark/item-types.ts

@@ -11,7 +11,6 @@ export type ItemSummary = {
   priority: string
   size: string
   points: number | null
-  estimateMinutes: number | null
   actualMinutes: number | null
   actualMs: number | null
   tags: string[]
@@ -19,6 +18,8 @@ export type ItemSummary = {
   resolvers: ContributorIdentity[]
   /** Frontmatter created date (YYYY-MM-DD or ISO). */
   created: string
+  /** Frontmatter updated date (YYYY-MM-DD or ISO). */
+  updated: string
   /** Frontmatter completed_at (ISO) when solved; empty if open. */
   completedAt: string
   parent: string

package/lib/taskmark/list-filters.test.ts

@@ -0,0 +1,23 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+
+import {
+  isCompletedStatus,
+  passesHideCompleted,
+} from "./list-filters"
+
+test("treats shelved as completed", () => {
+  assert.equal(isCompletedStatus("shelved"), true)
+  assert.equal(passesHideCompleted(true, "shelved"), false)
+})
+
+test("uses terminal child progress when filtering parents", () => {
+  assert.equal(
+    passesHideCompleted(true, "shelved", { done: 2, total: 2 }),
+    false
+  )
+  assert.equal(
+    passesHideCompleted(true, "shelved", { done: 1, total: 2 }),
+    true
+  )
+})

package/lib/taskmark/list-filters.ts

@@ -87,10 +87,15 @@ export function matchesWorkItemSearch(
 }
 
 export function isCompletedStatus(status: string): boolean {
-  return status.trim().toLowerCase() === "done"
+  const normalized = status.trim().toLowerCase()
+  return (
+    normalized === "done" ||
+    normalized === "shelved" ||
+    normalized === "cancelled"
+  )
 }
 
-/** True when every child is done (and there is at least one child). */
+/** True when every child is terminal (and there is at least one child). */
 export function isChildProgressComplete(
   done?: number,
   total?: number

package/lib/taskmark/list-view-mode.test.ts

@@ -0,0 +1,45 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+
+import {
+  compareByStatusThenPriority,
+  listViewModes,
+  parseListViewMode,
+  statusSortRank,
+} from "./list-view-mode"
+
+test("omits changelog from the switcher when the file is absent", () => {
+  assert.deepEqual(listViewModes(false), ["overall", "workitems"])
+  assert.equal(parseListViewMode("changelog"), "overall")
+  assert.equal(parseListViewMode("changelog", { hasChangelog: false }), "overall")
+})
+
+test("keeps changelog when content is present", () => {
+  assert.deepEqual(listViewModes(true), ["overall", "workitems", "changelog"])
+  assert.equal(parseListViewMode("changelog", { hasChangelog: true }), "changelog")
+})
+
+test("sorts every incomplete status before shelved", () => {
+  assert.ok(statusSortRank("backlog") < statusSortRank("shelved"))
+  assert.ok(statusSortRank("in_progress") < statusSortRank("shelved"))
+  assert.ok(statusSortRank("blocked") < statusSortRank("shelved"))
+})
+
+test("sorts shelved rows by completion date instead of priority", () => {
+  const olderHighPriority = {
+    id: "T-1",
+    status: "shelved",
+    priority: "critical",
+    completedAt: "2026-08-01",
+  }
+  const newerLowPriority = {
+    id: "T-2",
+    status: "shelved",
+    priority: "low",
+    completedAt: "2026-08-29",
+  }
+
+  assert.ok(
+    compareByStatusThenPriority(olderHighPriority, newerLowPriority) > 0
+  )
+})

package/lib/taskmark/list-view-mode.ts

@@ -1,4 +1,4 @@
-export const LIST_VIEW_MODES = ["overall", "workitems"] as const
+export const LIST_VIEW_MODES = ["overall", "workitems", "changelog"] as const
 
 export type ListViewMode = (typeof LIST_VIEW_MODES)[number]
 
@@ -7,17 +7,27 @@ export const DEFAULT_LIST_VIEW_MODE: ListViewMode = "overall"
 export const LIST_VIEW_LABELS: Record<ListViewMode, string> = {
   overall: "Overall",
   workitems: "Work items",
+  changelog: "Changelog",
 }
 
 /** Legacy view query values that map to Work items. */
 const LEGACY_WORKITEMS_VIEWS = new Set(["all", "stories", "tasks", "workitems"])
 
+export function listViewModes(hasChangelog: boolean): ListViewMode[] {
+  if (hasChangelog) return [...LIST_VIEW_MODES]
+  return LIST_VIEW_MODES.filter((mode) => mode !== "changelog")
+}
+
 export function parseListViewMode(
-  value: string | string[] | undefined
+  value: string | string[] | undefined,
+  options?: { hasChangelog?: boolean }
 ): ListViewMode {
   const raw = typeof value === "string" ? value.trim().toLowerCase() : ""
   if (raw === "overall") return "overall"
   if (LEGACY_WORKITEMS_VIEWS.has(raw)) return "workitems"
+  if (raw === "changelog") {
+    return options?.hasChangelog ? "changelog" : DEFAULT_LIST_VIEW_MODE
+  }
   return DEFAULT_LIST_VIEW_MODE
 }
 
@@ -45,9 +55,10 @@ export function boardHref(opts: {
 const STATUS_RANK: Record<string, number> = {
   backlog: 0,
   in_progress: 1,
-  done: 2,
-  blocked: 3,
-  cancelled: 4,
+  blocked: 2,
+  done: 3,
+  shelved: 4,
+  cancelled: 5,
 }
 
 const PRIORITY_RANK: Record<string, number> = {
@@ -66,9 +77,9 @@ export function prioritySortRank(priority: string): number {
 }
 
 /**
- * Primary: status (backlog → in_progress → done);
+ * Primary: status, with every incomplete state before terminal outcomes;
  * For open statuses: priority (highest first), then created (newest first);
- * For done/cancelled: solved date only (completedAt newest first; no priority);
+ * For done/shelved/cancelled: solved date only (completedAt newest first; no priority);
  * then id.
  */
 export function compareByStatusThenPriority(
@@ -104,7 +115,7 @@ export function compareByStatusThenPriority(
 
 function usesCompletedDate(status: string): boolean {
   const s = status.trim().toLowerCase()
-  return s === "done" || s === "cancelled"
+  return s === "done" || s === "shelved" || s === "cancelled"
 }
 
 function compareByDateThenId(

package/lib/taskmark/load-changelog.test.ts

@@ -0,0 +1,32 @@
+import assert from "node:assert/strict"
+import fs from "node:fs"
+import os from "node:os"
+import path from "node:path"
+import test from "node:test"
+
+import { loadBoardChangelogMarkdown } from "./load-changelog"
+
+function tempBoard(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "taskmark-changelog-"))
+}
+
+test("returns markdown when CHANGELOG.md has content", () => {
+  const dir = tempBoard()
+  fs.writeFileSync(
+    path.join(dir, "CHANGELOG.md"),
+    "# Changelog\n\n## Unreleased\n\n- A button was added.\n"
+  )
+  const loaded = loadBoardChangelogMarkdown(dir)
+  assert.ok(loaded)
+  assert.match(loaded, /A button was added/)
+})
+
+test("treats missing CHANGELOG.md as absent", () => {
+  assert.equal(loadBoardChangelogMarkdown(tempBoard()), null)
+})
+
+test("treats whitespace-only CHANGELOG.md as absent", () => {
+  const dir = tempBoard()
+  fs.writeFileSync(path.join(dir, "CHANGELOG.md"), "  \n\t\n")
+  assert.equal(loadBoardChangelogMarkdown(dir), null)
+})

package/lib/taskmark/load-changelog.ts

@@ -0,0 +1,18 @@
+import fs from "node:fs"
+import path from "node:path"
+
+/**
+ * Read board-root CHANGELOG.md for the UI. Never writes.
+ * Missing, unreadable, or whitespace-only files are absent.
+ */
+export function loadBoardChangelogMarkdown(boardPath: string): string | null {
+  const filePath = path.join(boardPath, "CHANGELOG.md")
+  try {
+    const raw = fs.readFileSync(filePath, "utf8")
+    const trimmed = raw.trim()
+    if (!trimmed) return null
+    return raw
+  } catch {
+    return null
+  }
+}

package/lib/taskmark/overall-tree.test.ts

@@ -0,0 +1,196 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+
+import {
+  buildOverallTree,
+  compareOverallNodes,
+  filterOverallTree,
+  searchRevealIds,
+  type OverallTreeNode,
+} from "./overall-tree"
+
+function node(
+  id: string,
+  overrides: Partial<OverallTreeNode> = {}
+): OverallTreeNode {
+  return {
+    kind: "task",
+    id,
+    title: id,
+    status: "backlog",
+    size: "S",
+    points: 3,
+    tags: [],
+    reporters: [],
+    resolvers: [],
+    created: "2026-01-01",
+    updated: "2026-01-01",
+    completedAt: "",
+    filePath: `/${id}.md`,
+    children: [],
+    workItemCount: 0,
+    doneWorkItemCount: 0,
+    ...overrides,
+  }
+}
+
+test("sorts incomplete before done, shelved, and cancelled", () => {
+  const rows = [
+    node("T-4", { status: "done", created: "2026-08-29" }),
+    node("T-3", { status: "cancelled", created: "2026-08-30" }),
+    node("T-6", { status: "shelved", created: "2026-08-31" }),
+    node("T-2", { created: "2026-08-28", updated: "2026-08-29" }),
+    node("T-1", { created: "2026-08-28", updated: "2026-08-30" }),
+    node("T-0", { created: "2026-08-28", updated: "2026-08-30" }),
+    node("T-5", { created: "2026-08-29" }),
+  ]
+
+  assert.deepEqual(
+    rows.sort(compareOverallNodes).map((row) => row.id),
+    ["T-5", "T-0", "T-1", "T-2", "T-6", "T-3", "T-4"]
+  )
+})
+
+test("hides an empty General epic like the previous Overall list", () => {
+  const general = {
+    ...node("E-008", {
+      kind: "epic",
+      title: "General",
+      filePath: "/epics/E-008-general/epic.md",
+    }),
+    priority: "medium",
+    actualMinutes: null,
+    actualMs: null,
+    project: {},
+  }
+  const list = {
+    project: {},
+    epics: [{ ...general, workItemCount: 0 }],
+    errors: [],
+  } as unknown as Parameters<typeof buildOverallTree>[0]
+
+  assert.deepEqual(buildOverallTree(list, {}, {}), [])
+})
+
+test("search retains ancestors of matching descendants", () => {
+  const tree = [
+    node("E-1", {
+      kind: "epic",
+      title: "Parent",
+      children: [
+        node("S-1", {
+          kind: "story",
+          children: [node("T-1", { title: "Needle task" })],
+        }),
+      ],
+    }),
+  ]
+
+  const filtered = filterOverallTree(tree, {
+    query: "needle",
+    hideCompleted: false,
+    timeframe: { mode: "none" },
+  })
+
+  assert.equal(filtered[0]?.id, "E-1")
+  assert.equal(filtered[0]?.children[0]?.id, "S-1")
+  assert.equal(filtered[0]?.children[0]?.children[0]?.id, "T-1")
+})
+
+test("hide-completed retains completed ancestors with incomplete descendants", () => {
+  const tree = [
+    node("E-1", {
+      kind: "epic",
+      status: "done",
+      children: [
+        node("S-1", {
+          kind: "story",
+          status: "done",
+          children: [node("T-1", { status: "backlog" })],
+        }),
+      ],
+    }),
+  ]
+
+  const filtered = filterOverallTree(tree, {
+    query: "",
+    hideCompleted: true,
+    timeframe: { mode: "none" },
+  })
+
+  assert.equal(filtered[0]?.children[0]?.children[0]?.id, "T-1")
+})
+
+test("hide-completed removes shelved branches", () => {
+  const tree = [
+    node("E-1", {
+      kind: "epic",
+      status: "shelved",
+      children: [
+        node("S-1", {
+          kind: "story",
+          status: "shelved",
+          children: [node("T-1", { status: "shelved" })],
+        }),
+      ],
+    }),
+  ]
+
+  assert.deepEqual(
+    filterOverallTree(tree, {
+      query: "",
+      hideCompleted: true,
+      timeframe: { mode: "none" },
+    }),
+    []
+  )
+})
+
+test("only a search reveals ancestors, so toggles keep the expansion state", () => {
+  const tree = [
+    node("E-1", {
+      kind: "epic",
+      children: [
+        node("S-1", { kind: "story", children: [node("T-1")] }),
+      ],
+    }),
+  ]
+
+  assert.deepEqual(searchRevealIds(tree, ""), [])
+  assert.deepEqual(searchRevealIds(tree, "   "), [])
+  assert.deepEqual(searchRevealIds(tree, "needle"), ["E-1", "S-1"])
+})
+
+test("timeframe retains ancestor context for matching completed leaves", () => {
+  const tree = [
+    node("E-1", {
+      kind: "epic",
+      children: [
+        node("S-1", {
+          kind: "story",
+          children: [
+            node("T-old", {
+              status: "done",
+              completedAt: "2026-01-01",
+            }),
+            node("T-match", {
+              status: "done",
+              completedAt: "2026-08-29",
+            }),
+          ],
+        }),
+      ],
+    }),
+  ]
+
+  const filtered = filterOverallTree(tree, {
+    query: "",
+    hideCompleted: false,
+    timeframe: { mode: "range", from: "2026-08-29", to: "2026-08-29" },
+  })
+
+  assert.deepEqual(
+    filtered[0]?.children[0]?.children.map((child) => child.id),
+    ["T-match"]
+  )
+})