@templatical/core 0.26.3 → 0.27.0

package/dist/editor-BCujEIye.d.ts

@@ -0,0 +1,99 @@
+import { Block, Template, TemplateContent, TemplateDefaults, TemplateSettings, TemplatesProvider, UiTheme, ViewportSize } from "@templatical/types";
+import { DeepReadonly, Ref } from "@vue/reactivity";
+//#region src/editor.d.ts
+interface EditorState {
+  /**
+   * The template currently being edited, as the store last returned it — `null`
+   * until `create()` or `load()` resolves, and always `null` without a
+   * {@link TemplatesProvider}.
+   *
+   * Carries identity and name only for practical purposes: its `content` is the
+   * store's copy from the last round-trip, whereas `state.content` is what the
+   * user is editing.
+   */
+  template: Template | null;
+  content: TemplateContent;
+  selectedBlockId: string | null;
+  viewport: ViewportSize;
+  darkMode: boolean;
+  previewMode: boolean;
+  isDirty: boolean;
+  /** True for the duration of a `save()` call. */
+  isSaving: boolean;
+  /** True for the duration of a `create()` or `load()` call. */
+  isLoading: boolean;
+  uiTheme: UiTheme;
+}
+interface UseEditorOptions {
+  content: TemplateContent;
+  defaultFontFamily?: string;
+  templateDefaults?: TemplateDefaults;
+  lockedBlocks?: Ref<Map<string, unknown>>;
+  /**
+   * Storage backend for the template's save/load lifecycle. Omit it and
+   * `create()` / `load()` / `save()` reject — the editor keeps working as a
+   * purely local editing surface.
+   */
+  templates?: TemplatesProvider;
+  /**
+   * Called with any error a provider call rejects with, before the rejection is
+   * re-thrown to the caller.
+   */
+  onError?: (error: Error) => void;
+}
+interface UseEditorReturn {
+  state: DeepReadonly<EditorState>;
+  content: Ref<TemplateContent>;
+  selectedBlock: Ref<Block | null>;
+  setContent: (content: TemplateContent, markDirty?: boolean) => void;
+  selectBlock: (blockId: string | null) => void;
+  setViewport: (viewport: ViewportSize) => void;
+  setDarkMode: (darkMode: boolean) => void;
+  setPreviewMode: (previewMode: boolean) => void;
+  setUiTheme: (theme: UiTheme) => void;
+  updateBlock: (blockId: string, updates: Partial<Block>) => void;
+  updateSettings: (updates: Partial<TemplateSettings>) => void;
+  addBlock: (block: Block, targetSectionId?: string, columnIndex?: number, index?: number) => void;
+  removeBlock: (blockId: string) => void;
+  moveBlock: (blockId: string, newIndex: number, targetSectionId?: string, columnIndex?: number) => void;
+  isBlockLocked: (blockId: string) => boolean;
+  markDirty: () => void;
+  findBlockLocation: (blockId: string) => {
+    targetSectionId?: string;
+    columnIndex?: number;
+    index: number;
+  } | null;
+  /**
+   * Rename the loaded template locally and mark the editor dirty. The new name
+   * reaches the store on the next `save()`, in the same patch as the content —
+   * a rename is an ordinary unsaved change, not a side channel.
+   *
+   * This method only stages it. The editor's inline rename field commits by
+   * calling `setName()` and then saving immediately, because a rename reads as a
+   * discrete action rather than an edit to be batched — so in the editor the
+   * "next `save()`" is usually the one it triggers itself. A headless caller
+   * decides its own moment.
+   *
+   * No-op when no template is loaded: there is nothing to name.
+   */
+  setName: (name: string) => void;
+  /**
+   * Persist the current content as a new template. `input.content`, when given,
+   * replaces the editor's content first — so `create({ content })` both loads
+   * and stores in one step.
+   */
+  create: (input?: {
+    name?: string;
+    content?: TemplateContent;
+  }) => Promise<Template>;
+  /** Fetch a template and make it the editor's content. */
+  load: (templateId: string) => Promise<Template>;
+  /** Persist the loaded template's name + content as a patch. */
+  save: () => Promise<Template>;
+  /** Whether a template has been created or loaded. */
+  hasTemplate: () => boolean;
+}
+declare function useEditor(options: UseEditorOptions): UseEditorReturn;
+//#endregion
+export { useEditor as i, UseEditorOptions as n, UseEditorReturn as r, EditorState as t };
+//# sourceMappingURL=editor-BCujEIye.d.ts.map

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { i as useEditor, n as UseEditorOptions, r as UseEditorReturn, t as EditorState } from "./editor-BIIsaIoN.js";
-import { Block, BlockDefaults, BlockType, CustomBlock, CustomBlockDefinition, SavedBlock, SavedBlockPatch, SavedBlocksListParams, SavedBlocksProvider, TemplateContent } from "@templatical/types";
+import { i as useEditor, n as UseEditorOptions, r as UseEditorReturn, t as EditorState } from "./editor-BCujEIye.js";
+import { Block, BlockDefaults, BlockType, Comment, CommentAuthor, CommentEvent, CommentInput, CommentPatch, CommentsListParams, CommentsProvider, CustomBlock, CustomBlockDefinition, SavedBlock, SavedBlockPatch, SavedBlocksListParams, SavedBlocksProvider, Template, TemplateContent, TemplateSettings, TemplateVersion, VersionHistoryListParams, VersionHistoryProvider } from "@templatical/types";
 import { ComputedRef, Ref } from "@vue/reactivity";
 import { ComputedRef as ComputedRef$1, Ref as Ref$1 } from "vue";
 //#region src/history.d.ts
