@tessera-editor/core 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import * as _tiptap_core from '@tiptap/core';
-import { Node, Mark, Extension, Editor, Range, JSONContent, Extensions } from '@tiptap/core';
+import { Node, Mark, Extension, Editor, Range, Extensions, JSONContent } from '@tiptap/core';
+export { Editor, JSONContent } from '@tiptap/core';
 import * as _tiptap_extension_table from '@tiptap/extension-table';
 export { TableRow as AiTableRow } from '@tiptap/extension-table';
 import * as _tiptap_pm_model from '@tiptap/pm/model';
@@ -94,6 +95,8 @@ declare module '@tiptap/core' {
             setColumnType: (index: number, kind: TableColumnKind) => ReturnType;
             /** Stable-sort body rows by column `index`. */
             sortTableByColumn: (index: number, direction: 'asc' | 'desc') => ReturnType;
+            /** Strip stray hidden text from every typed (non-text) cell. */
+            normalizeTypedCells: () => ReturnType;
         };
     }
 }
@@ -182,24 +185,6 @@ declare function listCommentRanges(state: _tiptap_pm_state.EditorState): {
 }[];
 declare const CommentCommands: Extension<any, any>;
 
-/**
- * Placeholder mark (v1.1, Slite's 占位符): dashed-underline token marking a
- * spot to fill in later — text / person / date / doc-link. ⌘⌥P toggles it on
- * a selection; slash items insert ready-made tokens.
- */
-type PlaceholderKind = 'text' | 'person' | 'date' | 'doc';
-declare const PlaceholderMark: Mark<any, any>;
-declare module '@tiptap/core' {
-    interface Commands<ReturnType> {
-        tesseraPlaceholder: {
-            togglePlaceholderMark: (kind?: PlaceholderKind) => ReturnType;
-            /** Insert a placeholder token at the caret (selection replaced). */
-            insertPlaceholderToken: (kind: PlaceholderKind, label: string) => ReturnType;
-        };
-    }
-}
-declare const PlaceholderCommands: Extension<any, any>;
-
 /**
  * Tessera-specific input rules beyond the StarterKit defaults:
  *   `[] ` + typing  → task list (mirrors Slite's trigger)
@@ -229,7 +214,6 @@ declare module '@tiptap/core' {
         'tessera:findPanel': Record<string, never>;
         'tessera:insertImage': Record<string, never>;
         'tessera:askPanel': Record<string, never>;
-        'tessera:historyPanel': Record<string, never>;
         'tessera:commentPanel': Record<string, never>;
     }
 }
@@ -327,6 +311,8 @@ declare const tesseraMessages: {
         readonly highlightNone: "无高亮";
         readonly linkPlaceholder: "链接地址…";
         readonly linkApply: "应用";
+        readonly linkSave: "保存";
+        readonly linkTextPlaceholder: "显示文字…";
         readonly linkRemove: "移除链接";
         readonly linkOpen: "打开";
         readonly emptyLineExpand: "展开全部块";
@@ -342,6 +328,10 @@ declare const tesseraMessages: {
         readonly imageAlignLeft: "左对齐";
         readonly imageAlignCenter: "居中";
         readonly imageAlignFull: "全宽";
+        readonly imageZoomIn: "放大";
+        readonly imageZoomOut: "缩小";
+        readonly imageZoomReset: "重置";
+        readonly imageZoomHint: "Ctrl+滚轮缩放 · 双击图片复位";
         readonly aiTitle: "AI";
         readonly aiAskPlaceholder: "针对本文档提问…";
         readonly aiSend: "发送";
@@ -378,16 +368,6 @@ declare const tesseraMessages: {
         readonly tableCopyCsv: "复制为 CSV";
         readonly tableToggleHeader: "切换表头";
         readonly cellEmpty: "空";
-        readonly itemHistory: "版本历史";
-        readonly historyTitle: "版本历史";
-        readonly historyEmpty: "暂无快照（编辑后空闲自动保存，或手动捕获）";
-        readonly historyCapture: "捕获快照";
-        readonly historyRestore: "恢复此版本";
-        readonly historyCurrent: "当前";
-        readonly historyDiffAdded: "新增";
-        readonly historyDiffRemoved: "删除";
-        readonly historyDiffChanged: "修改";
-        readonly historyConfirmRestore: "恢复到该版本？当前内容将被替换（可撤销）";
         readonly tooltipCommentV11: "评论";
         readonly commentTitle: "评论";
         readonly commentEmpty: "暂无评论";
@@ -407,9 +387,6 @@ declare const tesseraMessages: {
         readonly embedInvalid: "无效链接";
         readonly embedOpen: "打开原链接";
         readonly tocEmpty: "暂无标题——添加 H1–H4 后自动出现";
-        readonly placeholderText: "待补充";
-        readonly placeholderPerson: "待填人";
-        readonly placeholderDate: "待填日期";
         readonly menuCopyAnchor: "复制锚链接";
         readonly menuCopyBlockId: "复制块 ID";
         readonly menuDeleteBlock: "删除此块";
@@ -467,6 +444,8 @@ declare const tesseraMessages: {
         readonly highlightNone: "No highlight";
         readonly linkPlaceholder: "Link URL…";
         readonly linkApply: "Apply";
+        readonly linkSave: "Save";
+        readonly linkTextPlaceholder: "Link text…";
         readonly linkRemove: "Remove link";
         readonly linkOpen: "Open";
         readonly emptyLineExpand: "Show all blocks";
@@ -482,6 +461,10 @@ declare const tesseraMessages: {
         readonly imageAlignLeft: "Align left";
         readonly imageAlignCenter: "Center";
         readonly imageAlignFull: "Full width";
+        readonly imageZoomIn: "Zoom in";
+        readonly imageZoomOut: "Zoom out";
+        readonly imageZoomReset: "Reset zoom";
+        readonly imageZoomHint: "Ctrl+scroll to zoom · double-click to reset";
         readonly aiTitle: "AI";
         readonly aiAskPlaceholder: "Ask about this doc…";
         readonly aiSend: "Send";
@@ -518,16 +501,6 @@ declare const tesseraMessages: {
         readonly tableCopyCsv: "Copy as CSV";
         readonly tableToggleHeader: "Toggle header row";
         readonly cellEmpty: "Empty";
-        readonly itemHistory: "Version history";
-        readonly historyTitle: "Version history";
-        readonly historyEmpty: "No snapshots yet (auto-captured when idle, or capture manually)";
-        readonly historyCapture: "Capture snapshot";
-        readonly historyRestore: "Restore this version";
-        readonly historyCurrent: "Current";
-        readonly historyDiffAdded: "Added";
-        readonly historyDiffRemoved: "Removed";
-        readonly historyDiffChanged: "Changed";
-        readonly historyConfirmRestore: "Restore this version? Current content will be replaced (undoable)";
         readonly tooltipCommentV11: "Comment";
         readonly commentTitle: "Comments";
         readonly commentEmpty: "No comments yet";
@@ -547,17 +520,16 @@ declare const tesseraMessages: {
         readonly embedInvalid: "Invalid URL";
         readonly embedOpen: "Open original";
         readonly tocEmpty: "No headings yet — add H1–H4 and they appear here";
-        readonly placeholderText: "to fill in";
-        readonly placeholderPerson: "assignee";
-        readonly placeholderDate: "due date";
         readonly menuCopyAnchor: "Copy anchor link";
         readonly menuCopyBlockId: "Copy block ID";
         readonly menuDeleteBlock: "Delete block";
     };
 };
 type TesseraMessageKey = keyof typeof tesseraMessages['zh-CN'];
+/** Host-side overrides of individual UI strings (merged over the dictionary). */
+type TesseraMessageOverrides = Partial<Record<TesseraMessageKey, string>>;
 type TesseraTranslator = (key: TesseraMessageKey) => string;
