@templatical/core 0.52.0 → 0.53.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Block, BlockDefaults, BlockLock, BlockLockHolder, BlockType, CollaborationActor, CollaborationConflictCode, CollaborationConnectionState, CollaborationMember, CollaborationProvider, CollaborationRemoteChange, Comment, CommentAuthor, CommentInput, CommentPatch, CommentsListParams, CommentsProvider, CustomBlock, CustomBlockDefinition, MediaProvider, Operation, OperationError, SavedBlock, SavedBlockPatch, SavedBlocksListParams, SavedBlocksProvider, Template, TemplateContent, TemplateDefaults, TemplateSaveTrigger, TemplateSettings, TemplateVersion, TemplatesProvider, UiTheme, VersionHistoryListParams, VersionHistoryProvider, ViewportSize, invertOperations } from "@templatical/types";
+import { Block, BlockDefaults, BlockLock, BlockLockHolder, BlockType, CollaborationActor, CollaborationConflictCode, CollaborationConnectionState, CollaborationMember, CollaborationProvider, CollaborationRemoteChange, Comment, CommentAuthor, CommentInput, CommentPatch, CommentsListParams, CommentsProvider, CustomBlock, CustomBlockDefinition, MediaProvider, Operation, OperationError, SavedBlock, SavedBlockPatch, SavedBlocksListParams, SavedBlocksProvider, SetDefaultLocaleOperation, Template, TemplateContent, TemplateDefaults, TemplateSaveTrigger, TemplateSettings, TemplateVersion, TemplatesProvider, UiTheme, VersionHistoryListParams, VersionHistoryProvider, ViewportSize, invertOperations } from "@templatical/types";
 import { ComputedRef, DeepReadonly, Ref } from "@vue/reactivity";
 import { ComputedRef as ComputedRef$1, Ref as Ref$1 } from "vue";
 interface EditorState {
@@ -13,6 +13,7 @@ interface EditorState {
    */
   template: Template | null;
   content: TemplateContent;
+  activeLocale: string | null;
   selectedBlockId: string | null;
   viewport: ViewportSize;
   darkMode: boolean;
@@ -26,6 +27,11 @@ interface EditorState {
 }
 interface UseEditorOptions {
   content: TemplateContent;
+  localization?: {
+    locales: string[];
+  };
+  onLocaleChange?: (locale: string) => void;
+  onStructureChange?: () => void;
   defaultFontFamily?: string;
   templateDefaults?: TemplateDefaults;
   /**
@@ -33,6 +39,10 @@ interface UseEditorOptions {
    * editor's own mutators leave it alone.
    */
   lockedBlocks?: Readonly<Ref<ReadonlyMap<string, unknown>>>;
+  /** The language view for property edits and selection; absent or `null` is default. */
+  lockLocale?: Readonly<Ref<string | null>>;
+  /** This editor's session; its own locks never block local edits. */
+  lockSessionId?: string;
   /**
    * Storage backend for the template's save/load lifecycle. Omit it and
    * `create()` / `load()` / `save()` reject — the editor keeps working as a
@@ -51,6 +61,16 @@ interface UseEditorReturn {
   loadVersion: Readonly<Ref<number>>;
   content: Ref<TemplateContent>;
   selectedBlock: Ref<Block | null>;
+  activeLocale: Ref<string | null>;
+  setActiveLocale: (locale: string | null) => void;
+  addLocale: (locale: string) => void;
+  removeLocale: (locale: string) => void;
+  setBlockHidden: (blockId: string, hidden: boolean) => void;
+  resetLocaleFields: (blockId: string, paths?: string[]) => void;
+  keepTranslations: (blockId: string, paths: string[]) => void;
+  setCustomBlockDefinitions: (defs: readonly CustomBlockDefinition[]) => void;
+  /** Captures registered custom text paths for deterministic default-language replay. Pure. */
+  createSetDefaultLocaleOperation: (locale: string) => SetDefaultLocaleOperation;
   setContent: (content: TemplateContent, markDirty?: boolean) => void;
   selectBlock: (blockId: string | null) => void;
   setViewport: (viewport: ViewportSize) => void;
@@ -121,6 +141,7 @@ interface UseHistoryReturn {
   recordDebounced: (blockId: string) => void;
   clear: () => void;
   destroy: () => void;
+  flushDebounce?: () => void;
 }
 export declare function useHistory(options: UseHistoryOptions): UseHistoryReturn;
 interface UseBlockActionsOptions {
@@ -223,6 +244,12 @@ interface HistoryInterceptorEditor {
   updateBlock: (blockId: string, updates: Partial<Block>) => void;
   updateSettings: (updates: Partial<TemplateSettings>) => void;
   isBlockLocked: (blockId: string) => boolean;
+  activeLocale?: Ref<string | null>;
+  addLocale?: (locale: string) => void;
+  removeLocale?: (locale: string) => void;
+  setBlockHidden?: (blockId: string, hidden: boolean) => void;
+  resetLocaleFields?: (blockId: string, paths?: string[]) => void;
+  keepTranslations?: (blockId: string, paths: string[]) => void;
 }
 /**
  * Wraps editor mutation methods to record history snapshots before each
@@ -249,11 +276,22 @@ export declare function useHistoryInterceptor(editor: HistoryInterceptorEditor,
  * 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.
+ * 8. Added locales, block and settings layers, then removed locales.
  *
  * 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[];
+/**
+ * Turn operations written against `resolveLocale(base, locale)` into
+ * operations on `base`: changed translatable text becomes `text` (stamped
+ * with the base value's hash), other changed properties become `set`,
+ * structure changes go to the shared tree (a new block's values become
+ * default values, as a paste in that view does). Throws the engine's
+ * OperationError when `ops` don't apply to the projection or include a
+ * whole-template `setContent` replacement.
+ */
+export declare function mapLocalizedOperations(base: TemplateContent, locale: string, ops: Operation[], definitions?: readonly CustomBlockDefinition[]): Operation[];
 /** 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. */
@@ -296,13 +334,13 @@ interface CollaborationRemoteResync {
 }
 /** How {@link UseCollaborationReturn.applyOperations} sends a batch. */
 interface CollaborationApplyOptions {
-  /** Sent as the batch's `origin`: an AI turn produced it (BY9). */
-  origin: "ai";
+  /** Sent as the batch's `origin` when an AI turn produced it; absent for the session's own edits. */
+  origin?: "ai";
   /**
-   * The turn the batch belongs to. Batches of one turn share an undo step
-   * while that step is the newest one.
+   * The AI turn the batch belongs to; absent for the session's own edits.
+   * Batches of one defined turn share the newest undo step.
    */
-  turn: string;
+  turn?: string;
 }
 /** What {@link UseCollaborationReturn.applyOperations} answers. */
 type CollaborationApplyResult = {
@@ -348,8 +386,12 @@ 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. */
+  /** Blocks other sessions hold, keyed by `${blockId}\u0000${locale ?? ""}`. */
   locks: Readonly<Ref<ReadonlyMap<string, BlockLock>>>;
+  locksOf: (blockId: string) => BlockLock[];
+  /** The selected language for lock requests; `null` is the default view. */
+  lockLocale: Readonly<Ref<string | null>>;
+  setLockLocale: (locale: string | null) => void;
   /** `null` before a realtime join, and for a backend without realtime. */
   connection: Readonly<Ref<CollaborationConnectionState | null>>;
   /** The last revision this session confirmed. */
@@ -374,10 +416,10 @@ interface UseCollaborationReturn {
   /** Whether the block exists in the content the backend confirmed. */
   hasConfirmedBlock: (blockId: string) => boolean;
   /**
-   * Apply a batch this editor was handed (an AI turn's) as this session's
-   * own: checked against the view with this session's locks, put on the
-   * canvas, sent with its `origin`, and undone with the rest of its turn. A
-   * refusal changes nothing and sends nothing.
+   * Apply an explicit batch as this session's edit, checking its locks first.
+   * Own edits have a separate undo step and no wire origin. AI batches carry
+   * their origin and share an undo step within a defined turn. A local refusal
+   * changes nothing and sends nothing.
    */
   applyOperations: (ops: Operation[], options: CollaborationApplyOptions) => CollaborationApplyResult;
   destroy: () => void;