@baack-software/baack-ts-tasks 0.0.0-stage → 0.0.1

package/dist/time.js

@@ -0,0 +1,34 @@
+/**
+ * Baack timestamps are ISO 8601 in UTC without a zone, for example `2025-09-13T17:08:00` or `2025-09-13T17:08:00.000`.
+ * A plain `new Date(timestamp)` would read them as local time, so use these helpers instead.
+ */
+const HAS_ZONE = /(?:Z|[+-]\d{2}:?\d{2})$/i;
+/** Reads a Baack timestamp as a `Date`, or undefined when it is empty or not a valid timestamp. */
+export function parseTimestamp(timestamp) {
+    if (!timestamp)
+        return undefined;
+    const date = new Date(HAS_ZONE.test(timestamp) ? timestamp : timestamp + 'Z');
+    return Number.isNaN(date.getTime()) ? undefined : date;
+}
+/** Writes a `Date` as a Baack timestamp: UTC, with milliseconds, without a zone. */
+export function toTimestamp(date) {
+    return date.toISOString().replace(/Z$/, '');
+}
+/**
+ * The value for an `<input type="datetime-local">` showing a Baack timestamp in the viewer's local time, or `''`.
+ */
+export function toLocalInput(timestamp) {
+    const date = parseTimestamp(timestamp);
+    if (!date)
+        return '';
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+/** Reads an `<input type="datetime-local">` value (local time) as a Baack timestamp, or undefined when empty. */
+export function fromLocalInput(value) {
+    if (!value)
+        return undefined;
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? undefined : toTimestamp(date);
+}
+//# sourceMappingURL=time.js.map

package/dist/time.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.js","sourceRoot":"","sources":["../src/time.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,QAAQ,GAAG,0BAA0B,CAAC;AAE5C,mGAAmG;AACnG,MAAM,UAAU,cAAc,CAAC,SAAoC;IACjE,IAAI,CAAC,SAAS;QAAE,OAAO,SAAS,CAAC;IACjC,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC;IAC9E,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC;AACzD,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,WAAW,CAAC,IAAU;IACpC,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,SAAoC;IAC/D,MAAM,IAAI,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;IACvC,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IACrB,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACtD,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC;AACtI,CAAC;AAED,iHAAiH;AACjH,MAAM,UAAU,cAAc,CAAC,KAAgC;IAC7D,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC;IAC7B,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;AACtE,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,74 @@
+import type { Pagination, TaskActivity, TaskLog, TaskPriority, TaskStatus } from '@baack-software/baack-ts-client';
+/**
+ * A reference to another representation by URN. The API resolves references by `urn`, so this is all a request needs,
+ * unlike the client's read types (for example `Identity` requires `owner`).
+ */
+export interface Ref {
+    urn: string;
+    url?: string | null;
+}
+/** A URN, or anything carrying one, such as a task or identity read from the API. */
+export type RefLike = string | Ref;
+/**
+ * Task log activities, with both spellings of completed: earlier versions of baack-ts-client's `TaskActivity` have only
+ * `STATUS_COMPL_ETED`, later ones only `STATUS_COMPLETED`.
+ */
+export type Activity = TaskActivity | 'STATUS_COMPLETED' | 'STATUS_COMPL_ETED';
+/**
+ * Task fields to create or change. The API stores what an update sends, so `TaskClient.update` sends these changes on
+ * top of the whole task (see `updateBody`). Lists are sent whole: the server compares them with the current lists and
+ * logs each addition and removal.
+ */
+export interface TaskInput {
+    owner?: Ref;
+    /** `null` unsets. */
+    assignee?: Ref | null;
+    /** `null` unsets. */
+    project?: Ref | null;
+    /** `null` unsets. */
+    workflowStage?: Ref | null;
+    status?: TaskStatus;
+    priority?: TaskPriority;
+    title?: string;
+    description?: string;
+    /** ISO 8601 in UTC without a zone, see `toTimestamp`. `null` unsets. */
+    dueTimestamp?: string | null;
+    blockedBy?: Ref[];
+    blocking?: Ref[];
+    associatedTasks?: Ref[];
+    associatedEntities?: Ref[];
+    associatedIdentities?: Ref[];
+    associatedCompanies?: Ref[];
+    /** Attributes the change in the activity log without assigning the task. */
+    identityForLogs?: Ref;
+}
+/** A new task, with the fields the API requires on create. Build one with `draft`. */
+export interface TaskDraft extends TaskInput {
+    owner: Ref;
+    status: TaskStatus;
+    priority: TaskPriority;
+    title: string;
+    description: string;
+    blockedBy: Ref[];
+    blocking: Ref[];
+    associatedTasks: Ref[];
+    associatedEntities: Ref[];
+    associatedIdentities: Ref[];
+    associatedCompanies: Ref[];
+}
+/**
+ * The body of a task update: the whole task as it should be stored. The server requires `urn`, `owner`, `status`,
+ * `priority`, `title` and `description`, and clears any optional field left out. Build one with `updateBody`.
+ */
+export interface TaskUpdate extends TaskDraft {
+    urn: string;
+}
+/** One page of a task's activity log, newest first. */
+export interface TaskLogPage {
+    logs: TaskLog[];
+    pagination?: Pagination | null;
+}
+/** The fields of a task that hold lists of references. */
+export type TaskListField = 'blockedBy' | 'blocking' | 'associatedTasks' | 'associatedEntities' | 'associatedIdentities' | 'associatedCompanies';
+export declare const TASK_LIST_FIELDS: readonly TaskListField[];
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EACZ,OAAO,EACP,YAAY,EACZ,UAAU,EACX,MAAM,iCAAiC,CAAC;AAEzC;;;GAGG;AACH,MAAM,WAAW,GAAG;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,qFAAqF;AACrF,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,GAAG,CAAC;AAEnC;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,YAAY,GAAG,kBAAkB,GAAG,mBAAmB,CAAC;AAE/E;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,EAAE,GAAG,CAAC;IACZ,qBAAqB;IACrB,QAAQ,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;IACtB,qBAAqB;IACrB,OAAO,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;IACrB,qBAAqB;IACrB,aAAa,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;IAC3B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,SAAS,CAAC,EAAE,GAAG,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,GAAG,EAAE,CAAC;IACjB,eAAe,CAAC,EAAE,GAAG,EAAE,CAAC;IACxB,kBAAkB,CAAC,EAAE,GAAG,EAAE,CAAC;IAC3B,oBAAoB,CAAC,EAAE,GAAG,EAAE,CAAC;IAC7B,mBAAmB,CAAC,EAAE,GAAG,EAAE,CAAC;IAC5B,4EAA4E;IAC5E,eAAe,CAAC,EAAE,GAAG,CAAC;CACvB;AAED,sFAAsF;AACtF,MAAM,WAAW,SAAU,SAAQ,SAAS;IAC1C,KAAK,EAAE,GAAG,CAAC;IACX,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,YAAY,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,GAAG,EAAE,CAAC;IACjB,QAAQ,EAAE,GAAG,EAAE,CAAC;IAChB,eAAe,EAAE,GAAG,EAAE,CAAC;IACvB,kBAAkB,EAAE,GAAG,EAAE,CAAC;IAC1B,oBAAoB,EAAE,GAAG,EAAE,CAAC;IAC5B,mBAAmB,EAAE,GAAG,EAAE,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,UAAW,SAAQ,SAAS;IAC3C,GAAG,EAAE,MAAM,CAAC;CACb;AAED,uDAAuD;AACvD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,UAAU,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;CAChC;AAED,0DAA0D;AAC1D,MAAM,MAAM,aAAa,GACrB,WAAW,GACX,UAAU,GACV,iBAAiB,GACjB,oBAAoB,GACpB,sBAAsB,GACtB,qBAAqB,CAAC;AAE1B,eAAO,MAAM,gBAAgB,EAAE,SAAS,aAAa,EAOpD,CAAC"}

package/dist/types.js

@@ -0,0 +1,9 @@
+export const TASK_LIST_FIELDS = [
+    'blockedBy',
+    'blocking',
+    'associatedTasks',
+    'associatedEntities',
+    'associatedIdentities',
+    'associatedCompanies',
+];
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA6FA,MAAM,CAAC,MAAM,gBAAgB,GAA6B;IACxD,WAAW;IACX,UAAU;IACV,iBAAiB;IACjB,oBAAoB;IACpB,sBAAsB;IACtB,qBAAqB;CACtB,CAAC"}

package/package.json

@@ -1,6 +1,103 @@
 {
   "name": "@baack-software/baack-ts-tasks",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "TypeScript tools for Baack tasks: typed task API, helpers, a task store and shadcn/ui task components",
+  "keywords": [
+    "Baack",
+    "tasks",
+    "projects",
+    "workflow"
+  ],
+  "homepage": "https://github.com/Baack-Software/baack-ts-tasks#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Baack-Software/baack-ts-tasks.git"
+  },
+  "license": "Apache-2.0",
+  "author": "baack-dakkad",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./store": {
+      "types": "./dist/store.d.ts",
+      "import": "./dist/store.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "demo": "vite --config demo/vite.config.ts",
+    "demo:build": "vite build --config demo/vite.config.ts --outDir ../demo-dist --emptyOutDir",
+    "check:api": "node --env-file-if-exists=.env scripts/check-api.ts",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "peerDependencies": {
+    "@baack-software/baack-ts-client": ">=0.0.2",
+    "@baack-software/baack-ts-components": ">=0.0.1",
+    "react": ">=19",
+    "react-dom": ">=19"
+  },
+  "devDependencies": {
+    "@baack-software/baack-ts-client": "file:../baack-ts-client",
+    "@baack-software/baack-ts-components": "file:../baack-ts-components",
+    "@tailwindcss/vite": "^4.3.3",
+    "@testing-library/react": "^16.3.3",
+    "@testing-library/user-event": "^14.6.8",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.2",
+    "jsdom": "^30.1.2",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "shadcn": "^4.21.0",
+    "tailwindcss": "^4.3.3",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "^5.0.0",
+    "vite": "^8.3.4",
+    "vitest": "^5.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "class-variance-authority": "^0.7.1",
+    "cn": "^0.5.0",
+    "lucide-react": "^1.56.0",
+    "radix-ui": "^1.8.1"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "@baack-software/baack-ts-components": {
+      "optional": true
+    }
+  }
+}

