⭐️⭐️⭐️ 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.
TypeScript agenticagileai-agentsbug-reportingbug-trackerganttissue-trackerjirajira-alternativekanbanlinearlinear-alternativeopen-sourceproduct-managementproject-managementroadmapself-hostedsprint-planningteam-collaborationtrello-alternative
import { useCallback, useEffect, useRef, useState } from 'react';
import type { ProjectDocument } from '@/lib/api/endpoints/documents';
import { ApiError } from '@/lib/api/core/client';
import { uuid } from '@/utils/uuid';
import { useUpdateDocument } from '../services/documents.service';
export type DocumentSaveState = 'saved' | 'saving' | 'conflict' | 'error';
const AUTOSAVE_DELAY_MS = 700;
interface StoredDocumentDraft {
title: string;
content: string;
contentJson?: Record<string, unknown> | null;
baseVersion: number;
writerId?: string;
collaborative?: boolean;
}
function draftStorageKey(projectKey: string, documentId: number, userId: string) {
return `itsaplan:document-draft:${userId}:${projectKey}:${documentId}`;
}
function storedDraft(value: string | null): StoredDocumentDraft | null {
if (!value) return null;
try {
const parsed: unknown = JSON.parse(value);
if (
!parsed ||
typeof parsed !== 'object' ||
typeof (parsed as StoredDocumentDraft).title !== 'string' ||
typeof (parsed as StoredDocumentDraft).content !== 'string' ||
((parsed as StoredDocumentDraft).contentJson !== undefined &&
(parsed as StoredDocumentDraft).contentJson !== null &&
typeof (parsed as StoredDocumentDraft).contentJson !== 'object') ||
!Number.isInteger((parsed as StoredDocumentDraft).baseVersion) ||
((parsed as StoredDocumentDraft).writerId !== undefined &&
typeof (parsed as StoredDocumentDraft).writerId !== 'string')
) {
return null;
}
return parsed as StoredDocumentDraft;
} catch {
return null;
}
}
function rebaseStoredDraft(
storageKey: string | null,
writerId: string,
fromVersion: number,
toVersion: number,
) {
if (!storageKey) return;
try {
const local = storedDraft(window.localStorage.getItem(storageKey));
// Do not overwrite a draft already rebased by another save/tab. Keeping the
// text unchanged is important: it may contain edits newer than this request.
if (!local || local.writerId !== writerId || local.baseVersion !== fromVersion) return;
window.localStorage.setItem(storageKey, JSON.stringify({ ...local, baseVersion: toVersion }));
} catch {
// Recovery storage is best effort; the server save still succeeded.
}
}
function removeOwnedStoredDraft(storageKey: string | null, writerId: string) {
if (!storageKey) return;
const rawStoredDraft = window.localStorage.getItem(storageKey);
const local = storedDraft(rawStoredDraft);
// The recovery key is shared by every tab for this account and page. A clean
// tab must not delete a newer draft written by another mounted tab. Legacy
// drafts have no writer id, so preserve them until a tab restores and rewrites
// them as its own.
if (rawStoredDraft !== null && local?.writerId === writerId) {
window.localStorage.removeItem(storageKey);
}
}
export function useDocumentDraft({
projectKey,
document,
editable,
userId,
collaborative = false,
}: {
projectKey: string;
document: ProjectDocument;
editable: boolean;
userId: string | null;
collaborative?: boolean;
}) {
const { mutateAsync } = useUpdateDocument(projectKey);
const versionRef = useRef(document.version);
const savingRef = useRef(false);
const writerIdRef = useRef(uuid());
const [legacyDraft, setLegacyDraft] = useState(false);
const [version, setVersion] = useState(document.version);
const [title, setTitleState] = useState(document.title);
const [content, setContentState] = useState(document.content);
const [contentJson, setContentJsonState] = useState(document.contentJson);
const [saved, setSaved] = useState({
title: document.title,
content: document.content,
contentJson: JSON.stringify(document.contentJson),
});
const [draftBaseVersion, setDraftBaseVersion] = useState(document.version);
const [saveState, setSaveState] = useState<DocumentSaveState>('saved');
const [editorRevision, setEditorRevision] = useState(0);
const [restoredStorageKey, setRestoredStorageKey] = useState<string | null>(null);
const dirty =
title !== saved.title ||
(!collaborative &&
(content !== saved.content || JSON.stringify(contentJson) !== saved.contentJson));
const storageKey = userId ? draftStorageKey(projectKey, document.id, userId) : null;
// Keep an on-device recovery copy. Unlike beforeunload, this also survives
// App Router links and browser Back/Forward, where React can unmount the editor
// before an unsuccessful autosave reports its error.
useEffect(() => {
if (!storageKey || restoredStorageKey === storageKey) return;
let local: StoredDocumentDraft | null = null;
try {
local = storedDraft(window.localStorage.getItem(storageKey));
} catch {
// Private browsing policies may make even reading storage throw.
}
versionRef.current = document.version;
setDraftBaseVersion(local?.baseVersion ?? document.version);
setSaved({
title: document.title,
content: document.content,
contentJson: JSON.stringify(document.contentJson),
});
setTitleState(local?.title ?? document.title);
setContentState(local?.content ?? document.content);
setContentJsonState(local ? (local.contentJson ?? null) : document.contentJson);
const legacy = Boolean(
collaborative &&
local &&
!local.collaborative &&
(local.content !== document.content ||
JSON.stringify(local.contentJson ?? null) !== JSON.stringify(document.contentJson)),
);
setLegacyDraft(legacy);
setSaveState(
legacy || (local && local.baseVersion !== document.version) ? 'conflict' : 'saved',
);
setEditorRevision((revision) => revision + 1);
setRestoredStorageKey(storageKey);
}, [
collaborative,
document.content,
document.contentJson,
document.title,
document.version,
restoredStorageKey,
storageKey,
]);
// A scope refresh can replace the query data while this editor stays mounted.
// Own writes update versionRef before their query result settles, so equality is
// also what prevents a successful autosave from remounting Tiptap and moving the
// cursor. A genuinely newer remote version is adopted only when there is no local
// work to protect; otherwise the existing conflict flow lets the user review it.
useEffect(() => {
if (document.version <= versionRef.current) return;
if (dirty || savingRef.current) {
if (collaborative && document.title === saved.title) {
versionRef.current = document.version;
setVersion(document.version);
setDraftBaseVersion(document.version);
} else setSaveState('conflict');
return;
}
versionRef.current = document.version;
setVersion(document.version);
setDraftBaseVersion(document.version);
setTitleState(document.title);
setContentState(document.content);
setContentJsonState(document.contentJson);
setSaved({
title: document.title,
content: document.content,
contentJson: JSON.stringify(document.contentJson),
});
setSaveState('saved');
if (!collaborative) setEditorRevision((revision) => revision + 1);
}, [
collaborative,
saved.title,
dirty,
document.content,
document.contentJson,
document.title,
document.version,
]);
useEffect(() => {
if (!storageKey || restoredStorageKey !== storageKey) return;
try {
if (dirty) {
window.localStorage.setItem(
storageKey,
JSON.stringify({
title,
content,
contentJson,
baseVersion: draftBaseVersion,
writerId: writerIdRef.current,
collaborative: collaborative && !legacyDraft,
}),
);
} else {
removeOwnedStoredDraft(storageKey, writerIdRef.current);
}
} catch {
// A full or disabled storage must not prevent editing or autosave.
}
}, [
collaborative,
legacyDraft,
content,
contentJson,
dirty,
draftBaseVersion,
restoredStorageKey,
storageKey,
title,
]);
const save = useCallback(async (): Promise<ProjectDocument | null> => {
if (!editable || !dirty || savingRef.current || saveState === 'conflict') return null;
const snapshot = { title, content, contentJson };
const baseVersion = versionRef.current;
savingRef.current = true;
setSaveState('saving');
try {
const updated = await mutateAsync({
documentId: document.id,
patch: {
version: baseVersion,
title: snapshot.title,
...(!collaborative
? { content: snapshot.content, contentJson: snapshot.contentJson }
: {}),
},
});
versionRef.current = updated.version;
setVersion(updated.version);
// This direct write also runs when navigation unmounted the editor while
// the request was in flight, where a React state/effect update cannot.
rebaseStoredDraft(storageKey, writerIdRef.current, baseVersion, updated.version);
// A user may keep typing while this request is in flight. Advancing the
// recovery draft's base version keeps those newer edits saveable after a
// navigation or remount, even before the next autosave fires.
setDraftBaseVersion(updated.version);
setSaved({ ...snapshot, contentJson: JSON.stringify(snapshot.contentJson) });
setSaveState('saved');
return updated;
} catch (error) {
setSaveState(error instanceof ApiError && error.status === 409 ? 'conflict' : 'error');
return null;
} finally {
savingRef.current = false;
}
}, [
collaborative,
content,
contentJson,
dirty,
document.id,
editable,
mutateAsync,
saveState,
storageKey,
title,
]);
useEffect(() => {
if (!editable || !dirty || saveState === 'conflict' || saveState === 'error') return;
const timer = window.setTimeout(() => void save(), AUTOSAVE_DELAY_MS);
return () => window.clearTimeout(timer);
}, [dirty, editable, save, saveState]);
useEffect(() => {
if (!dirty) return;
const warnBeforeLeaving = (event: BeforeUnloadEvent) => event.preventDefault();
window.addEventListener('beforeunload', warnBeforeLeaving);
return () => window.removeEventListener('beforeunload', warnBeforeLeaving);
}, [dirty]);
const setTitle = (value: string) => {
setTitleState(value);
setSaveState((state) => (state === 'error' ? 'saved' : state));
};
const setContent = (value: string, json: Record<string, unknown>) => {
setContentState(value);
setContentJsonState(json);
setSaveState((state) => (state === 'error' ? 'saved' : state));
};
const replaceWith = (latest: ProjectDocument) => {
setLegacyDraft(false);
try {
removeOwnedStoredDraft(storageKey, writerIdRef.current);
} catch {
// Reloading from the server still works when storage is unavailable.
}
versionRef.current = latest.version;
setVersion(latest.version);
setDraftBaseVersion(latest.version);
setTitleState(latest.title);
setContentState(latest.content);
setContentJsonState(latest.contentJson);
setSaved({
title: latest.title,
content: latest.content,
contentJson: JSON.stringify(latest.contentJson),
});
setSaveState('saved');
// Tiptap owns its document after mount. Remounting is the reliable way to
// replace it after resolving an optimistic-concurrency conflict.
setEditorRevision((revision) => revision + 1);
};
const adoptServerDocument = (latest: ProjectDocument) => {
if (latest.version < versionRef.current) return;
if (
collaborative &&
title !== saved.title &&
latest.title !== saved.title &&
latest.title !== title
)
setSaveState('conflict');
if (collaborative && (title === saved.title || latest.title === title)) {
setTitleState(latest.title);
setSaved((previous) => ({ ...previous, title: latest.title }));
}
const previousVersion = versionRef.current;
versionRef.current = latest.version;
setVersion(latest.version);
setDraftBaseVersion(latest.version);
rebaseStoredDraft(storageKey, writerIdRef.current, previousVersion, latest.version);
};
return {
legacyDraft,
title,
content,
contentJson,
dirty,
saveState,
version,
editorRevision,
setTitle,
setContent,
save,
replaceWith,
adoptServerDocument,
};
}