@taskmark/ui 0.1.0

package/dist/standalone/dist/standalone/dist/standalone/dist/standalone/lib/taskmark/table-sort.ts

@@ -0,0 +1,344 @@
+/** Pure table-sort types and comparators for board lists. */
+
+import {
+  prioritySortRank,
+  statusSortRank,
+} from "@/lib/taskmark/list-view-mode"
+import type { ContributorIdentity } from "@/lib/taskmark/identity"
+
+export const TABLE_SORT_KEYS = [
+  "id",
+  "title",
+  "size",
+  "epic",
+  "points",
+  "status",
+  "priority",
+  "type",
+  "people",
+] as const
+
+export type TableSortKey = (typeof TABLE_SORT_KEYS)[number]
+
+export type TableSortDirection = "asc" | "desc"
+
+export type TableSortState = {
+  key: TableSortKey
+  direction: TableSortDirection
+}
+
+/** T-shirt rank: XS < S < M < L < XL. Unknown / empty sorts last. */
+const SIZE_RANK: Record<string, number> = {
+  XS: 1,
+  S: 2,
+  M: 3,
+  L: 4,
+  XL: 5,
+}
+
+const ID_PREFIX_RANK: Record<string, number> = {
+  E: 1,
+  S: 2,
+  T: 3,
+  B: 4,
+}
+
+export function isTableSortKey(value: string): value is TableSortKey {
+  return (TABLE_SORT_KEYS as readonly string[]).includes(value)
+}
+
+export function sizeSortRank(size: string | null | undefined): number | null {
+  if (!size?.trim()) return null
+  const rank = SIZE_RANK[size.trim().toUpperCase()]
+  return rank ?? null
+}
+
+/**
+ * Natural Taskmark id compare: prefix (E/S/T/B) then numeric suffix.
+ * Falls back to case-insensitive string compare.
+ */
+export function compareTaskmarkIds(a: string, b: string): number {
+  const pa = parseTaskmarkId(a)
+  const pb = parseTaskmarkId(b)
+  if (pa && pb) {
+    if (pa.prefixRank !== pb.prefixRank) return pa.prefixRank - pb.prefixRank
+    if (pa.num !== pb.num) return pa.num - pb.num
+    return pa.raw.localeCompare(pb.raw)
+  }
+  return a.localeCompare(b, undefined, { sensitivity: "base", numeric: true })
+}
+
+function parseTaskmarkId(id: string): {
+  prefixRank: number
+  num: number
+  raw: string
+} | null {
+  const m = id.trim().match(/^([A-Za-z]+)-(\d+)$/)
+  if (!m) return null
+  const prefix = m[1]!.toUpperCase()
+  const prefixRank = ID_PREFIX_RANK[prefix] ?? 100 + prefix.charCodeAt(0)
+  return { prefixRank, num: Number(m[2]), raw: id.trim() }
+}
+
+/** Null/empty values always sort after defined values (both directions). */
+export function compareNullable(
+  a: number | null,
+  b: number | null,
+  direction: TableSortDirection
+): number | null {
+  if (a === null && b === null) return 0
+  if (a === null) return 1
+  if (b === null) return -1
+  const cmp = a - b
+  return direction === "asc" ? cmp : -cmp
+}
+
+export function compareStrings(
+  a: string | null | undefined,
+  b: string | null | undefined,
+  direction: TableSortDirection
+): number {
+  const left = a?.trim() ?? ""
+  const right = b?.trim() ?? ""
+  if (!left && !right) return 0
+  if (!left) return 1
+  if (!right) return -1
+  const cmp = left.localeCompare(right, undefined, {
+    sensitivity: "base",
+    numeric: true,
+  })
+  return direction === "asc" ? cmp : -cmp
+}
+
+export function compareSizes(
+  a: string | null | undefined,
+  b: string | null | undefined,
+  direction: TableSortDirection
+): number {
+  const ra = sizeSortRank(a)
+  const rb = sizeSortRank(b)
+  const ranked = compareNullable(ra, rb, direction)
+  if (ranked !== null && ranked !== 0) return ranked
+  if (ranked === 0 && ra !== null) return 0
+  // Both unknown: fall back to string
+  return compareStrings(a, b, direction)
+}
+
+export function compareIds(
+  a: string | null | undefined,
+  b: string | null | undefined,
+  direction: TableSortDirection
+): number {
+  const left = a?.trim() ?? ""
+  const right = b?.trim() ?? ""
+  if (!left && !right) return 0
+  if (!left) return 1
+  if (!right) return -1
+  const cmp = compareTaskmarkIds(left, right)
+  return direction === "asc" ? cmp : -cmp
+}
+
+/** Epic: title primary, id tie-break; missing epic last. */
+export function compareEpics(
+  a: { epicId?: string | null; epicTitle?: string | null },
+  b: { epicId?: string | null; epicTitle?: string | null },
+  direction: TableSortDirection
+): number {
+  const aKey = (a.epicTitle?.trim() || a.epicId?.trim() || "").toLowerCase()
+  const bKey = (b.epicTitle?.trim() || b.epicId?.trim() || "").toLowerCase()
+  if (!aKey && !bKey) {
+    return compareIds(a.epicId, b.epicId, direction)
+  }
+  if (!aKey) return 1
+  if (!bKey) return -1
+  const titleCmp = aKey.localeCompare(bKey, undefined, { sensitivity: "base" })
+  if (titleCmp !== 0) {
+    return direction === "asc" ? titleCmp : -titleCmp
+  }
+  return compareIds(a.epicId, b.epicId, direction)
+}
+
+export function comparePoints(
+  a: number | null | undefined,
+  b: number | null | undefined,
+  direction: TableSortDirection
+): number {
+  const left = a == null || Number.isNaN(a) ? null : a
+  const right = b == null || Number.isNaN(b) ? null : b
+  const ranked = compareNullable(left, right, direction)
+  return ranked ?? 0
+}
+
+/** Workflow order: backlog < in_progress < done < blocked < cancelled. */
+export function compareStatuses(
+  a: string | null | undefined,
+  b: string | null | undefined,
+  direction: TableSortDirection
+): number {
+  const left = a?.trim() ?? ""
+  const right = b?.trim() ?? ""
+  if (!left && !right) return 0
+  if (!left) return 1
+  if (!right) return -1
+  const cmp = statusSortRank(left) - statusSortRank(right)
+  return direction === "asc" ? cmp : -cmp
+}
+
+/** Priority order: critical < high < medium < low (asc = most urgent first). */
+export function comparePriorities(
+  a: string | null | undefined,
+  b: string | null | undefined,
+  direction: TableSortDirection
+): number {
+  const left = a?.trim() ?? ""
+  const right = b?.trim() ?? ""
+  if (!left && !right) return 0
+  if (!left) return 1
+  if (!right) return -1
+  const cmp = prioritySortRank(left) - prioritySortRank(right)
+  return direction === "asc" ? cmp : -cmp
+}
+
+const TYPE_RANK: Record<string, number> = {
+  epic: 0,
+  story: 1,
+  task: 2,
+  bug: 3,
+}
+
+export function typeSortRank(type: string | null | undefined): number | null {
+  if (!type?.trim()) return null
+  const rank = TYPE_RANK[type.trim().toLowerCase()]
+  return rank ?? null
+}
+
+/** epic < story < task < bug; unknown last. */
+export function compareTypes(
+  a: string | null | undefined,
+  b: string | null | undefined,
+  direction: TableSortDirection
+): number {
+  const ra = typeSortRank(a)
+  const rb = typeSortRank(b)
+  const ranked = compareNullable(ra, rb, direction)
+  if (ranked !== null && ranked !== 0) return ranked
+  if (ranked === 0 && ra !== null) return 0
+  return compareStrings(a, b, direction)
+}
+
+/** Stable label from unique contributors (name, else email), sorted. */
+export function peopleSortLabel(
+  reporters?: readonly ContributorIdentity[] | null,
+  resolvers?: readonly ContributorIdentity[] | null
+): string {
+  const seen = new Set<string>()
+  const labels: string[] = []
+  for (const person of [...(reporters ?? []), ...(resolvers ?? [])]) {
+    const id = (person.email || person.name || "").trim().toLowerCase()
+    if (!id || seen.has(id)) continue
+    seen.add(id)
+    labels.push((person.name || person.email || "").trim().toLowerCase())
+  }
+  labels.sort((a, b) => a.localeCompare(b, undefined, { sensitivity: "base" }))
+  return labels.join(", ")
+}
+
+export function comparePeople(
+  a: {
+    reporters?: readonly ContributorIdentity[] | null
+    resolvers?: readonly ContributorIdentity[] | null
+  },
+  b: {
+    reporters?: readonly ContributorIdentity[] | null
+    resolvers?: readonly ContributorIdentity[] | null
+  },
+  direction: TableSortDirection
+): number {
+  return compareStrings(
+    peopleSortLabel(a.reporters, a.resolvers),
+    peopleSortLabel(b.reporters, b.resolvers),
+    direction
+  )
+}
+
+export type SortableRowFields = {
+  id?: string | null
+  title?: string | null
+  size?: string | null
+  epicId?: string | null
+  epicTitle?: string | null
+  points?: number | null
+  status?: string | null
+  priority?: string | null
+  /** Work-item kind or item type (`story` / `task` / `bug` / `epic`). */
+  kind?: string | null
+  type?: string | null
+  reporters?: readonly ContributorIdentity[] | null
+  resolvers?: readonly ContributorIdentity[] | null
+}
+
+export function compareSortableRows(
+  a: SortableRowFields,
+  b: SortableRowFields,
+  state: TableSortState
+): number {
+  switch (state.key) {
+    case "id":
+      return compareIds(a.id, b.id, state.direction)
+    case "title":
+      return compareStrings(a.title, b.title, state.direction)
+    case "size":
+      return compareSizes(a.size, b.size, state.direction)
+    case "epic":
+      return compareEpics(a, b, state.direction)
+    case "points":
+      return comparePoints(a.points, b.points, state.direction)
+    case "status":
+      return compareStatuses(a.status, b.status, state.direction)
+    case "priority":
+      return comparePriorities(a.priority, b.priority, state.direction)
+    case "type":
+      return compareTypes(a.kind ?? a.type, b.kind ?? b.type, state.direction)
+    case "people":
+      return comparePeople(a, b, state.direction)
+    default:
+      return 0
+  }
+}
+
+/** Stable sort: tie-break by original index. */
+export function sortRowsByTableSort<T extends SortableRowFields>(
+  rows: readonly T[],
+  state: TableSortState | null
+): T[] {
+  if (!state) return [...rows]
+  return rows
+    .map((row, index) => ({ row, index }))
+    .sort((a, b) => {
+      const cmp = compareSortableRows(a.row, b.row, state)
+      return cmp !== 0 ? cmp : a.index - b.index
+    })
+    .map(({ row }) => row)
+}
+
+/**
+ * Cycle sort for a column: none → asc → desc → none (default order).
+ * Switching to a different column always starts at asc.
+ */
+export function toggleTableSort(
+  current: TableSortState | null,
+  key: TableSortKey
+): TableSortState | null {
+  if (current?.key !== key) {
+    return { key, direction: "asc" }
+  }
+  if (current.direction === "asc") {
+    return { key, direction: "desc" }
+  }
+  return null
+}
+
+export function tableSortResetKey(state: TableSortState | null): string {
+  if (!state) return ""
+  return `${state.key}:${state.direction}`
+}