package/src/activity.ts

@@ -0,0 +1,86 @@
+import type { TaskLog } from '@baack-software/baack-ts-client';
+import type { Activity } from './types.ts';
+
+/** What happened, as a short sentence without the subject, e.g. "Status set to In progress". */
+export const ACTIVITY_LABELS: Readonly<Record<Activity, string>> = {
+  CREATED: 'Created',
+  STATUS_UNDEFINED: 'Status set to Undefined',
+  STATUS_PENDING: 'Status set to Pending',
+  STATUS_IN_PROGRESS: 'Status set to In progress',
+  STATUS_BLOCKED: 'Status set to Blocked',
+  STATUS_COMPLETED: 'Status set to Completed',
+  STATUS_COMPL_ETED: 'Status set to Completed',
+  STATUS_CLOSED: 'Status set to Closed',
+  PRIORITY_NONE: 'Priority set to None',
+  PRIORITY_LOW: 'Priority set to Low',
+  PRIORITY_MEDIUM: 'Priority set to Medium',
+  PRIORITY_HIGH: 'Priority set to High',
+  PRIORITY_CRITICAL: 'Priority set to Critical',
+  WORKFLOW_STAGE_SET: 'Moved to a workflow stage',
+  WORKFLOW_STAGE_UNSET: 'Removed from its workflow stage',
+  COMMENT_ADDED: 'Commented',
+  WORK_TASK_ASSOCIATION_ADDED: 'Related task added',
+  WORK_TASK_ASSOCIATION_REMOVED: 'Related task removed',
+  WORK_TASK_BLOCKER_ADDED: 'Blocker added',
+  WORK_TASK_BLOCKER_REMOVED: 'Blocker removed',
+  WORK_TASK_BLOCKING_ADDED: 'Now blocking a task',
+  WORK_TASK_BLOCKING_REMOVED: 'No longer blocking a task',
+  WORK_TASK_ENTITY_ADDED: 'Content added',
+  WORK_TASK_ENTITY_REMOVED: 'Content removed',
+  WORK_TASK_IDENTITY_ADDED: 'Person added',
+  WORK_TASK_IDENTITY_REMOVED: 'Person removed',
+  WORK_TASK_COMPANY_ADDED: 'Company added',
+  WORK_TASK_COMPANY_REMOVED: 'Company removed',
+  WORK_PROJECT_SET: 'Added to a project',
+  WORK_PROJECT_UNSET: 'Removed from its project',
+  ASSIGNED: 'Assigned',
+  UNASSIGNED: 'Unassigned',
+  TITLE_UPDATED: 'Title changed',
+  DESCRIPTION_UPDATED: 'Description changed',
+  DUE_DATE_UPDATED: 'Due date changed',
+  DUE_DATE_UNSET: 'Due date removed',
+};
+
+/** A readable label for an activity, falling back to the raw value in lower case for activities added later. */
+export function activityLabel(activity: string): string {
+  return (ACTIVITY_LABELS as Record<string, string>)[activity] ?? activity.toLowerCase().replaceAll('_', ' ');
+}
+
+/** Whether the log entry is a comment rather than a recorded change. */
+export function isComment(log: Pick<TaskLog, 'activity'>): boolean {
+  return log.activity === 'COMMENT_ADDED';
+}
+
+/** A comment and the replies to it, oldest reply first. */
+export interface CommentThread {
+  comment: TaskLog;
+  replies: TaskLog[];
+}
+
+/**
+ * Groups comments into threads by `replyTo`, most recently active thread first. Expects `logs` newest first, as the
+ * API returns them.
+ * A reply whose parent is not in `logs` (for example on an older page) starts its own thread.
+ */
+export function commentThreads(logs: readonly TaskLog[]): CommentThread[] {
+  const comments = logs.filter(isComment);
+  const byUrn = new Map(comments.map((log) => [log.urn, log]));
+  const rootOf = (log: TaskLog): TaskLog => {
+    const seen = new Set<string>();
+    let current = log;
+    while (current.replyTo && byUrn.has(current.replyTo.urn) && !seen.has(current.urn)) {
+      seen.add(current.urn);
+      current = byUrn.get(current.replyTo.urn)!;
+    }
+    return current;
+  };
+
+  const threads = new Map<string, CommentThread>();
+  for (const log of comments) {
+    const root = rootOf(log);
+    const thread = threads.get(root.urn) ?? { comment: root, replies: [] };
+    if (root !== log) thread.replies.unshift(log);
+    threads.set(root.urn, thread);
+  }
+  return [...threads.values()];
+}