-declare function createTesseraT(locale?: TesseraLocale): TesseraTranslator;
+declare function createTesseraT(locale?: TesseraLocale, overrides?: TesseraMessageOverrides): TesseraTranslator;
 
 /**
  * Slash menu (acceptance §1): framework-neutral extension built on
@@ -587,7 +559,17 @@ interface SlashMenuOptions {
     }) => SlashMenuItem[];
     includeAiItems?: boolean;
     render?: SlashRenderFactory;
-}
+    /**
+     * Host block policy (mirrors `TesseraPresetOptions.excludeBlocks`): drop
+     * default items whose node type is excluded, so the menu never offers a
+     * block the editor cannot represent.
+     */
+    excludeItems?: string[];
+}
+/** Slash item id → the node type it produces. */
+declare function slashItemNodeName(item: SlashMenuItem): string;
+/** Drop default items whose node type is excluded by the host. */
+declare function filterSlashItems(items: SlashMenuItem[], excludeBlocks?: string[]): SlashMenuItem[];
 /** Default block items — mirrors the Slite slash palette for the M1 scope. */
 declare function defaultSlashItems(t: TesseraTranslator): SlashMenuItem[];
 declare const SlashMenu: Extension<SlashMenuOptions, any>;
@@ -619,102 +601,6 @@ interface EmojiMenuOptions {
 }
 declare const EmojiMenu: Extension<EmojiMenuOptions, any>;
 