package/dist/standalone/dist/standalone/dist/standalone/dist/standalone/lib/taskmark/timeframe-filters.ts

@@ -0,0 +1,258 @@
+/** Timeframe filters for solved work items (`completed_at`). */
+
+import {
+  getISOWeek,
+  getISOWeekYear,
+  getISOWeeksInYear,
+  startOfDay,
+  endOfDay,
+  isWithinInterval,
+} from "date-fns"
+
+import { parseTaskmarkDate } from "@/lib/format-date"
+
+export type TimeframeFilterMode = "none" | "weeks" | "range"
+
+export type TimeframeFilterState =
+  | { mode: "none" }
+  | {
+      mode: "weeks"
+      year: number
+      weekFrom: number
+      weekTo: number
+    }
+  | {
+      mode: "range"
+      /** YYYY-MM-DD */
+      from: string
+      /** YYYY-MM-DD */
+      to: string
+    }
+
+export const DEFAULT_TIMEFRAME_FILTER: TimeframeFilterState = { mode: "none" }
+
+export function isTimeframeActive(tf: TimeframeFilterState): boolean {
+  return tf.mode !== "none"
+}
+
+export function timeframeResetKey(tf: TimeframeFilterState): string {
+  if (tf.mode === "none") return "none"
+  if (tf.mode === "weeks") {
+    return `w:${tf.year}:${tf.weekFrom}-${tf.weekTo}`
+  }
+  return `r:${tf.from}:${tf.to}`
+}
+
+/** Calendar date as YYYY-MM-DD (local). */
+export function toDateOnlyString(date: Date): string {
+  const y = date.getFullYear()
+  const m = String(date.getMonth() + 1).padStart(2, "0")
+  const d = String(date.getDate()).padStart(2, "0")
+  return `${y}-${m}-${d}`
+}
+
+export function isoWeekParts(date: Date): { year: number; week: number } {
+  return { year: getISOWeekYear(date), week: getISOWeek(date) }
+}
+
+/** Shift an ISO week by `delta` weeks (negative = earlier). Handles year bounds. */
+export function shiftIsoWeek(
+  year: number,
+  week: number,
+  delta: number
+): { year: number; week: number } {
+  let y = year
+  let w = week + delta
+  while (w < 1) {
+    y -= 1
+    w += weeksInIsoYear(y)
+  }
+  while (w > weeksInIsoYear(y)) {
+    w -= weeksInIsoYear(y)
+    y += 1
+  }
+  return { year: y, week: w }
+}
+
+export function weeksInIsoYear(year: number): number {
+  // 28 Dec is always in the last ISO week of that ISO year
+  return getISOWeeksInYear(new Date(year, 11, 28))
+}
+
+export type YearWeekBounds = {
+  years: number[]
+  /** min/max ISO week observed per ISO week-year (from data). */
+  weeksByYear: Record<number, { min: number; max: number }>
+}
+
+/** Collect ISO years and week bounds from completed_at values. */
+export function deriveYearWeekBounds(
+  completedAts: readonly (string | null | undefined)[]
+): YearWeekBounds {
+  const weeksByYear: Record<number, { min: number; max: number }> = {}
+  for (const raw of completedAts) {
+    const date = parseTaskmarkDate(raw)
+    if (!date) continue
+    const { year, week } = isoWeekParts(date)
+    const cur = weeksByYear[year]
+    if (!cur) {
+      weeksByYear[year] = { min: week, max: week }
+    } else {
+      cur.min = Math.min(cur.min, week)
+      cur.max = Math.max(cur.max, week)
+    }
+  }
+  const years = Object.keys(weeksByYear)
+    .map(Number)
+    .sort((a, b) => a - b)
+  return { years, weeksByYear }
+}
+
+export function defaultWeekRangeForYear(
+  year: number,
+  bounds: YearWeekBounds
+): { weekFrom: number; weekTo: number } {
+  const observed = bounds.weeksByYear[year]
+  if (observed) return { weekFrom: observed.min, weekTo: observed.max }
+  return { weekFrom: 1, weekTo: weeksInIsoYear(year) }
+}
+
+/**
+ * Default slider range: current ISO week and the two weeks before it
+ * (three weeks total), clamped within the current ISO week-year.
+ */
+export function recentWeekRange(
+  now: Date = new Date()
+): { year: number; weekFrom: number; weekTo: number } {
+  const { year, week } = isoWeekParts(now)
+  return {
+    year,
+    weekFrom: Math.max(1, week - 2),
+    weekTo: week,
+  }
+}
+
+/** True when weeks filter spans more than one week (slider UI). */
+export function isWeekRangeSelection(
+  timeframe: TimeframeFilterState
+): boolean {
+  if (timeframe.mode !== "weeks") return false
+  return timeframe.weekFrom !== timeframe.weekTo
+}
+
+/** Map key for ISO week counts: `2026-W30`. */
+export function isoWeekCountKey(year: number, week: number): string {
+  return `${year}-W${week}`
+}
+
+/** Solved item with optional story points (stories + epic-direct leaves). */
+export type SolvedCompletionSample = {
+  completedAt: string | null | undefined
+  points?: number | null
+}
+
+/**
+ * Count solved items per ISO week (stories + epic-direct tasks/bugs).
+ * Items without a parseable completed_at are skipped.
+ */
+export function countCompletionsByIsoWeek(
+  completedAts: readonly (string | null | undefined)[]
+): Map<string, number> {
+  const counts = new Map<string, number>()
+  for (const raw of completedAts) {
+    const date = parseTaskmarkDate(raw)
+    if (!date) continue
+    const { year, week } = isoWeekParts(date)
+    const key = isoWeekCountKey(year, week)
+    counts.set(key, (counts.get(key) ?? 0) + 1)
+  }
+  return counts
+}
+
+/**
+ * Count solved items per local calendar day (`YYYY-MM-DD`).
+ */
+export function countCompletionsByDate(
+  completedAts: readonly (string | null | undefined)[]
+): Map<string, number> {
+  const counts = new Map<string, number>()
+  for (const raw of completedAts) {
+    const date = parseTaskmarkDate(raw)
+    if (!date) continue
+    const key = toDateOnlyString(date)
+    counts.set(key, (counts.get(key) ?? 0) + 1)
+  }
+  return counts
+}
+
+function samplePoints(points: number | null | undefined): number {
+  return typeof points === "number" && Number.isFinite(points) && points > 0
+    ? points
+    : 0
+}
+
+/**
+ * Sum story points of solved items per ISO week.
+ */
+export function sumPointsByIsoWeek(
+  samples: readonly SolvedCompletionSample[]
+): Map<string, number> {
+  const totals = new Map<string, number>()
+  for (const sample of samples) {
+    const date = parseTaskmarkDate(sample.completedAt)
+    if (!date) continue
+    const pts = samplePoints(sample.points)
+    if (pts <= 0) continue
+    const { year, week } = isoWeekParts(date)
+    const key = isoWeekCountKey(year, week)
+    totals.set(key, (totals.get(key) ?? 0) + pts)
+  }
+  return totals
+}
+
+/**
+ * Sum story points of solved items per local calendar day (`YYYY-MM-DD`).
+ */
+export function sumPointsByDate(
+  samples: readonly SolvedCompletionSample[]
+): Map<string, number> {
+  const totals = new Map<string, number>()
+  for (const sample of samples) {
+    const date = parseTaskmarkDate(sample.completedAt)
+    if (!date) continue
+    const pts = samplePoints(sample.points)
+    if (pts <= 0) continue
+    const key = toDateOnlyString(date)
+    totals.set(key, (totals.get(key) ?? 0) + pts)
+  }
+  return totals
+}
+
+/**
+ * When a timeframe is active, rows without completed_at never match.
+ * Weeks: ISO-8601 week-year + week in [weekFrom, weekTo].
+ * Range: calendar day of completed_at within inclusive [from, to].
+ */
+export function passesTimeframeFilter(
+  timeframe: TimeframeFilterState,
+  completedAt: string | null | undefined
+): boolean {
+  if (timeframe.mode === "none") return true
+  const date = parseTaskmarkDate(completedAt)
+  if (!date) return false
+
+  if (timeframe.mode === "weeks") {
+    const { year, week } = isoWeekParts(date)
+    if (year !== timeframe.year) return false
+    const from = Math.min(timeframe.weekFrom, timeframe.weekTo)
+    const to = Math.max(timeframe.weekFrom, timeframe.weekTo)
+    return week >= from && week <= to
+  }
+
+  const fromDate = parseTaskmarkDate(timeframe.from)
+  const toDate = parseTaskmarkDate(timeframe.to)
+  if (!fromDate || !toDate) return false
+  const start = startOfDay(fromDate <= toDate ? fromDate : toDate)
+  const end = endOfDay(fromDate <= toDate ? toDate : fromDate)
+  return isWithinInterval(date, { start, end })
+}

