@templatical/core 0.26.3 → 0.27.1

package/dist/index.js

@@ -1,6 +1,6 @@
 import { SdkError, createBlock, createDefaultTemplateContent, generateId, safeClone } from "@templatical/types";
 import { computed, reactive, readonly, ref, watch } from "@vue/reactivity";
-import { computed as computed$1, ref as ref$1 } from "vue";
+import { computed as computed$1, onScopeDispose, ref as ref$1, watch as watch$1 } from "vue";
 //#region src/editor.ts
 function getColumnCount(layout) {
 	if (layout === "1") return 1;
@@ -9,19 +9,33 @@ function getColumnCount(layout) {
 }
 function useEditor(options) {
 	const state = reactive({
+		template: null,
 		content: options.content ?? createDefaultTemplateContent(options.defaultFontFamily, options.templateDefaults),
 		selectedBlockId: null,
 		viewport: "desktop",
 		darkMode: false,
 		previewMode: false,
 		isDirty: false,
+		isSaving: false,
+		isLoading: false,
 		uiTheme: "auto"
 	});
+	/**
+	* Bumped by every content mutation. `save()` captures it before awaiting the
+	* provider and only clears `isDirty` if it is unchanged afterwards, so an edit
+	* made while a save is in flight is not reported as persisted — which would
+	* also make autosave skip it, since that decides dirtiness at debounce time.
+	*/
+	let revision = 0;
+	function touch() {
+		state.isDirty = true;
+		revision++;
+	}
 	const content = computed({
 		get: () => state.content,
 		set: (value) => {
 			state.content = value;
-			state.isDirty = true;
+			touch();
 		}
 	});
 	const selectedBlock = computed(() => {
@@ -73,7 +87,7 @@ function useEditor(options) {
 	}
 	function setContent(newContent, markDirty = true) {
 		state.content = newContent;
-		if (markDirty) state.isDirty = true;
+		if (markDirty) touch();
 	}
 	function selectBlock(blockId) {
 		if (blockId && isBlockLocked(blockId)) return;
@@ -97,7 +111,7 @@ function useEditor(options) {
 		const block = findBlockById(state.content.blocks, blockId);
 		if (block) {
 			Object.assign(block, updates);
-			state.isDirty = true;
+			touch();
 		}
 	}
 	function updateSettings(updates) {
@@ -105,7 +119,7 @@ function useEditor(options) {
 			...state.content.settings,
 			...updates
 		};
-		state.isDirty = true;
+		touch();
 	}
 	function addBlock(block, targetSectionId, columnIndex = 0, index) {
 		if (targetSectionId && block.type === "section") return;
@@ -121,7 +135,7 @@ function useEditor(options) {
 			}
 		} else if (index !== void 0 && index < state.content.blocks.length) state.content.blocks.splice(index, 0, block);
 		else state.content.blocks.push(block);
-		state.isDirty = true;
+		touch();
 	}
 	function removeBlock(blockId) {
 		if (isBlockLocked(blockId)) return;
@@ -135,7 +149,7 @@ function useEditor(options) {
 					collectBlockIds(removed, removedIds);
 					if (removedIds.has(state.selectedBlockId)) state.selectedBlockId = null;
 				}
-				state.isDirty = true;
+				touch();
 			}
 		}
 	}
@@ -157,10 +171,105 @@ function useEditor(options) {
 		} else targetArray = state.content.blocks;
 		const [block] = parent.blocks.splice(oldIndex, 1);
 		targetArray.splice(newIndex, 0, block);
-		state.isDirty = true;
+		touch();
 	}
 	function markDirty() {
-		state.isDirty = true;
+		touch();
+	}
+	/**
+	* A refused call throws rather than resolving, because a resolved promise
+	* would read as "saved" to whoever awaited it.
+	*
+	* The message names the provider key the consumer set, not an internal
+	* capability flag: `EditorCapabilities` is type-only and its injection key is
+	* unexported, so neither a core nor an editor consumer can read one. Note the
+	* editor hides its own save controls when `save` is withheld but has no
+	* create affordance to hide at all, so `create()` is reachable by definition.
+	*/
+	function refuse(action, reason) {
+		throw new SdkError(`[Templatical] Templates: ${action} ${reason}`);
+	}
+	function requireProvider(action) {
+		const { templates } = options;
+		if (!templates) refuse(action, "needs a templates provider. Pass one as `init({ templates })` to enable saving and loading.");
+		return templates;
+	}
+	function setName(name) {
+		if (!state.template) return;
+		state.template = {
+			...state.template,
+			name
+		};
+		touch();
+	}
+	async function create(input) {
+		const { create: providerCreate } = requireProvider("create()");
+		if (typeof providerCreate !== "function") refuse("create()", "is disabled by the provider — its `create` is `false`.");
+		state.isLoading = true;
+		try {
+			if (input?.content) state.content = input.content;
+			const revisionAtRequest = revision;
+			const template = await providerCreate(input?.name !== void 0 ? {
+				name: input.name,
+				content: state.content
+			} : { content: state.content });
+			state.template = template;
+			if (revision === revisionAtRequest) state.isDirty = false;
+			return template;
+		} catch (error) {
+			options.onError?.(error);
+			throw error;
+		} finally {
+			state.isLoading = false;
+		}
+	}
+	async function load(templateId) {
+		const provider = requireProvider("load()");
+		state.isLoading = true;
+		try {
+			const template = await provider.load(templateId);
+			state.template = template;
+			state.content = template.content;
+			state.isDirty = false;
+			return template;
+		} catch (error) {
+			options.onError?.(error);
+			throw error;
+		} finally {
+			state.isLoading = false;
+		}
+	}
+	async function save() {
+		const { save: providerSave } = requireProvider("save()");
+		if (typeof providerSave !== "function") refuse("save()", "is disabled by the provider — its `save` is `false`.");
+		const current = state.template;
+		if (!current) refuse("save()", "has no template loaded. Call create() or load() first.");
+		const patch = current.name !== void 0 ? {
+			name: current.name,
+			content: state.content
+		} : { content: state.content };
+		state.isSaving = true;
+		try {
+			const revisionAtRequest = revision;
+			const template = await providerSave(current.id, patch);
+			if (state.template?.id === current.id) {
+				const localName = state.template.name;
+				state.template = localName !== current.name ? {
+					...template,
+					name: localName
+				} : template;
+			}
+			if (revision === revisionAtRequest) state.isDirty = false;
+			return template;
+		} catch (error) {
+			options.onError?.(error);
+			throw error;
+		} finally {
+			state.isSaving = false;
+		}
+	}
+	function hasTemplate() {
+		return state.template?.id !== void 0;
 	}
 	return {
 		state: readonly(state),
@@ -179,7 +288,12 @@ function useEditor(options) {
 		removeBlock,
 		moveBlock,
 		markDirty,
-		findBlockLocation
+		findBlockLocation,
+		setName,
+		create,
+		load,
+		save,
+		hasTemplate
 	};
 }
 //#endregion
@@ -344,8 +458,23 @@ function useBlockActions(options) {
 }
 //#endregion
 //#region src/auto-save.ts
+/**
+* Trailing debounce, in ms, measured from the *last* content mutation.
+*
+* Typing is not debounced upstream — TipTap's `onUpdate` calls `updateBlock` per
+* keystroke — so this is the only thing between a keypress and a whole-document
+* write. 1000 was too eager: ordinary prose pauses for a second constantly
+* (word choice, re-reading, reaching for the mouse), so a single paragraph could
+* produce dozens of full-content saves. 2000 roughly halves that while still
+* landing well before a user wonders whether their work was kept.
+*
+* **The single default for both entry points.** Cloud imports this constant
+* rather than declaring its own — a second copy for one setting drifts silently,
+* since nothing links the two.
+*/
+const DEFAULT_AUTO_SAVE_DEBOUNCE_MS = 2e3;
 function useAutoSave(options) {
-	const { content, isDirty, onChange, debounce = 1e3, enabled = true } = options;
+	const { content, isDirty, onChange, debounce = DEFAULT_AUTO_SAVE_DEBOUNCE_MS, enabled = true } = options;
 	let timeoutId = null;
 	let paused = false;
 	function isEnabled() {
@@ -685,6 +814,389 @@ function createLocalStorageSavedBlocksProvider(options = {}) {
 	};
 }
 //#endregion
-export { createLocalStorageSavedBlocksProvider, useAutoSave, useBlockActions, useConditionPreview, useDataSourceFetch, useEditor, useHistory, useHistoryInterceptor, useSavedBlocks };
+//#region src/version-history.ts
+/**
+* Reactive state over a {@link VersionHistoryProvider}.
+*
+* Owns the list, the loading flags and the per-version content cache that keeps
+* scrubbing synchronous. Errors are reported through `onError` and re-thrown,
+* leaving the list untouched on failure.
+*
+* It deliberately does **not** create versions of its own accord. The editor
+* never records a version on a save — whoever implements `TemplatesProvider.save`
+* decides that, because they are the side that pays for the storage.
+*/
+function useVersionHistory(options) {
+	const { provider, getTemplateId } = options;
+	const versions = ref$1([]);
+	const isLoading = ref$1(false);
+	const nextCursor = ref$1(void 0);
+	const isRestoring = ref$1(false);
+	/**
+	* Content fetched through `get`, keyed by version id. A version that carried
+	* a `content` hint never lands here — the hint is read straight off the entry,
+	* so a provider that eager-loads pays no second copy.
+	*/
+	const fetched = /* @__PURE__ */ new Map();
+	const canCreate = computed$1(() => typeof provider.create === "function");
+	const canRestore = computed$1(() => typeof provider.restore === "function");
+	/**
+	* The UI hides disabled actions and renders nothing before a template exists,
+	* so reaching one of these means a programmatic caller went around it. Fail
+	* loudly rather than silently no-op: a resolved promise reads as "done".
+	*/
+	function requireTemplateId(action) {
+		const templateId = getTemplateId();
+		if (!templateId) throw new SdkError(`[Templatical] Version history: ${action} needs a template. Call create() or load() first.`);
+		return templateId;
+	}
+	function refuse(action) {
+		throw new SdkError(`[Templatical] Version history: ${action} is disabled by the provider. Check the capability before calling — the editor's own UI hides the action.`);
+	}
+	async function load(params) {
+		const templateId = requireTemplateId("list");
+		isLoading.value = true;
+		try {
+			const page = await provider.list(templateId, params);
+			versions.value = page.versions;
+			nextCursor.value = page.nextCursor;
+		} catch (error) {
+			options.onError?.(error);
+			throw error;
+		} finally {
+			isLoading.value = false;
+		}
+	}
+	function peekContent(version) {
+		return version.content ?? fetched.get(version.id) ?? null;
+	}
+	async function resolveContent(version) {
+		const known = peekContent(version);
+		if (known) return known;
+		const templateId = requireTemplateId("get");
+		try {
+			const content = await provider.get(templateId, version.id);
+			fetched.set(version.id, content);
+			return content;
+		} catch (error) {
+			options.onError?.(error);
+			throw error;
+		}
+	}
+	async function create(content, meta) {
+		const { create: providerCreate } = provider;
+		if (typeof providerCreate !== "function") refuse("create");
+		const templateId = requireTemplateId("create");
+		try {
+			const created = await providerCreate(templateId, content, meta);
+			versions.value = [created, ...versions.value];
+			return created;
+		} catch (error) {
+			options.onError?.(error);
+			throw error;
+		}
+	}
+	async function restore(versionId) {
+		const { restore: providerRestore } = provider;
+		if (typeof providerRestore !== "function") refuse("restore");
+		const templateId = requireTemplateId("restore");
+		isRestoring.value = true;
+		try {
+			return await providerRestore(templateId, versionId);
+		} catch (error) {
+			options.onError?.(error);
+			throw error;
+		} finally {
+			isRestoring.value = false;
+		}
+	}
+	return {
+		nextCursor,
+		versions,
+		isLoading,
+		isRestoring,
+		canCreate,
+		canRestore,
+		load,
+		peekContent,
+		resolveContent,
+		create,
+		restore
+	};
+}
+//#endregion
+//#region src/comments.ts
+/**
+* Reactive state over a {@link CommentsProvider}.
+*
+* Owns the thread list, the loading flags, the local mutations that keep the list
+* consistent, and the derived counts the chrome renders. Errors are reported
+* through `onError` and **re-thrown**, leaving the list untouched on failure —
+* the same discipline as `useSavedBlocks` and `useVersionHistory`.
+*
+* Mutations **reject** when the provider withheld them rather than resolving to
+* `null`: a resolved promise reads as "saved" to whoever awaited it. Ask through
+* `canCreate` / `canUpdate` / `canDelete` / `canResolve` first — which is what the
+* editor's own UI does, hiding each action rather than disabling it.
+*/
+function useComments(options) {
+	const { provider, getTemplateId, getUser } = options;
+	const comments = ref$1([]);
+	const isLoading = ref$1(false);
+	const isSubmitting = ref$1(false);
+	const canCreate = computed$1(() => typeof provider.create === "function");
+	const canUpdate = computed$1(() => typeof provider.update === "function");
+	const canDelete = computed$1(() => typeof provider.delete === "function");
+	const canResolve = computed$1(() => typeof provider.setResolved === "function");
+	const totalCount = computed$1(() => comments.value.reduce((sum, thread) => sum + 1 + (thread.replies?.length ?? 0), 0));
+	const unresolvedCount = computed$1(() => comments.value.filter((thread) => !thread.resolvedAt).length);
+	const commentCountByBlock = computed$1(() => {
+		const map = /* @__PURE__ */ new Map();
+		for (const thread of comments.value) {
+			if (!thread.blockId) continue;
+			map.set(thread.blockId, (map.get(thread.blockId) ?? 0) + 1 + (thread.replies?.length ?? 0));
+		}
+		return map;
+	});
+	/**
+	* The UI hides disabled actions and renders nothing before a template exists,
+	* so reaching one of these means a programmatic caller went around it. Fail
+	* loudly rather than silently no-op.
+	*/
+	function requireTemplateId(action) {
+		const templateId = getTemplateId();
+		if (!templateId) throw new SdkError(`[Templatical] Comments: ${action} needs a template. Call create() or load() first.`);
+		return templateId;
+	}
+	function requireUser(action) {
+		const user = getUser();
+		if (!user) throw new SdkError(`[Templatical] Comments: ${action} needs to know who is commenting. Pass init({ user: { id, name } }) — an unattributed comment is not written.`);
+		return user;
+	}
+	function refuse(action) {
+		throw new SdkError(`[Templatical] Comments: ${action} is disabled by the provider. Check the capability before calling — the editor's own UI hides the action.`);
+	}
+	function find(commentId) {
+		for (const thread of comments.value) {
+			if (thread.id === commentId) return thread;
+			for (const reply of thread.replies ?? []) if (reply.id === commentId) return reply;
+		}
+		return null;
+	}
+	function isOwn(comment) {
+		const user = getUser();
+		return user !== null && comment.author.id === user.id;
+	}
+	function emit(type, comment) {
+		options.onComment?.({
+			type,
+			comment
+		});
+	}
+	function report(error) {
+		const wrapped = error instanceof Error ? error : new Error(String(error), { cause: error });
+		options.onError?.(wrapped);
+		throw wrapped;
+	}
+	/**
+	* Insert a comment, replacing an entry with the same id rather than duplicating
+	* it. `create` and a subscribe echo of that same create both land here, which is
+	* why a provider does not have to de-duplicate its own broadcasts.
+	*/
+	function replaceAt(list, index, next) {
+		return [
+			...list.slice(0, index),
+			next,
+			...list.slice(index + 1)
+		];
+	}
+	function upsert(comment) {
+		if (comment.parentId) {
+			comments.value = comments.value.map((thread) => {
+				if (thread.id !== comment.parentId) return thread;
+				const replies = thread.replies ?? [];
+				const at = replies.findIndex((reply) => reply.id === comment.id);
+				return {
+					...thread,
+					replies: at === -1 ? [...replies, comment] : replaceAt(replies, at, comment)
+				};
+			});
+			return;
+		}
+		const at = comments.value.findIndex((thread) => thread.id === comment.id);
+		if (at === -1) {
+			comments.value = [...comments.value, comment];
+			return;
+		}
+		comments.value = replaceAt(comments.value, at, {
+			...comment,
+			replies: comment.replies ?? comments.value[at].replies
+		});
+	}
+	function drop(commentId, parentId) {
+		const existing = find(commentId);
+		const parent = parentId ?? existing?.parentId ?? null;
+		if (parent) comments.value = comments.value.map((thread) => thread.id === parent ? {
+			...thread,
+			replies: (thread.replies ?? []).filter((r) => r.id !== commentId)
+		} : thread);
+		else comments.value = comments.value.filter((c) => c.id !== commentId);
+		return existing;
+	}
+	async function load(params) {
+		const templateId = requireTemplateId("list");
+		isLoading.value = true;
+		try {
+			comments.value = await provider.list(templateId, params);
+		} catch (error) {
+			report(error);
+		} finally {
+			isLoading.value = false;
+		}
+	}
+	async function create(input) {
+		const { create: providerCreate } = provider;
+		if (typeof providerCreate !== "function") refuse("create");
+		const templateId = requireTemplateId("create");
+		requireUser("create");
+		isSubmitting.value = true;
+		try {
+			const created = await providerCreate(templateId, input);
+			upsert(created);
+			emit("created", created);
+			return created;
+		} catch (error) {
+			report(error);
+		} finally {
+			isSubmitting.value = false;
+		}
+	}
+	async function update(commentId, patch) {
+		const { update: providerUpdate } = provider;
+		if (typeof providerUpdate !== "function") refuse("update");
+		const templateId = requireTemplateId("update");
+		requireUser("update");
+		isSubmitting.value = true;
+		try {
+			const updated = await providerUpdate(templateId, commentId, patch);
+			upsert(updated);
+			emit("updated", updated);
+			return updated;
+		} catch (error) {
+			report(error);
+		} finally {
+			isSubmitting.value = false;
+		}
+	}
+	async function remove(commentId) {
+		const { delete: providerDelete } = provider;
+		if (typeof providerDelete !== "function") refuse("delete");
+		const templateId = requireTemplateId("delete");
+		requireUser("delete");
+		const existing = find(commentId);
+		isSubmitting.value = true;
+		try {
+			await providerDelete(templateId, commentId);
+			drop(commentId);
+			if (existing) emit("deleted", existing);
+		} catch (error) {
+			report(error);
+		} finally {
+			isSubmitting.value = false;
+		}
+	}
+	async function setResolved(commentId, resolved) {
+		const { setResolved: providerSetResolved } = provider;
+		if (typeof providerSetResolved !== "function") refuse("setResolved");
+		const templateId = requireTemplateId("setResolved");
+		requireUser("setResolved");
+		isSubmitting.value = true;
+		try {
+			const updated = await providerSetResolved(templateId, commentId, resolved);
+			upsert(updated);
+			emit(updated.resolvedAt ? "resolved" : "unresolved", updated);
+			return updated;
+		} catch (error) {
+			report(error);
+		} finally {
+			isSubmitting.value = false;
+		}
+	}
+	function applyRemoteCreate(comment) {
+		upsert(comment);
+		emit("created", comment);
+	}
+	function applyRemoteUpdate(comment) {
+		upsert(comment);
+		emit(comment.resolvedAt ? "resolved" : "updated", comment);
+	}
+	function applyRemoteDelete(commentId, parentId) {
+		const existing = drop(commentId, parentId);
+		if (existing) emit("deleted", existing);
+	}
+	return {
+		comments,
+		isLoading,
+		isSubmitting,
+		canCreate,
+		canUpdate,
+		canDelete,
+		canResolve,
+		totalCount,
+		unresolvedCount,
+		commentCountByBlock,
+		load,
+		create,
+		update,
+		remove,
+		setResolved,
+		find,
+		isOwn,
+		applyRemoteCreate,
+		applyRemoteUpdate,
+		applyRemoteDelete
+	};
+}
+/**
+* Wire {@link CommentsProvider.subscribe} into the three `applyRemote*` paths.
+*
+* A no-op when the provider has no `subscribe` — realtime is optional, and
+* comments without it work exactly the same except that a colleague's comment
+* only appears on the next read. Nothing here knows about a transport: Cloud's
+* Pusher channel lives inside `createCloudCommentsProvider`, and an SSE or
+* long-poll implementation is the same three lines on the consumer's side.
+*
+* Re-subscribes when the template id changes, and unsubscribes on scope dispose —
+* so a session that loads a second template does not keep receiving the first
+* one's comments.
+*/
+function useCommentListener(options) {
+	const { comments, provider, getTemplateId } = options;
+	const { subscribe } = provider;
+	if (typeof subscribe !== "function") return;
+	let unsubscribe = null;
+	function stop() {
+		unsubscribe?.();
+		unsubscribe = null;
+	}
+	watch$1(() => getTemplateId(), (templateId) => {
+		stop();
+		if (!templateId) return;
+		unsubscribe = subscribe(templateId, (change) => {
+			switch (change.type) {
+				case "created":
+					comments.applyRemoteCreate(change.comment);
+					break;
+				case "updated":
+					comments.applyRemoteUpdate(change.comment);
+					break;
+				case "deleted": comments.applyRemoteDelete(change.commentId, change.parentId);
+			}
+		});
+	}, { immediate: true });
+	onScopeDispose(stop);
+}
+//#endregion
+export { DEFAULT_AUTO_SAVE_DEBOUNCE_MS, createLocalStorageSavedBlocksProvider, useAutoSave, useBlockActions, useCommentListener, useComments, useConditionPreview, useDataSourceFetch, useEditor, useHistory, useHistoryInterceptor, useSavedBlocks, useVersionHistory };
 
 //# sourceMappingURL=index.js.map