-/**
- * Injected services (ADR-0001 family): the component family never performs
- * network or storage I/O itself. Hosts provide implementations through the
- * binding; the editor reads them from `editor.storage.tesseraServices`.
- */
-interface UploadedAsset {
-    url: string;
-    name?: string;
-    mime?: string;
-}
-interface UploadService {
-    uploadImage(file: File | Blob): Promise<UploadedAsset>;
-    uploadFile?(file: File | Blob): Promise<UploadedAsset>;
-}
-/** v1.1: persistent version history storage (snapshots keyed by time). */
-interface DocSnapshot {
-    id: string;
-    ts: number;
-    doc: JSONContent;
-    label?: string;
-}
-interface StorageService {
-    saveSnapshot(snapshot: DocSnapshot): Promise<void>;
-    listSnapshots(): Promise<DocSnapshot[]>;
-    deleteSnapshot?(id: string): Promise<void>;
-}
-/** v1.1: inline comments. */
-interface CommentEntry {
-    id: string;
-    authorId: string;
-    authorName: string;
-    text: string;
-    ts: number;
-}
-interface CommentThread {
-    id: string;
-    quote: string;
-    resolved: boolean;
-    createdAt: number;
-    entries: CommentEntry[];
-}
-interface CommentStore {
-    list(): Promise<CommentThread[]>;
-    upsert(thread: CommentThread): Promise<void>;
-    remove(id: string): Promise<void>;
-}
-/** v1.1: who is editing (author of comments / history labels). */
-interface IdentityService {
-    getCurrentUser(): {
-        id: string;
-        name: string;
-    } | null;
-}
-interface TesseraServicesStorage {
-    upload?: UploadService;
-    storage?: StorageService;
-    comments?: CommentStore;
-    identity?: IdentityService;
-}
-declare const TesseraServices: Extension<any, any>;
-type ServicesEditor = {
-    storage: unknown;
-};
-declare function getUploadService(editor: ServicesEditor): UploadService | undefined;
-declare function getStorageService(editor: ServicesEditor): StorageService | undefined;
-declare function getCommentStore(editor: ServicesEditor): CommentStore | undefined;
-declare function getIdentityService(editor: ServicesEditor): IdentityService | undefined;
-
-/**
- * Version history capture (v1.1): snapshots the canonical JSON into the
- * injected StorageService. Auto-capture fires after `idleMs` of inactivity
- * (Slite: 5 minutes); manual capture is always available as a command.
- */
-interface HistorySnapshotOptions {
-    /** idle window before auto-capture (default 5 minutes) */
-    idleMs?: number;
-    /** minimum ms between two auto-captures (default 60s) */
-    minIntervalMs?: number;
-    /** snapshot label source */
-    label?: () => string | undefined;
-}
-declare module '@tiptap/core' {
-    interface Commands<ReturnType> {
-        tesseraHistory: {
-            captureSnapshot: (label?: string) => ReturnType;
-        };
-    }
-    interface EditorEvents {
-        'tessera:snapshotSaved': {
-            snapshot: DocSnapshot;
-        };
-    }
-}
-declare const historyKey: PluginKey<any>;
-declare const TesseraHistory: Extension<HistorySnapshotOptions, any>;
-
 /**
  * Block context menu (v1.1): right-click a block → `tessera:blockMenu` event.
  * The binding renders the menu (copy anchor link / copy block id / delete;
@@ -815,18 +701,122 @@ declare function deleteBlockById(editor: Editor, id: string): boolean;
 /** Anchor URL for a block id (`#block-<id>` on the current page). */
 declare function blockAnchorUrl(blockId: string): string;
 
