Skip to content

⭐️⭐️⭐️ Open-source, self-hosted alternative to Linear and Plane. Project management and issue tracking where teams and AI agents work side by side to plan and ship products.

12.0 KB
Raw Blame
import assert from 'node:assert/strict';
import { afterEach, beforeEach, describe, it } from 'node:test';
import { act } from 'react';
import type { Root } from 'react-dom/client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { JSDOM } from 'jsdom';
import type { ProjectDocument } from '@/lib/api/endpoints/documents';

type UseDocumentDraft = (typeof import('./useDocumentDraft'))['useDocumentDraft'];
type DocumentDraftController = ReturnType<UseDocumentDraft>;

const replacedGlobals = [
  'window',
  'document',
  'navigator',
  'HTMLElement',
  'IS_REACT_ACT_ENVIRONMENT',
] as const;

let dom: JSDOM;
let root: Root;
let queryClient: QueryClient;
let useDocumentDraft: UseDocumentDraft;
let originalFetch: typeof fetch;
let controller: DocumentDraftController | null;
let originalGlobalDescriptors: Map<string, PropertyDescriptor | undefined>;

// Holds the save in flight until the test resolves it. The update is stubbed at
// fetch rather than at updateDocument: an ES module binding cannot be reassigned.
function stubSave(update: Promise<ProjectDocument>): void {
  globalThis.fetch = (() =>
    update.then((document) => new Response(JSON.stringify(document)))) as typeof fetch;
}

function projectDocument(version: number, content: string): ProjectDocument {
  return {
    id: 42,
    projectId: 7,
    parentId: null,
    title: 'Runbook',
    content,
    contentJson: null,
    icon: null,
    metadata: {},
    fullWidth: false,
    isPrivate: false,
    isLocked: false,
    isFavorite: false,
    archivedAt: null,
    position: 0,
    version,
    ownerUserId: 'user-1',
    createdByUserId: 'user-1',
    updatedByUserId: 'user-1',
    createdAt: '2026-09-01T00:00:00.000Z',
    updatedAt: '2026-09-01T00:00:00.000Z',
    shareToken: null,
    shareExpiresAt: null,
    shareIncludeChildren: false,
    shareIncludeIssues: false,
  };
}

function Probe({
  document,
  editable,
  collaborative = false,
  onController = (value) => {
    controller = value;
  },
}: {
  document: ProjectDocument;
  editable: boolean;
  collaborative?: boolean;
  onController?: (value: DocumentDraftController) => void;
}) {
  const value = useDocumentDraft({
    projectKey: 'SEKTA',
    document,
    editable,
    userId: 'user-1',
    collaborative,
  });
  onController(value);
  return null;
}

function renderInto(
  targetRoot: Root,
  document: ProjectDocument,
  editable: boolean,
  onController?: (value: DocumentDraftController) => void,
  collaborative = false,
) {
  act(() =>
    targetRoot.render(
      <QueryClientProvider client={queryClient}>
        <Probe
          document={document}
          editable={editable}
          collaborative={collaborative}
          onController={onController}
        />
      </QueryClientProvider>,
    ),
  );
}

function render(document: ProjectDocument, editable = true, collaborative = false) {
  renderInto(root, document, editable, undefined, collaborative);
  assert.ok(controller);
}

beforeEach(async () => {
  originalGlobalDescriptors = new Map(
    replacedGlobals.map((name) => [name, Object.getOwnPropertyDescriptor(globalThis, name)]),
  );
  dom = new JSDOM('<!doctype html><div id="root"></div>', { url: 'https://plan.example.test' });
  dom.window.__ITSAPLAN_ENV__ = {
    apiUrl: 'https://api.example.test',
    privacyUrl: '',
    termsUrl: '',
  };
  Object.defineProperties(globalThis, {
    window: { configurable: true, value: dom.window },
    document: { configurable: true, value: dom.window.document },
    navigator: { configurable: true, value: dom.window.navigator },
    HTMLElement: { configurable: true, value: dom.window.HTMLElement },
    IS_REACT_ACT_ENVIRONMENT: { configurable: true, value: true },
  });

  ({ useDocumentDraft } = await import('./useDocumentDraft'));
  originalFetch = globalThis.fetch;
  queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
  controller = null;

  const { createRoot } = await import('react-dom/client');
  const rootElement = document.querySelector('#root');
  assert.ok(rootElement);
  root = createRoot(rootElement);
});