package/dist/standalone/dist/standalone/dist/standalone/dist/standalone/lib/taskmark/timing.ts

@@ -0,0 +1,32 @@
+import {
+  asNumberOrNull,
+} from "@/lib/taskmark/frontmatter"
+
+export type TimingFields = {
+  estimateMinutes: number | null
+  /** Billable work-log minutes (floor of actual_ms / 60000). */
+  actualMinutes: number | null
+  /** Precise billable work-log duration in milliseconds. */
+  actualMs: number | null
+}
+
+/**
+ * Read estimate and actual from board frontmatter.
+ * Est = optional/historical planned minutes (sizing no longer suggests time).
+ * Actual = session time spent (prefers actual_ms; falls back to minutes / effort).
+ */
+export function readTimingFields(
+  frontmatter: Record<string, unknown>
+): TimingFields {
+  const actualMinutes =
+    asNumberOrNull(frontmatter.actual_minutes) ??
+    asNumberOrNull(frontmatter.effort_minutes)
+  const actualMs =
+    asNumberOrNull(frontmatter.actual_ms) ??
+    (actualMinutes != null ? actualMinutes * 60_000 : null)
+  return {
+    estimateMinutes: asNumberOrNull(frontmatter.estimate_minutes),
+    actualMinutes,
+    actualMs,
+  }
+}

package/dist/standalone/dist/standalone/dist/standalone/dist/standalone/lib/taskmark/types.ts

@@ -0,0 +1,28 @@
+export type DiscoveredProject = {
+  /** Stable id — realpath of boardPath */
+  id: string
+  /** Display name */
+  name: string
+  /**
+   * Absolute path to the project root:
+   * parent of nested `taskmark/`, or the dedicated `*-taskmark` folder itself.
+   */
+  projectPath: string
+  /**
+   * Absolute path to the board directory:
+   * `<project>/taskmark` (single) or `<name>-taskmark` root (multi).
+   */
+  boardPath: string
+}
+
+export type ValidateMasterFolderResult =
+  | {
+      ok: true
+      masterPath: string
+      projects: DiscoveredProject[]
+    }
+  | {
+      ok: false
+      error: string
+      code: "empty" | "not_found" | "not_directory" | "unreadable" | "no_projects"
+    }