+/**
+ * Link click-to-edit: clicking a link opens a panel with its display text
+ * and href, and offers unlink (degrade to plain text). The doc semantics
+ * live here so React and Vue bindings behave identically.
+ */
+interface TesseraLinkRange {
+    from: number;
+    to: number;
+    text: string;
+    href: string;
+}
+/** Resolve the link mark range under/ending at `pos` (defaults to the caret). */
+declare function findLinkRange(editor: Editor, pos?: number): TesseraLinkRange | null;
+/**
+ * Save an edit in ONE transaction (single undo step): update href, and when
+ * the display text changed replace the range content while keeping the
+ * text's other marks. An empty href degrades to unlink.
+ */
+declare function saveLinkRange(editor: Editor, range: TesseraLinkRange, next: {
+    text: string;
+    href: string;
+}): void;
+/** Strip the link mark, keeping the display text as plain text. */
+declare function removeLinkRange(editor: Editor, range: TesseraLinkRange): void;
+
 interface TesseraPresetOptions {
     locale?: TesseraLocale;
-    /** v1.1 history auto-capture idle window (playground uses a short one) */
-    historyIdleMs?: number;
+    /** Empty-paragraph placeholder text (default: the i18n `placeholderEmpty` string). */
+    placeholder?: string;
+    /** Per-key overrides of the built-in UI dictionary (slash items, tooltips…). */
+    messages?: TesseraMessageOverrides;
+    /**
+     * Host block policy: top-level block types to exclude entirely. An excluded
+     * node is dropped from the extension preset, the slash menu, UniqueID's id
+     * list and the keyboard shortcuts that produce it — the editor cannot create
+     * it and rejects its JSON on parse. Recognized names: `hint`, `collapsible`,
+     * `embedBlock`, `tocBlock`, `horizontalRule`, `table`, `taskList`,
+     * `imageBlock`.
+     */
+    excludeBlocks?: string[];
 }
 /** Node types that receive stable block IDs (write-back protocol basis). */
 declare const ID_BLOCK_TYPES: string[];
+/**
+ * Every top-level block type the FULL preset can emit into the canonical JSON.
+ * Hosts gating saves server-side (a block whitelist) should align their list
+ * with this one; `excludeBlocks` trims the editor to match a narrower policy.
+ * (Nested containers — listItem/taskItem/tableRow — are not listed: they only
+ * appear inside their parents.)
+ */
+declare const SUPPORTED_BLOCK_TYPES: readonly ["paragraph", "heading", "bulletList", "orderedList", "taskList", "blockquote", "codeBlock", "horizontalRule", "imageBlock", "table", "hint", "collapsible", "embedBlock", "tocBlock"];
 /**
  * The Tessera extension preset: framework-agnostic, UI-free. The binding layers
  * rendering (slash menu renderer, node views) on top of this.
  */
 declare function createTesseraExtensions(options?: TesseraPresetOptions): Extensions;