afterEach(() => {
  globalThis.fetch = originalFetch;
  act(() => root.unmount());
  queryClient.clear();
  dom.window.close();
  for (const [name, descriptor] of originalGlobalDescriptors) {
    if (descriptor) Object.defineProperty(globalThis, name, descriptor);
    else Reflect.deleteProperty(globalThis, name);
  }
});

describe('useDocumentDraft', () => {
  it('adopts a newer remote version when the editor is clean', () => {
    render(projectDocument(1, 'Initial'));
    const previousRevision = controller!.editorRevision;

    render(projectDocument(2, 'Changed elsewhere'));

    assert.equal(controller!.content, 'Changed elsewhere');
    assert.equal(controller!.version, 2);
    assert.equal(controller!.saveState, 'saved');
    assert.equal(controller!.editorRevision, previousRevision + 1);
  });

  it('preserves a local draft and enters conflict on a newer remote version', () => {
    render(projectDocument(1, 'Initial'));
    act(() => controller!.setContent('Local draft', { type: 'doc', content: [] }));

    render(projectDocument(2, 'Changed elsewhere'));

    assert.equal(controller!.content, 'Local draft');
    assert.equal(controller!.version, 1);
    assert.equal(controller!.dirty, true);
    assert.equal(controller!.saveState, 'conflict');
  });

  it('refreshes a read-only view without requiring an editor save', () => {
    render(projectDocument(1, 'Initial'), false);

    render(projectDocument(2, 'Read-only refresh'), false);

    assert.equal(controller!.content, 'Read-only refresh');
    assert.equal(controller!.version, 2);
    assert.equal(controller!.saveState, 'saved');
  });

  it('rebases edits made during an in-flight save before a remount', async () => {
    const first = projectDocument(1, 'Server copy');
    render(first);

    let resolveUpdate!: (document: ProjectDocument) => void;
    const update = new Promise<ProjectDocument>((resolve) => {
      resolveUpdate = resolve;
    });
    stubSave(update);

    act(() => controller!.setContent('Snapshot A', { type: 'doc', content: [] }));
    let savePromise!: Promise<ProjectDocument | null>;
    act(() => {
      savePromise = controller!.save();
    });
    act(() => controller!.setContent('Newer draft B', { type: 'doc', content: [] }));

    const storageKey = 'itsaplan:document-draft:user-1:SEKTA:42';
    assert.equal(JSON.parse(window.localStorage.getItem(storageKey)!).baseVersion, 1);

    // Navigation may unmount the editor while its request is still in flight.
    // The success path must rebase the recovery draft without relying on a
    // mounted component or a follow-up React effect.
    act(() => root.unmount());
    resolveUpdate(projectDocument(2, 'Snapshot A'));
    await savePromise;

    const rebased = JSON.parse(window.localStorage.getItem(storageKey)!);
    assert.deepEqual(
      { title: rebased.title, content: rebased.content, baseVersion: rebased.baseVersion },
      { title: 'Runbook', content: 'Newer draft B', baseVersion: 2 },
    );
    assert.equal(typeof rebased.writerId, 'string');

    const { createRoot } = await import('react-dom/client');
    const rootElement = document.querySelector('#root');
    assert.ok(rootElement);
    root = createRoot(rootElement);
    controller = null;
    render(projectDocument(2, 'Snapshot A'));

    assert.equal(controller!.content, 'Newer draft B');
    assert.equal(controller!.dirty, true);
    assert.equal(controller!.saveState, 'saved');
  });

  it("does not rebase another tab's recovery draft", async () => {
    render(projectDocument(1, 'Server copy'));

    let resolveUpdate!: (document: ProjectDocument) => void;
    const update = new Promise<ProjectDocument>((resolve) => {
      resolveUpdate = resolve;
    });
    stubSave(update);

    act(() => controller!.setContent('Saved by tab A', { type: 'doc', content: [] }));
    let savePromise!: Promise<ProjectDocument | null>;
    act(() => {
      savePromise = controller!.save();
    });

    const storageKey = 'itsaplan:document-draft:user-1:SEKTA:42';
    window.localStorage.setItem(
      storageKey,
      JSON.stringify({
        title: 'Runbook',
        content: 'Draft from tab B',
        baseVersion: 1,
        writerId: 'tab-b',
      }),
    );

    act(() => root.unmount());
    resolveUpdate(projectDocument(2, 'Saved by tab A'));
    await savePromise;

    assert.deepEqual(JSON.parse(window.localStorage.getItem(storageKey)!), {
      title: 'Runbook',
      content: 'Draft from tab B',
      baseVersion: 1,
      writerId: 'tab-b',
    });

    const { createRoot } = await import('react-dom/client');
    const rootElement = document.querySelector('#root');
    assert.ok(rootElement);
    root = createRoot(rootElement);
  });

  it("does not delete another mounted tab's recovery draft after saving", async () => {
    render(projectDocument(1, 'Server copy'));
    const tabA = controller!;

    const tabBElement = document.createElement('div');
    document.body.appendChild(tabBElement);
    const { createRoot } = await import('react-dom/client');
    const tabBRoot = createRoot(tabBElement);
    const tabB: { current: DocumentDraftController | null } = { current: null };
    renderInto(tabBRoot, projectDocument(1, 'Server copy'), true, (value) => {
      tabB.current = value;
    });
    assert.ok(tabB.current);

    let resolveUpdate!: (document: ProjectDocument) => void;
    const update = new Promise<ProjectDocument>((resolve) => {
      resolveUpdate = resolve;
    });
    stubSave(update);

    act(() => tabA.setContent('Saved by tab A', { type: 'doc', content: [] }));
    let savePromise!: Promise<ProjectDocument | null>;
    act(() => {
      savePromise = tabA.save();
    });
    act(() => tabB.current!.setContent('Newer draft from tab B', { type: 'doc', content: [] }));

    const storageKey = 'itsaplan:document-draft:user-1:SEKTA:42';
    const tabBDraft = JSON.parse(window.localStorage.getItem(storageKey)!);
    assert.equal(tabBDraft.content, 'Newer draft from tab B');
    assert.equal(typeof tabBDraft.writerId, 'string');

    await act(async () => {
      resolveUpdate(projectDocument(2, 'Saved by tab A'));
      await savePromise;
    });

    assert.deepEqual(JSON.parse(window.localStorage.getItem(storageKey)!), tabBDraft);

    renderInto(tabBRoot, projectDocument(2, 'Saved by tab A'), true, (value) => {
      tabB.current = value;
    });
    assert.equal(tabB.current!.content, 'Newer draft from tab B');
    assert.equal(tabB.current!.dirty, true);
    assert.equal(tabB.current!.saveState, 'conflict');

    act(() => tabBRoot.unmount());
    tabBElement.remove();
  });
});

