feat: an ordered backlog

A Backlog tab lists the tickets still to start in the order the team will
take them; drag them, or use the arrows, to reorder. Moving a ticket only
rewrites that ticket's rank, read from the event store, and board columns
follow the same order.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

libs/web/tracker/application/src/index.ts

@@ -7,3 +7,4 @@ export * from './lib/facades/home.facade';
 export * from './lib/facades/explore.facade';
 export * from './lib/facades/inbox.facade';
 export * from './lib/facades/epics.facade';
+export * from './lib/facades/backlog.facade';

libs/web/tracker/application/src/lib/events/backlog.events.ts

@@ -0,0 +1,22 @@
+import { type } from '@ngrx/signals';
+import { eventGroup } from '@ngrx/signals/events';
+import { IssuePage } from '@task-stream/web/tracker/domain';
+
+export const backlogPageEvents = eventGroup({
+  source: 'Backlog Page',
+  events: {
+    opened: type<{ projectId: string }>(),
+    /** Put the ticket at `index` of the backlog as shown now. */
+    moveRequested: type<{ issueId: string; index: number }>(),
+  },
+});
+
+export const backlogApiEvents = eventGroup({
+  source: 'Backlog API',
+  events: {
+    loaded: type<IssuePage>(),
+    loadFailed: type<string>(),
+    moved: type<void>(),
+    moveFailed: type<string>(),
+  },
+});

libs/web/tracker/application/src/lib/facades/backlog.facade.ts

@@ -0,0 +1,32 @@
+import { inject, Injectable, Provider } from '@angular/core';
+import { injectDispatch } from '@ngrx/signals/events';
+import { backlogPageEvents } from '../events/backlog.events';
+import { BacklogStore } from '../stores/backlog.store';
+
+/** "Backlog": tickets still to start, in the order the team will take them. */
+@Injectable()
+export class BacklogFacade {
+  private readonly store = inject(BacklogStore);
+  private readonly dispatch = injectDispatch(backlogPageEvents);
+
+  /** In backlog order (the first 200). */
+  readonly issues = this.store.issues;
+  readonly total = this.store.total;
+  /** False until the first load: show skeletons, not empty states. */
+  readonly loaded = this.store.loaded;
+  readonly error = this.store.error;
+
+  open(projectId: string): void {
+    this.dispatch.opened({ projectId });
+  }
+
+  /** Puts the ticket at `index` of the list as shown now. */
+  move(issueId: string, index: number): void {
+    this.dispatch.moveRequested({ issueId, index });
+  }
+}
+
+/** Store + facade of the backlog view, for its route component. */
+export function provideBacklogFacade(): Provider[] {
+  return [BacklogStore, BacklogFacade];
+}

libs/web/tracker/application/src/lib/stores/backlog.reducers.spec.ts

@@ -0,0 +1,25 @@
+import { IssueSummary } from '@task-stream/web/tracker/domain';
+import { reorder } from './backlog.reducers';
+
+const list = ['a', 'b', 'c', 'd'].map((id) => ({ id }) as IssueSummary);
+const ids = (issues: IssueSummary[] | undefined) => issues?.map((i) => i.id);
+
+describe('backlog reorder', () => {
+  it('moves a ticket and tells who ends up around it', () => {
+    const down = reorder(list, 'a', 2);
+    expect(ids(down?.issues)).toEqual(['b', 'c', 'a', 'd']);
+    expect([down?.above?.id, down?.below?.id]).toEqual(['c', 'd']);
+
+    const top = reorder(list, 'd', 0);
+    expect(ids(top?.issues)).toEqual(['d', 'a', 'b', 'c']);
+    expect([top?.above, top?.below?.id]).toEqual([null, 'a']);
+
+    const bottom = reorder(list, 'b', 99);
+    expect([bottom?.above?.id, bottom?.below]).toEqual(['d', null]);
+  });
+
+  it('does nothing when it stays where it was', () => {
+    expect(reorder(list, 'b', 1)).toBeNull();
+    expect(reorder(list, 'zz', 0)).toBeNull();
+  });
+});

libs/web/tracker/application/src/lib/stores/backlog.reducers.ts

@@ -0,0 +1,23 @@
+import { IssueSummary } from '@task-stream/web/tracker/domain';
+
+/** Where a ticket lands when moved to `index`, and its new neighbours. */
+export function reorder(
+  issues: IssueSummary[],
+  issueId: string,
+  index: number,
+): {
+  issues: IssueSummary[];
+  above: IssueSummary | null;
+  below: IssueSummary | null;
+} | null {
+  const from = issues.findIndex((i) => i.id === issueId);
+  if (from === -1) return null;
+  const rest = issues.filter((i) => i.id !== issueId);
+  const at = Math.max(0, Math.min(index, rest.length));
+  if (at === from) return null;
+  return {
+    issues: [...rest.slice(0, at), issues[from], ...rest.slice(at)],
+    above: rest[at - 1] ?? null,
+    below: rest[at] ?? null,
+  };
+}

libs/web/tracker/application/src/lib/stores/backlog.store.ts