+/**
+ * ProseMirror schema for the preset without instantiating an editor — the
+ * headless entry for hosts that only need format conversion (markdown ⇄ JSON).
+ * Honors `excludeBlocks` so conversion always agrees with the mounted editor.
+ */
+declare function createTesseraSchema(options?: TesseraPresetOptions): Schema;
+
+/**
+ * Injected services (ADR-0001 family): the component family never performs
+ * network or storage I/O itself. Hosts provide implementations through the
+ * binding; the editor reads them from `editor.storage.tesseraServices`.
+ */
+interface UploadedAsset {
+    url: string;
+    name?: string;
+    mime?: string;
+}
+interface UploadService {
+    uploadImage(file: File | Blob): Promise<UploadedAsset>;
+    uploadFile?(file: File | Blob): Promise<UploadedAsset>;
+}
+/** v1.1: inline comments. */
+interface CommentEntry {
+    id: string;
+    authorId: string;
+    authorName: string;
+    text: string;
+    ts: number;
+}
+interface CommentThread {
+    id: string;
+    quote: string;
+    resolved: boolean;
+    createdAt: number;
+    entries: CommentEntry[];
+}
+interface CommentStore {
+    list(): Promise<CommentThread[]>;
+    upsert(thread: CommentThread): Promise<void>;
+    remove(id: string): Promise<void>;
+}
+/** v1.1: who is editing (comment authorship). */
+interface IdentityService {
+    getCurrentUser(): {
+        id: string;
+        name: string;
+    } | null;
+}
+interface TesseraServicesStorage {
+    upload?: UploadService;
+    comments?: CommentStore;
+    identity?: IdentityService;
+}
+declare const TesseraServices: Extension<any, any>;
+type ServicesEditor = {
+    storage: unknown;
+};
+declare function getUploadService(editor: ServicesEditor): UploadService | undefined;
+declare function getCommentStore(editor: ServicesEditor): CommentStore | undefined;
+declare function getIdentityService(editor: ServicesEditor): IdentityService | undefined;
 
 declare function createMarkdownSerializer(schema: Schema): MarkdownSerializer;
 /** Canonical JSON (or doc node) → Markdown. */
@@ -836,32 +826,6 @@ declare function markdownToDoc(markdown: string, schema: Schema): JSONContent;
 /** Strip volatile/whitespace-irrelevant fields for round-trip comparisons. */
 declare function stableJson(json: JSONContent): JSONContent;
 
-/**
- * Document diff (v1.1 history panel): block-level via stable ids (LCS on the
- * id sequence) + word-level inside changed text blocks. Pure utility — the
- * panel renders it.
- */
-interface WordDiffPart {
-    text: string;
-    type: 'same' | 'add' | 'del';
-}
-interface BlockDiffEntry {
-    kind: 'added' | 'removed' | 'changed' | 'unchanged';
-    id?: string;
-    before?: JSONContent;
-    after?: JSONContent;
-    wordDiff?: WordDiffPart[];
-}
-/** Classic LCS word diff with a size guard. */
-declare function wordDiff(beforeText: string, afterText: string): WordDiffPart[];
-declare function diffDocs(before: JSONContent, after: JSONContent): BlockDiffEntry[];
-/** Compact summary for the panel header. */
-declare function diffSummary(entries: BlockDiffEntry[]): {
-    added: number;
-    removed: number;
-    changed: number;
-};
-
 /**
  * Write-back protocol (ADR-0001 / product-definition §4): AI and host code
  * mutate the document by stable block IDs — never whole-doc rewrites.
@@ -900,4 +864,4 @@ declare function removeBlocks(editor: Editor, ids: string[]): boolean;
 /** Read a block (and its subtree) by id as canonical JSON. */
 declare function getBlockJson(editor: Editor, id: string): JSONContent | null;
 
