@templatical/core 0.48.0 → 0.49.0

package/dist/index.d.ts

@@ -1,12 +1,115 @@
-import { i as useEditor, n as UseEditorOptions, r as UseEditorReturn, t as EditorState } from "./editor-Bl4WsPU3.js";
-import { Block, BlockDefaults, BlockType, Comment, CommentAuthor, CommentInput, CommentPatch, CommentsListParams, CommentsProvider, CustomBlock, CustomBlockDefinition, MediaProvider, SavedBlock, SavedBlockPatch, SavedBlocksListParams, SavedBlocksProvider, Template, TemplateContent, TemplateSettings, TemplateVersion, VersionHistoryListParams, VersionHistoryProvider } from "@templatical/types";
-import { ComputedRef, Ref } from "@vue/reactivity";
+import { Block, BlockDefaults, BlockLock, BlockLockHolder, BlockType, CollaborationActor, CollaborationConflictCode, CollaborationConnectionState, CollaborationMember, CollaborationProvider, CollaborationRemoteChange, Comment, CommentAuthor, CommentInput, CommentPatch, CommentsListParams, CommentsProvider, CustomBlock, CustomBlockDefinition, MediaProvider, Operation, SavedBlock, SavedBlockPatch, SavedBlocksListParams, SavedBlocksProvider, Template, TemplateContent, TemplateDefaults, TemplateSaveTrigger, TemplateSettings, TemplateVersion, TemplatesProvider, UiTheme, VersionHistoryListParams, VersionHistoryProvider, ViewportSize } from "@templatical/types";
+import { ComputedRef, DeepReadonly, Ref } from "@vue/reactivity";
 import { ComputedRef as ComputedRef$1, Ref as Ref$1 } from "vue";