@@ -0,0 +1,120 @@
+import { inject } from '@angular/core';
+import { mapResponse } from '@ngrx/operators';
+import { patchState, signalStore, withState } from '@ngrx/signals';
+import {
+  Events,
+  on,
+  withEventHandlers,
+  withReducer,
+} from '@ngrx/signals/events';
+import {
+  IssuesGateway,
+  IssueSummary,
+  TrackerRealtimeGateway,
+} from '@task-stream/web/tracker/domain';
+import {
+  concatMap,
+  debounceTime,
+  EMPTY,
+  merge,
+  startWith,
+  switchMap,
+  tap,
+} from 'rxjs';
+import { backlogApiEvents, backlogPageEvents } from '../events/backlog.events';
+import { describeError, Notifications } from '../notifications';
+import { reorder } from './backlog.reducers';
+
+interface BacklogState {
+  projectId: string | null;
+  issues: IssueSummary[];
+  total: number;
+  loaded: boolean;
+  error: string | null;
+}
+
+/** Tickets still to start, in the order the team will take them. Live. */
+export const BacklogStore = signalStore(
+  withState<BacklogState>({
+    projectId: null,
+    issues: [],
+    total: 0,
+    loaded: false,
+    error: null,
+  }),
+  withReducer(
+    on(backlogPageEvents.opened, ({ payload }) => ({
+      projectId: payload.projectId,
+      loaded: false,
+      error: null,
+    })),
+    on(backlogApiEvents.loaded, ({ payload }) => ({
+      issues: payload.items,
+      total: payload.total,
+      loaded: true,
+    })),
+    on(backlogApiEvents.loadFailed, ({ payload }) => ({
+      loaded: true,
+      error: payload,
+    })),
+  ),
+  withEventHandlers(
+    (
+      store,
+      events = inject(Events),
+      issues = inject(IssuesGateway),
+      realtime = inject(TrackerRealtimeGateway),
+      notifications = inject(Notifications),
+    ) => {
+      const fetch = (projectId: string) =>
+        issues.backlog(projectId).pipe(
+          mapResponse({
+            next: (page) => backlogApiEvents.loaded(page),
+            error: (error) => backlogApiEvents.loadFailed(describeError(error)),
+          }),
+        );
+      return {
+        // Anyone's change may add, remove or move a ticket: reload, calmly.
+        load$: events.on(backlogPageEvents.opened).pipe(
+          switchMap(({ payload }) =>
+            merge(
+              realtime.issueChanges(payload.projectId).pipe(debounceTime(400)),
+              events.on(backlogApiEvents.moveFailed),
+            ).pipe(
+              startWith(null),
+              switchMap(() => fetch(payload.projectId)),
+            ),
+          ),
+        ),
+        // One move after another: each needs the ranks the previous left.
+        move$: events.on(backlogPageEvents.moveRequested).pipe(
+          concatMap(({ payload }) => {
+            const next = reorder(
+              store.issues(),
+              payload.issueId,
+              payload.index,
+            );
+            if (!next) return EMPTY;
+            patchState(store, { issues: next.issues });
+            return issues
+              .rank(
+                payload.issueId,
+                next.above?.id ?? null,
+                next.below?.id ?? null,
+              )
+              .pipe(
+                mapResponse({
+                  next: () => backlogApiEvents.moved(),
+                  error: (error) =>
+                    backlogApiEvents.moveFailed(describeError(error)),
+                }),
+              );
+          }),
+        ),
+        feedback$: events
+          .on(backlogApiEvents.moveFailed)
+          .pipe(tap(({ payload }) => notifications.error(payload))),
+      };
+    },
+  ),
+);

libs/web/tracker/application/src/lib/stores/board.reducers.spec.ts

@@ -19,6 +19,7 @@ const issue = (
     area: null,
     labels: [],
     commentCount: 0,
+    rank: `n-${id}`,
   }) as unknown as IssueSummary;
 
 const board = (): BoardColumn[] => [
@@ -57,8 +58,12 @@ describe('board reducers', () => {
     expect(next[0].issues).toEqual([]);
   });
 
-  it('adds new issues from other users', () => {
+  it('adds new issues from other users at their place in the backlog', () => {
     const next = applyIssueChange(board(), issue('b', 'TODO', 1), null);
-    expect(next[0].issues.map((i) => i.id)).toEqual(['b', 'a']);
+    expect(next[0].issues.map((i) => i.id)).toEqual(['a', 'b']);
+
+    const ranked = { ...issue('c', 'TODO', 1), rank: 'a' };
+    const top = applyIssueChange(next, ranked, null);
+    expect(top[0].issues.map((i) => i.id)).toEqual(['c', 'a', 'b']);
   });
 });

libs/web/tracker/application/src/lib/stores/board.reducers.ts

@@ -29,7 +29,18 @@ export function matchesFilter(
   return true;
 }
 
-/** Removes the issue wherever it is and puts `next` (if any) on top of its status column. */
+/** `issues` (in backlog order) with `issue` at its place by rank. */
+export function insertByRank(
+  issues: IssueSummary[],
+  issue: IssueSummary,
+): IssueSummary[] {
+  const at = issues.findIndex((i) => i.rank > issue.rank);
+  return at === -1
+    ? [...issues, issue]
+    : [...issues.slice(0, at), issue, ...issues.slice(at)];
+}
+
+/** Removes the issue wherever it is and puts `next` (if any) at its place by rank in its status column. */
 export function placeIssue(
   columns: BoardColumn[],
   issueId: string,
@@ -42,7 +53,7 @@ export function placeIssue(
       : column.issues;
     let total = column.total - (had ? 1 : 0);
     if (next && next.status === column.status) {
-      issues = [next, ...issues];
+      issues = insertByRank(issues, next);
       total += 1;
     }
     return had || issues !== column.issues