describe('collaborative document titles and legacy drafts', () => {
  it('rebases title changes over body-only updates and protects a competing title', () => {
    render(projectDocument(1, 'Initial'), true, true);
    act(() => controller!.setTitle('My title'));
    act(() => controller!.adoptServerDocument(projectDocument(2, 'Remote body')));
    assert.equal(controller!.version, 2);
    assert.equal(controller!.saveState, 'saved');
    act(() =>
      controller!.adoptServerDocument({
        ...projectDocument(3, 'Remote body'),
        title: 'Other title',
      }),
    );
    assert.equal(controller!.title, 'My title');
    assert.equal(controller!.saveState, 'conflict');
    act(() => controller!.adoptServerDocument(projectDocument(1, 'Stale body')));
    assert.equal(controller!.version, 3);
  });
  it('preserves a body draft made before collaborative editing was enabled', () => {
    window.localStorage.setItem(
      'itsaplan:document-draft:user-1:SEKTA:42',
      JSON.stringify({ title: 'Runbook', content: 'Unsaved old editor text', baseVersion: 1 }),
    );
    render(projectDocument(1, 'Initial'), true, true);
    assert.equal(controller!.legacyDraft, true);
    assert.equal(controller!.content, 'Unsaved old editor text');
    assert.equal(controller!.saveState, 'conflict');
    act(() => controller!.replaceWith(projectDocument(2, 'Current')));
    assert.equal(controller!.legacyDraft, false);
    assert.equal(controller!.content, 'Current');
  });
});