+//#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;
+  /**
+   * Blocks other collaborators hold. A locked block can't be selected, and the
+   * editor's own mutators leave it alone.
+   */
+  lockedBlocks?: Readonly<Ref<ReadonlyMap<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.
+   *
+   * `trigger` is passed through to `TemplatesOptions.onSaved`. It defaults to
+   * `"api"`, which is the honest answer for a direct call — the editor package
+   * passes the value matching whichever affordance fired.
+   */
+  save: (trigger?: TemplateSaveTrigger) => Promise<Template>;
+  /** Whether a template has been created or loaded. */
+  hasTemplate: () => boolean;
+}
+export declare function useEditor(options: UseEditorOptions): UseEditorReturn;
+//#endregion
 //#region src/history.d.ts
 interface UseHistoryOptions {
   content: Ref<TemplateContent>;
   setContent: (content: TemplateContent, markDirty?: boolean) => void;
-  isRemoteOperation?: () => boolean;
   maxSize?: number;
 }
 interface UseHistoryReturn {
@@ -136,11 +239,176 @@ interface HistoryInterceptorEditor {
  * Wraps editor mutation methods to record history snapshots before each
  * operation. Mutates the editor object in place.
  *
- * Must be applied **after** any collaboration broadcast wrapping so the
- * call chain is: history.record() → broadcast → original mutation.
+ * Not installed with a collaboration provider: its controller captures
+ * changes by diffing the content and keeps its own undo history.
  */
 export declare function useHistoryInterceptor(editor: HistoryInterceptorEditor, history: UseHistoryReturn): void;
 //#endregion
+//#region src/diff-content.d.ts
+/**
+ * The operations that turn `before` into `after`. Blocks are matched by id, so
+ * a drag comes out as a `moveBlock` and a layout change as a `columns` change
+ * plus moves, never as deletions and re-additions.
+ *
+ * `applyOperations(before, diffContent(before, after))` deep-equals `after`
+ * when both are well formed: unique ids, sections only at the top level, and
+ * each section's `children` as long as its layout's column count. The order is
+ * what the engine needs:
+ *
+ * 1. Deletions that take nothing still needed with them.
+ * 2. The top level: additions (a new section carries its new children) and moves.
+ * 3. `columns` growth, so new columns exist before blocks move into them.
+ * 4. Every section column: additions and moves, out of shrinking columns too.
+ * 5. `columns` shrinkage, once the dropped columns are empty.
+ * 6. Deletion of sections whose surviving blocks have moved out.
+ * 7. Key changes on blocks, then on settings.
+ *
+ * No operation carries `expect`: an ordinary edit applies over anything that
+ * doesn't conflict with it, and locks keep two people off one block.
+ */
+export declare function diffContent(before: TemplateContent, after: TemplateContent): Operation[];
+//#endregion
+//#region src/invert-operations.d.ts
+/**
+ * The batch that undoes `ops`, given the content they apply to. Each operation
+ * is inverted against the content just before it, and the inverses run in
+ * reverse order.
+ *
+ * Every inverse that can be guarded is: it expects what its operation left
+ * behind, so an undo that a later edit by someone else has overtaken is refused
+ * (`precondition_failed`, `anchor_missing`, `block_missing`) instead of
+ * overwriting that edit. A `setContent` inverse has no guard; the backend's
+ * `locked_by_others` rule is what stops it while others are editing.
+ *
+ * Throws the engine's `OperationError` when `ops` don't apply to `before`.
+ */
+export declare function invertOperations(before: TemplateContent, ops: readonly Operation[]): Operation[];
+//#endregion
+//#region src/collaboration.d.ts
+/** The template fields the controller reads, as the editor's readonly state holds them. */
+type CollaborationTemplate = DeepReadonly<Pick<Template, "id" | "revision" | "content">>;
+/** The slice of the editor the controller reads and writes. */
+interface CollaborationEditor {
+  state: {
+    readonly template: CollaborationTemplate | null;
+    readonly selectedBlockId: string | null;
+    readonly isLoading: boolean;
+  };
+  /** The live content the user edits. */
+  content: Ref<TemplateContent>;
+  selectBlock: (blockId: string | null) => void;
+  setContent: (content: TemplateContent, markDirty?: boolean) => void;
+  markDirty: () => void;
+}
+/** Something to tell the person at this editor. */
+type CollaborationNotice =
+/** Someone else holds the block this session tried to select. */
+{
+  type: "selectionRefused";
+  blockId: string;
+  holder: BlockLockHolder;
+} |
+/** A local change was refused and taken back. */
+{
+  type: "editRefused";
+  code: CollaborationConflictCode;
+  holder?: BlockLockHolder;
+} |
+/** An undo or redo step no longer applies and was dropped. */
+{
+  type: "undoSkipped";
+  code: CollaborationConflictCode;
+};
+/** A re-sync another session caused, as the backend announced it. */
+interface CollaborationRemoteResync {
+  /** The revision the re-sync brings the template to. */
+  revision: number;
+  actor: CollaborationActor;
+}
+interface UseCollaborationOptions {
+  provider: CollaborationProvider;
+  /**
+   * Fetch a template when the backend says to re-sync: the templates
+   * provider's `load`. Its `revision` says which revision `content` is at.
+   */
+  loadTemplate: (templateId: string) => Promise<Template>;
+  /** This editor instance's session id. A new UUID when omitted. */
+  sessionId?: string;
+  /** How many undo steps to keep. */
+  maxUndo?: number;
+  /** A batch from another session was applied. */
+  onRemoteChange?: (change: CollaborationRemoteChange) => void;
+  /**
+   * Another session re-synced the template — a `setContent`, a restore, a
+   * batch too large to broadcast — and the backend said who. Called for a
+   * revision this session doesn't have yet, before it catches up; the
+   * catch-up's batches still reach `onRemoteChange`. The editor names an
+   * agent's re-sync with it.
+   */
+  onRemoteResync?: (resync: CollaborationRemoteResync) => void;
+  /**
+   * Rewrite another session's batch just before it is applied, given the
+   * content it applies to. Called for live batches and catch-up batches
+   * alike, never for this session's own. The editor uses it to turn merge-tag
+   * tokens into tags, as it does for loaded content. `onRemoteChange` still
+   * receives the batch as the backend sent it.
+   */
+  normalizeRemoteOperations?: (ops: readonly Operation[], content: TemplateContent) => Operation[];
+  onNotice?: (notice: CollaborationNotice) => void;
+  onError?: (error: Error) => void;
+}
+interface UseCollaborationReturn {
+  readonly sessionId: string;
+  /** Everyone with the template open, this session included; empty without presence. */
+  members: Readonly<Ref<readonly CollaborationMember[]>>;
+  /** Blocks other sessions hold, by block id. */
+  locks: Readonly<Ref<ReadonlyMap<string, BlockLock>>>;
+  /** `null` before a realtime join, and for a backend without realtime. */
+  connection: Readonly<Ref<CollaborationConnectionState | null>>;
+  /** The last revision this session confirmed. */
+  revision: Readonly<Ref<number>>;
+  canUndo: ComputedRef<boolean>;
+  canRedo: ComputedRef<boolean>;
+  /** Wire the controller to the editor. Call once, inside the editor's setup scope. */
+  attach: (editor: CollaborationEditor) => void;
+  undo: () => void;
+  redo: () => void;
+  clearHistory: () => void;
+  /** Turn edits not sent yet into a batch now. */
+  flush: () => void;
+  /** Resolves once every batch is confirmed; rejects when one fails in transit. */
+  settle: () => Promise<void>;
+  /** Stop reading the canvas (a version preview is on it). Batches keep arriving. */
+  suspend: () => void;
+  /** Put the current state back on the canvas and read it again. */
+  resume: () => void;
+  /** Fetch what this session missed, or reload when the backend says to. */
+  catchUp: () => Promise<void>;
+  /** Whether the block exists in the content the backend confirmed. */
+  hasConfirmedBlock: (blockId: string) => boolean;
+  destroy: () => void;
+}
+/**
+ * Real-time collaboration over a {@link CollaborationProvider}.
+ *
+ * The controller keeps the content the backend confirmed at revision R, plus
+ * this session's pending batches; the canvas shows the confirmed content with
+ * the pending batches applied. Local changes are captured by diffing the
+ * canvas against that view: structural changes, selection changes and blur
+ * send at once, typing into one block after a short pause. One batch is in
+ * flight at a time. Batches from other sessions apply strictly by revision,
+ * with this session's pending batches replayed on top; a gap that isn't
+ * filled within a second, a re-sync, a reconnect and a refusal all fetch what
+ * was missed.
+ *
+ * Selecting a block takes its lock (when the backend has locks), renewed
+ * while selected and released on deselect, template switch and page hide.
+ * Undo and redo send inverse batches guarded by preconditions; one that no
+ * longer applies is dropped with a notice. Changes from others never enter the
+ * stacks.
+ */
+export declare function useCollaboration(options: UseCollaborationOptions): UseCollaborationReturn;
+//#endregion
 //#region src/saved-blocks.d.ts
 interface UseSavedBlocksOptions {
   /**
@@ -419,5 +687,5 @@ interface UseCommentListenerOptions {
  */
 export declare function useCommentListener(options: UseCommentListenerOptions): void;
 //#endregion
-export { type EditorState, type LocalStorageMediaProviderOptions, 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, useEditor };
+export type { CollaborationEditor, CollaborationNotice, CollaborationRemoteResync, CollaborationTemplate, EditorState, LocalStorageMediaProviderOptions, LocalStorageSavedBlocksOptions, UseAutoSaveOptions, UseAutoSaveReturn, UseBlockActionsOptions, UseBlockActionsReturn, UseCollaborationOptions, UseCollaborationReturn, UseCommentListenerOptions, UseCommentsOptions, UseCommentsReturn, UseConditionPreviewReturn, UseEditorOptions, UseEditorReturn, UseHistoryOptions, UseHistoryReturn, UseSavedBlocksOptions, UseSavedBlocksReturn, UseVersionHistoryOptions, UseVersionHistoryReturn };
 //# sourceMappingURL=index.d.ts.map