-export { AiAttribution, type AiAttributionOptions, AiTable, AiTableCell, AiTableHeader, type AppendBlocksOptions, BlockContextMenu, type BlockDiffEntry, type BlockHandle, Collapsible, CollapsibleContent, type CollapsibleOptions, CollapsibleSummary, CommentCommands, type CommentEntry, CommentMark, type CommentStore, type CommentThread, type DocSnapshot, EMOJI_ITEMS, EmbedBlock, type EmojiItem, EmojiMenu, type EmojiMenuOptions, type FindMatch, type FindReplaceState, Hint, type HintOptions, type HintVariant, type HistorySnapshotOptions, ID_BLOCK_TYPES, type IdentityService, type ImageAlign, ImageBlock, type ImageBlockOptions, type ModifyRangeOptions, PlaceholderCommands, type PlaceholderKind, PlaceholderMark, SlashMenu, type SlashMenuItem, type SlashMenuOptions, type SlashRenderFactory, type StorageService, TABLE_COLUMN_KINDS, type TableColumnKind, TesseraFindReplace, TesseraGallery, TesseraHistory, TesseraInputRules, type TesseraLocale, type TesseraMessageKey, TesseraMetrics, type TesseraMetricsSnapshot, type TesseraPresetOptions, TesseraServices, type TesseraServicesStorage, TesseraShortcuts, type TesseraTranslator, TesseraWordPaste, TocBlock, type UploadService, type UploadedAsset, type WordDiffPart, appendBlocks, blockAnchorUrl, cleanWordHtml, createMarkdownSerializer, createTesseraExtensions, createTesseraT, defaultSlashItems, deleteBlockById, diffDocs, diffSummary, docToMarkdown, filterEmojiItems, findBlockPosById, findGalleryRuns, findReplaceKey, galleryKey, getBlockJson, getCommentStore, getIdentityService, getStorageService, getTesseraMetrics, getTopLevelBlocks, getUploadService, historyKey, isWordHtml, listCommentRanges, markdownToDoc, measureTesseraMetrics, modifyRange, normalizeTypes, removeBlocks, stableJson, tableNodeToCsv, tableToCsvAt, tesseraMessages, wordDiff };
+export { AiAttribution, type AiAttributionOptions, AiTable, AiTableCell, AiTableHeader, type AppendBlocksOptions, BlockContextMenu, type BlockHandle, Collapsible, CollapsibleContent, type CollapsibleOptions, CollapsibleSummary, CommentCommands, type CommentEntry, CommentMark, type CommentStore, type CommentThread, EMOJI_ITEMS, EmbedBlock, type EmojiItem, EmojiMenu, type EmojiMenuOptions, type FindMatch, type FindReplaceState, Hint, type HintOptions, type HintVariant, ID_BLOCK_TYPES, type IdentityService, type ImageAlign, ImageBlock, type ImageBlockOptions, type ModifyRangeOptions, SUPPORTED_BLOCK_TYPES, SlashMenu, type SlashMenuItem, type SlashMenuOptions, type SlashRenderFactory, TABLE_COLUMN_KINDS, type TableColumnKind, TesseraFindReplace, TesseraGallery, TesseraInputRules, type TesseraLinkRange, type TesseraLocale, type TesseraMessageKey, type TesseraMessageOverrides, TesseraMetrics, type TesseraMetricsSnapshot, type TesseraPresetOptions, TesseraServices, type TesseraServicesStorage, TesseraShortcuts, type TesseraTranslator, TesseraWordPaste, TocBlock, type UploadService, type UploadedAsset, appendBlocks, blockAnchorUrl, cleanWordHtml, createMarkdownSerializer, createTesseraExtensions, createTesseraSchema, createTesseraT, defaultSlashItems, deleteBlockById, docToMarkdown, filterEmojiItems, filterSlashItems, findBlockPosById, findGalleryRuns, findLinkRange, findReplaceKey, galleryKey, getBlockJson, getCommentStore, getIdentityService, getTesseraMetrics, getTopLevelBlocks, getUploadService, isWordHtml, listCommentRanges, markdownToDoc, measureTesseraMetrics, modifyRange, normalizeTypes, removeBlocks, removeLinkRange, saveLinkRange, slashItemNodeName, stableJson, tableNodeToCsv, tableToCsvAt, tesseraMessages };