package/src/blockers.ts

@@ -0,0 +1,134 @@
+import type { Task } from '@baack-software/baack-ts-client';
+import { urnOf } from './refs.ts';
+import { isOpen } from './tasks.ts';
+import type { RefLike } from './types.ts';
+
+/** Finds a task by URN, for example from a store or a `Map`. */
+export type TaskLookup = (urn: string) => Task | undefined;
+
+/** A lookup over a list of tasks. */
+export function lookupFrom(tasks: Iterable<Task>): TaskLookup {
+  const byUrn = new Map<string, Task>();
+  for (const task of tasks) byUrn.set(task.urn, task);
+  return (urn) => byUrn.get(urn);
+}
+
+/**
+ * The URNs of the tasks blocking `task` that are still open. A blocker the lookup doesn't know counts as open, since
+ * the task may be blocked by work the reader can't see.
+ */
+export function openBlockers(task: Task, lookup: TaskLookup): string[] {
+  return (task.blockedBy ?? [])
+    .map((blocker) => blocker.urn)
+    .filter((urn) => {
+      const blocker = lookup(urn);
+      return blocker === undefined || isOpen(blocker);
+    });
+}
+
+/** Whether every task blocking `task` is done, so work can start. */
+export function isUnblocked(task: Task, lookup: TaskLookup): boolean {
+  return openBlockers(task, lookup).length === 0;
+}
+
+/**
+ * Blocking edges among `tasks`, from each task to the tasks it blocks. Reads both `blocking` and `blockedBy`, so an
+ * edge recorded on only one side still counts.
+ */
+export function blockingGraph(tasks: Iterable<Task>): Map<string, Set<string>> {
+  const graph = new Map<string, Set<string>>();
+  const edge = (from: string, to: string) => {
+    const targets = graph.get(from) ?? new Set<string>();
+    targets.add(to);
+    graph.set(from, targets);
+  };
+  for (const task of tasks) {
+    if (!graph.has(task.urn)) graph.set(task.urn, new Set());
+    for (const blocked of task.blocking ?? []) edge(task.urn, blocked.urn);
+    for (const blocker of task.blockedBy ?? []) edge(blocker.urn, task.urn);
+  }
+  return graph;
+}
+
+/** A cycle of blocking tasks as a list of URNs (the first task blocks the second, and so on, back to the first), or undefined. */
+export function findBlockingCycle(tasks: Iterable<Task>): string[] | undefined {
+  const graph = blockingGraph(tasks);
+  const state = new Map<string, 'visiting' | 'done'>();
+  const path: string[] = [];
+
+  const visit = (urn: string): string[] | undefined => {
+    state.set(urn, 'visiting');
+    path.push(urn);
+    for (const next of graph.get(urn) ?? []) {
+      const seen = state.get(next);
+      if (seen === 'visiting') return path.slice(path.indexOf(next));
+      if (seen === undefined) {
+        const cycle = visit(next);
+        if (cycle) return cycle;
+      }
+    }
+    path.pop();
+    state.set(urn, 'done');
+    return undefined;
+  };
+
+  for (const urn of graph.keys()) {
+    if (state.get(urn) === undefined) {
+      const cycle = visit(urn);
+      if (cycle) return cycle;
+    }
+  }
+  return undefined;
+}
+
+/** Whether making `blocker` block `task` would create a cycle, given the current `tasks`. */
+export function wouldCreateCycle(tasks: Iterable<Task>, task: RefLike, blocker: RefLike): boolean {
+  const from = urnOf(blocker);
+  const to = urnOf(task);
+  if (from === to) return true;
+  // A cycle appears when the blocker is already reachable from the task it would block.
+  const graph = blockingGraph(tasks);
+  const queue = [to];
+  const seen = new Set(queue);
+  for (let urn = queue.shift(); urn !== undefined; urn = queue.shift()) {
+    for (const next of graph.get(urn) ?? []) {
+      if (next === from) return true;
+      if (!seen.has(next)) {
+        seen.add(next);
+        queue.push(next);
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Tasks in an order where each comes after the tasks blocking it, keeping the given order otherwise. Tasks in a
+ * cycle are placed at the end in their given order.
+ */
+export function dependencyOrder(tasks: readonly Task[]): Task[] {
+  const known = new Set(tasks.map((task) => task.urn));
+  const graph = blockingGraph(tasks);
+  const waiting = new Map<string, number>(tasks.map((task) => [task.urn, 0]));
+  for (const [from, targets] of graph) {
+    if (!known.has(from)) continue;
+    for (const to of targets) if (known.has(to)) waiting.set(to, (waiting.get(to) ?? 0) + 1);
+  }
+
+  const ordered: Task[] = [];
+  const placed = new Set<string>();
+  let progress = true;
+  while (progress) {
+    progress = false;
+    for (const task of tasks) {
+      if (placed.has(task.urn) || waiting.get(task.urn) !== 0) continue;
+      ordered.push(task);
+      placed.add(task.urn);
+      progress = true;
+      for (const to of graph.get(task.urn) ?? []) {
+        if (known.has(to)) waiting.set(to, (waiting.get(to) ?? 0) - 1);
+      }
+    }
+  }
+  return [...ordered, ...tasks.filter((task) => !placed.has(task.urn))];
+}

package/src/conflicts.ts

@@ -0,0 +1,115 @@
+import type { Task } from '@baack-software/baack-ts-client';
+import { refs, sameRef, sameRefs, urnOf } from './refs.ts';
+import { parseTimestamp } from './time.ts';
+import { TASK_LIST_FIELDS, type Ref, type TaskInput, type TaskListField } from './types.ts';
+
+/**
+ * Finding and resolving conflicting edits.
+ *
+ * An editor shows a task (the base), the person changes some fields, and by the time the change is sent someone else
+ * may have changed the task too. Fields only the other person changed are kept, since an update applies only this
+ * person's changes on top of the task as it is now. A field both changed is a conflict, which the person resolves by
+ * keeping their value or using the other one. Lists never conflict: their changes are applied as additions and
+ * removals.
+ */
+
+/** The task fields that hold one value, which can conflict. */
+export type TaskField =
+  | 'title'
+  | 'description'
+  | 'status'
+  | 'priority'
+  | 'dueTimestamp'
+  | 'assignee'
+  | 'project'
+  | 'workflowStage';
+
+export const TASK_FIELDS: readonly TaskField[] = [
+  'title',
+  'description',
+  'status',
+  'priority',
+  'dueTimestamp',
+  'assignee',
+  'project',
+  'workflowStage',
+];
+
+/** A field's value: text, a timestamp, or a reference. Absent and empty values are the same. */
+export type TaskFieldValue = string | Ref | null | undefined;
+
+/** A field this person and someone else both changed since the base. */
+export interface TaskConflict {
+  field: TaskField;
+  /** The value when this person started editing. */
+  base: TaskFieldValue;
+  /** The value someone else saved since. */
+  theirs: TaskFieldValue;
+  /** The value this person is saving. */
+  mine: TaskFieldValue;
+}
+
+/** Which value to keep for each conflicting field. */
+export type ConflictChoices = Partial<Record<TaskField, 'mine' | 'theirs'>>;
+
+/** Whether two values of a field are the same: references by URN, timestamps by instant, absent equal to empty. */
+export function sameValue(field: TaskField, a: TaskFieldValue, b: TaskFieldValue): boolean {
+  if (field === 'assignee' || field === 'project' || field === 'workflowStage') {
+    return sameRef(a as Ref | null | undefined, b as Ref | null | undefined);
+  }
+  if (field === 'dueTimestamp') {
+    return parseTimestamp(a as string | null | undefined)?.getTime() === parseTimestamp(b as string | null | undefined)?.getTime();
+  }
+  return ((a as string | null | undefined) ?? '') === ((b as string | null | undefined) ?? '');
+}
+
+/** The fields that differ between two versions of a task, single values first, then lists. */
+export function changedFields(before: Task, after: Task): (TaskField | TaskListField)[] {
+  return [
+    ...TASK_FIELDS.filter((field) => !sameValue(field, before[field], after[field])),
+    ...TASK_LIST_FIELDS.filter((field) => !sameRefs(before[field], after[field])),
+  ];
+}
+
+/** The single-value fields `changes` sets. */
+export function fieldsChanged(changes: TaskInput): TaskField[] {
+  return TASK_FIELDS.filter((field) => changes[field] !== undefined);
+}
+
+/**
+ * The fields `changes` sets that someone else also changed between `base` and `theirs`, to a different value.
+ * Empty when the change can be saved as it is.
+ */
+export function findConflicts(base: Task, theirs: Task, changes: TaskInput): TaskConflict[] {
+  return fieldsChanged(changes)
+    .filter((field) => !sameValue(field, base[field], theirs[field]) && !sameValue(field, theirs[field], changes[field]))
+    .map((field) => ({ field, base: base[field], theirs: theirs[field], mine: changes[field] }));
+}
+
+/**
+ * `changes` with the choices applied: a field resolved to theirs is dropped, so the other person's value stays. Fields
+ * without a choice keep this person's value.
+ */
+export function resolveConflicts(changes: TaskInput, choices: ConflictChoices): TaskInput {
+  const result: TaskInput = { ...changes };
+  for (const field of TASK_FIELDS) if (choices[field] === 'theirs') delete result[field];
+  return result;
+}
+
+/**
+ * List changes made against `base`, replayed on `theirs` as additions and removals, so items someone else added or
+ * removed since are kept. Other fields are unchanged.
+ */
+export function rebaseLists(base: Task, theirs: Task, changes: TaskInput): TaskInput {
+  const result: TaskInput = { ...changes };
+  for (const field of TASK_LIST_FIELDS) {
+    const mine = changes[field];
+    if (mine === undefined) continue;
+    const before = new Set((base[field] ?? []).map(urnOf));
+    const after = new Set(mine.map(urnOf));
+    const removed = new Set([...before].filter((urn) => !after.has(urn)));
+    const added = mine.filter((item) => !before.has(urnOf(item)));
+    result[field] = refs([...(theirs[field] ?? []).filter((item) => !removed.has(urnOf(item))), ...added]);
+  }
+  return result;
+}