@@ -60,6 +60,21 @@ interface UseAutoSaveReturn {
   resume: () => void;
   destroy: () => void;
 }
+/**
+ * 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.** `initCloud()` used to carry its
+ * own copy at 5000 in the editor package; two constants for one setting drifted
+ * silently and nothing linked them. Cloud imports this one now.
+ */
+declare const DEFAULT_AUTO_SAVE_DEBOUNCE_MS = 2000;
 declare function useAutoSave(options: UseAutoSaveOptions): UseAutoSaveReturn;
 //#endregion
 //#region src/condition-preview.d.ts
@@ -69,7 +84,18 @@ interface UseConditionPreviewReturn {
   reset: () => void;
   hasHiddenBlocks: ComputedRef<boolean>;
 }
-declare function useConditionPreview(editor: UseEditorReturn): UseConditionPreviewReturn;
+/**
+ * The slice of an editor this needs — deliberately structural, so both the OSS
+ * and the Cloud `useEditor` satisfy it without either having to grow toward the
+ * other.
+ */
+interface ConditionPreviewEditor {
+  state: {
+    readonly selectedBlockId: string | null;
+  };
+  selectBlock: (blockId: string | null) => void;
+}
+declare function useConditionPreview(editor: ConditionPreviewEditor): UseConditionPreviewReturn;
 //#endregion
 //#region src/data-source-fetch.d.ts
 declare function useDataSourceFetch(options: {
@@ -85,6 +111,19 @@ declare function useDataSourceFetch(options: {
 };
 //#endregion
 //#region src/history-interceptor.d.ts
+/**
+ * The mutable slice of an editor this wraps — structural, so the OSS and Cloud
+ * `useEditor` returns both satisfy it without either having to grow toward the
+ * other. Not `Readonly`: the whole point is to replace these members in place.
+ */
+interface HistoryInterceptorEditor {
+  addBlock: (block: Block, targetSectionId?: string, columnIndex?: number, index?: number) => void;
+  removeBlock: (blockId: string) => void;
+  moveBlock: (blockId: string, newIndex: number, targetSectionId?: string, columnIndex?: number) => void;
+  updateBlock: (blockId: string, updates: Partial<Block>) => void;
+  updateSettings: (updates: Partial<TemplateSettings>) => void;
+  isBlockLocked: (blockId: string) => boolean;
+}
 /**
  * Wraps editor mutation methods to record history snapshots before each
  * operation. Mutates the editor object in place.
@@ -92,7 +131,7 @@ declare function useDataSourceFetch(options: {
  * Must be applied **after** any collaboration broadcast wrapping so the
  * call chain is: history.record() → broadcast → original mutation.
  */
-declare function useHistoryInterceptor(editor: UseEditorReturn, history: UseHistoryReturn): void;
+declare function useHistoryInterceptor(editor: HistoryInterceptorEditor, history: UseHistoryReturn): void;
 //#endregion
 //#region src/saved-blocks.d.ts
 interface UseSavedBlocksOptions {
@@ -184,5 +223,170 @@ interface LocalStorageSavedBlocksOptions {
  */
 declare function createLocalStorageSavedBlocksProvider(options?: LocalStorageSavedBlocksOptions): SavedBlocksProvider;
 //#endregion
-export { type EditorState, type LocalStorageSavedBlocksOptions, type UseAutoSaveOptions, type UseAutoSaveReturn, type UseBlockActionsOptions, type UseBlockActionsReturn, type UseConditionPreviewReturn, type UseEditorOptions, type UseEditorReturn, type UseHistoryOptions, type UseHistoryReturn, type UseSavedBlocksOptions, type UseSavedBlocksReturn, createLocalStorageSavedBlocksProvider, useAutoSave, useBlockActions, useConditionPreview, useDataSourceFetch, useEditor, useHistory, useHistoryInterceptor, useSavedBlocks };
+//#region src/version-history.d.ts
+interface UseVersionHistoryOptions {
+  /**
+   * Storage backend. Supplied by the consumer via `init({ versionHistory })`,
+   * or by Cloud's own adapter — this composable is transport-agnostic and never
+   * talks to a network itself.
+   */
+  provider: VersionHistoryProvider;
+  /**
+   * Which template's history this is. A getter rather than a value because a
+   * session can outlive the template: `initCloud()` constructs the feature at
+   * setup and only learns the id once `create()` / `load()` resolves.
+   */
+  getTemplateId: () => string | null;
+  onError?: (error: Error) => void;
+}
+interface UseVersionHistoryReturn {
+  /** The provider's list, in the provider's order. Never re-sorted. */
+  versions: Ref$1<TemplateVersion[]>;
+  isLoading: Ref$1<boolean>;
+  isRestoring: Ref$1<boolean>;
+  /**
+   * Cursor for the page after the one currently held, or `undefined` when the
+   * provider signalled there is no more. The editor loads one page and ignores
+   * this; it is here so a headless caller can page without reaching past the
+   * composable.
+   */
+  nextCursor: Ref$1<string | undefined>;
+  /** Whether the provider supplied each mutation at all. */
+  canCreate: ComputedRef$1<boolean>;
+  canRestore: ComputedRef$1<boolean>;
+  /** Re-read the list. The editor calls this bare; `params` is for headless callers. */
+  load: (params?: VersionHistoryListParams) => Promise<void>;
+  /**
+   * The version's content **if it is already in hand** — the provider's
+   * `content` hint, or a previous `get` this composable cached. `null` means a
+   * round-trip is required.
+   *
+   * Callers that must not block (scrubbing through history swaps the canvas in
+   * the same tick) check this first and only await {@link resolveContent} when
+   * it comes back null.
+   */
+  peekContent: (version: TemplateVersion) => TemplateContent | null;
+  /**
+   * `version.content ?? await provider.get(...)`, cached per version id, so a
+   * lazily-loaded version costs one round-trip on its first visit and nothing
+   * afterwards.
+   */
+  resolveContent: (version: TemplateVersion) => Promise<TemplateContent>;
+  /** Rejects with an {@link SdkError} when the provider disabled `create`. */
+  create: (content: TemplateContent, meta?: {
+    label?: string;
+  }) => Promise<TemplateVersion>;
+  /** Rejects with an {@link SdkError} when the provider disabled `restore`. */
+  restore: (versionId: string) => Promise<Template>;
+}
+/**
+ * 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.
+ */
+declare function useVersionHistory(options: UseVersionHistoryOptions): UseVersionHistoryReturn;
+//#endregion
+//#region src/comments.d.ts
+interface UseCommentsOptions {
+  /**
+   * Storage backend. Supplied by the consumer via `init({ comments })`, or by
+   * Cloud's own adapter — this composable is transport-agnostic and never talks
+   * to a network itself.
+   */
+  provider: CommentsProvider;
+  /**
+   * Which template's conversation this is. A getter rather than a value because a
+   * session can outlive the template: `initCloud()` constructs the feature at
+   * setup and only learns the id once `create()` / `load()` resolves.
+   */
+  getTemplateId: () => string | null;
+  /**
+   * Who is commenting, read at call time. `null` means the editor has no
+   * identity, and every mutation refuses — an unattributable comment is worse
+   * than no comment feature.
+   */
+  getUser: () => CommentAuthor | null;
+  /** Fired for every change this composable applied, local or remote. */
+  onComment?: (event: CommentEvent) => void;
+  onError?: (error: Error) => void;
+}
+interface UseCommentsReturn {
+  /** Thread roots in the provider's order. Never re-sorted. */
+  comments: Ref$1<Comment[]>;
+  isLoading: Ref$1<boolean>;
+  isSubmitting: Ref$1<boolean>;
+  /** Whether the provider supplied each mutation at all. */
+  canCreate: ComputedRef$1<boolean>;
+  canUpdate: ComputedRef$1<boolean>;
+  canDelete: ComputedRef$1<boolean>;
+  canResolve: ComputedRef$1<boolean>;
+  /** Roots plus replies. */
+  totalCount: ComputedRef$1<number>;
+  /** Unresolved roots — the badge on the trigger. */
+  unresolvedCount: ComputedRef$1<number>;
+  /** Comments per anchored block id, roots plus their replies. */
+  commentCountByBlock: ComputedRef$1<Map<string, number>>;
+  /** Re-read the list. The editor calls this bare; `params` is for headless callers. */
+  load: (params?: CommentsListParams) => Promise<void>;
+  /** Rejects with an {@link SdkError} when `create` is disabled or there is no user. */
+  create: (input: CommentInput) => Promise<Comment>;
+  /** Rejects with an {@link SdkError} when `update` is disabled or there is no user. */
+  update: (commentId: string, patch: CommentPatch) => Promise<Comment>;
+  /** Rejects with an {@link SdkError} when `delete` is disabled or there is no user. */
+  remove: (commentId: string) => Promise<void>;
+  /** Rejects with an {@link SdkError} when `setResolved` is disabled or there is no user. */
+  setResolved: (commentId: string, resolved: boolean) => Promise<Comment>;
+  /** Look one up by id, root or reply. `null` when it isn't loaded. */
+  find: (commentId: string) => Comment | null;
+  /** Whether this comment was written by the current user. */
+  isOwn: (comment: Comment) => boolean;
+  /**
+   * Apply a change that arrived from {@link CommentsProvider.subscribe}. Public
+   * so a consumer driving this headlessly can push their own transport into it.
+   */
+  applyRemoteCreate: (comment: Comment) => void;
+  applyRemoteUpdate: (comment: Comment) => void;
+  applyRemoteDelete: (commentId: string, parentId?: string | null) => void;
+}
+/**
+ * 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.
+ */
+declare function useComments(options: UseCommentsOptions): UseCommentsReturn;
+interface UseCommentListenerOptions {
+  comments: UseCommentsReturn;
+  provider: CommentsProvider;
+  getTemplateId: () => string | null;
+}
+/**
+ * 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.
+ */
+declare function useCommentListener(options: UseCommentListenerOptions): void;
+//#endregion
+export { DEFAULT_AUTO_SAVE_DEBOUNCE_MS, type EditorState, type LocalStorageSavedBlocksOptions, type UseAutoSaveOptions, type UseAutoSaveReturn, type UseBlockActionsOptions, type UseBlockActionsReturn, type UseCommentListenerOptions, type UseCommentsOptions, type UseCommentsReturn, type UseConditionPreviewReturn, type UseEditorOptions, type UseEditorReturn, type UseHistoryOptions, type UseHistoryReturn, type UseSavedBlocksOptions, type UseSavedBlocksReturn, type UseVersionHistoryOptions, type UseVersionHistoryReturn, createLocalStorageSavedBlocksProvider, useAutoSave, useBlockActions, useCommentListener, useComments, useConditionPreview, useDataSourceFetch, useEditor, useHistory, useHistoryInterceptor, useSavedBlocks, useVersionHistory };
 //# sourceMappingURL=index.d.ts.map