@kedataindo/docflow-plugins 0.0.4 → 0.0.5

package/dist/index.d.cts

@@ -1,6 +1,26 @@
 import * as _kedata_indonesia_docflow_core from '@kedataindo/docflow-core';
+import { AIAction, DocsEditorPlugin } from '@kedataindo/docflow-core';
 export { DocsEditorPlugin, FontSizeExtension, SlashCommand, ToolbarItem } from '@kedataindo/docflow-core';
-import { Node } from '@tiptap/core';
+import { Extension, Node, Editor, Mark } from '@tiptap/core';
+import { CiteEngine } from './citations.cjs';
+export { CSL_LOCALE_EN_US, CSL_STYLES, CitationAttrs, CitationCluster, CitationMode, CiteEngineOptions, CslStyleInfo, DEFAULT_CSL_STYLE, buildCitationNodes, nextCitationId, sanitizeCiteprocHtml } from './citations.cjs';
+import { PluginKey } from '@tiptap/pm/state';
+
+declare function getCitationEngine(editor: Editor): CiteEngine | null;
+/**
+ * Carries the document-scoped CiteEngine in editor storage. The engine is
+ * created by citationPlugin.hooks.onInit (from the injected CitationPort) and
+ * disposed on destroy — one instance per editor, never per node.
+ */
+declare const CitationEngineExtension: Extension<any, any>;
+/**
+ * Inline citation — `{ sourceId, locator, … }` only. The visible text is
+ * derived by the CiteEngine at render time and is NEVER stored in the
+ * document (the #1 correctness invariant of the phase-6 design: two clients
+ * with the same sources + style derive identical output through Yjs).
+ */
+declare const CitationNode: Node<any, any>;
+declare const citationPlugin: _kedata_indonesia_docflow_core.DocsEditorPlugin;
 
 declare const formattingPlugin: _kedata_indonesia_docflow_core.DocsEditorPlugin;
 
@@ -32,6 +52,54 @@ declare const pageBreakPlugin: _kedata_indonesia_docflow_core.DocsEditorPlugin;
 declare const FootnoteNode: Node<any, any>;
 declare const footnotePlugin: _kedata_indonesia_docflow_core.DocsEditorPlugin;
 
+interface TocHeading {
+    level: number;
+    text: string;
+    pos: number;
+}
+/**
+ * Walk the doc and collect H1–H3 headings in document order. Same algorithm
+ * as the outline sidebar (TOCSidebar.vue) — positions are captured now and go
+ * stale as the doc is edited; refresh to recapture.
+ */
+declare function collectHeadings(editor: Editor): TocHeading[];
+/** Standalone refresh (refresh button, plugin action): builds and dispatches its own transaction. */
+declare function regenerateToc(editor: Editor): boolean;
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        toc: {
+            /** Insert a table-of-contents block prefilled with the current H1–H3 headings. */
+            insertToc: () => ReturnType;
+            /** Regenerate the entries of every toc block from the current headings. */
+            refreshToc: () => ReturnType;
+        };
+    }
+}
+/**
+ * A page number inside a TOC entry — an inline atom holding the page captured
+ * at generation time (GDocs "with page numbers": stale until refresh). Being
+ * real node content, it serializes to JSON (attrs.page) and to HTML as an
+ * actual `<span>` with the number as text, so exports show it even without
+ * the editor stylesheet.
+ */
+declare const TocPageNumNode: Node<any, any>;
+/**
+ * One TOC entry — a paragraph variant carrying the heading level (CSS indents
+ * by it) and the heading's doc position at generation time (click-to-jump).
+ * Only valid inside a `toc` block (no group), so regular paragraphs never
+ * turn into entries and entries never leak into the doc body.
+ */
+declare const TocEntryNode: Node<any, any>;
+/**
+ * Table of contents — a container block holding real generated entry
+ * paragraphs (one per H1–H3). The entries are real document content, so
+ * export/print/Yjs/undo all work without special-casing; the `0` hole in
+ * renderHTML is what keeps them in the serialized output. The NodeView adds
+ * only the chrome (caption + refresh button) around the contentDOM.
+ */
+declare const TocNode: Node<any, any>;
+declare const tocPlugin: _kedata_indonesia_docflow_core.DocsEditorPlugin;
+
 /**
  * fontSizePlugin — provides the `setFontSize` command action for toolbar use.
  *
@@ -42,6 +110,151 @@ declare const footnotePlugin: _kedata_indonesia_docflow_core.DocsEditorPlugin;
  */
 declare const fontSizePlugin: _kedata_indonesia_docflow_core.DocsEditorPlugin;
 
+declare const textColorPlugin: _kedata_indonesia_docflow_core.DocsEditorPlugin;
+
+declare const highlightPlugin: _kedata_indonesia_docflow_core.DocsEditorPlugin;
+
+/**
+ * AI writing assistance (Phase 7B inline transforms + 7C generation at cursor).
+ *
+ * The two non-negotiables from the phase-7 design:
+ *
+ *  1. Streaming NEVER mutates the document. Tokens accumulate in plugin state
+ *     and render as decorations (highlight + ghost preview). Meta-only
+ *     transactions carry no steps, so a collaborative Yjs doc sees zero churn
+ *     while a preview streams.
+ *  2. Accept is ONE ProseMirror transaction replacing the selection range
+ *     (transform) or inserting at the cursor (generate), so y-prosemirror
+ *     propagates it exactly like a human edit.
+ *
+ * The library never names a URL: the host injects `aiStream` through the
+ * editorContext port (mirroring onImageUpload). Without it, actions are inert.
+ */
+type AIMode = 'transform' | 'generate';
+interface AIPreviewState {
+    mode: AIMode;
+    /** 'prompt' — waiting for the /ai instruction input (7C, generate only). */
+    status: 'prompt' | 'streaming' | 'done' | 'error';
+    /**
+     * Transform: range of the original selection. Generate: collapsed cursor
+     * position. Mapped through doc changes.
+     */
+    from: number;
+    to: number;
+    /** Selection text at start (transform) — detects external edits; '' for generate. */
+    originalText: string;
+    /** Accumulated streamed text. */
+    text: string;
+    action: AIAction;
+    error?: string;
+}
+declare const aiPluginKey: PluginKey<AIPreviewState | null>;
+declare function getAIPreview(editor: Editor): AIPreviewState | null;
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        ai: {
+            /** Start an AI transform over the current selection (streams a preview). */
+            aiTransform: (options: {
+                action: AIAction;
+                prompt?: string;
+            }) => ReturnType;
+            /** Open the /ai prompt input at the cursor (7C). */
+            aiGenerate: () => ReturnType;
+            /** Submit the /ai instruction and stream ghost text at the cursor (7C). */
+            aiPromptSubmit: (options: {
+                prompt: string;
+            }) => ReturnType;
+            /** Apply the streamed text in ONE transaction (replace or insert). */
+            aiAccept: () => ReturnType;
+            /** Discard the preview; the document stays untouched. */
+            aiReject: () => ReturnType;
+        };
+    }
+}
+declare const AIExtension: Extension<any, any>;
+declare const aiPlugin: _kedata_indonesia_docflow_core.DocsEditorPlugin;
+
+/**
+ * Phase 9 P9-4 — comment plugin.
+ *
+ * The mark carries ONLY \`threadId\` — never the anchored text. The
+ * anchored text + position live in the server-side CommentThread
+ * record; the mark is the in-doc pointer to that record. This is the
+ * same invariant the citation plugin uses (Phase 6), extended with
+ * thread id + position.
+ *
+ * ### Anchor survival (v1 — position-based)
+ *
+ * This v1 stores the absolute document position at the time the
+ * comment was created. It survives concurrent edits from OTHER
+ * users until someone deletes or restructures the surrounding text.
+ * For a docflow-style \"inline review comment\" workflow, drift is
+ * rare (commenters don't aggressively edit each other's paragraphs
+ * mid-review) and the rendered side panel shows the snippet + author
+ * so the reader can locate the anchor by content if needed.
+ *
+ * v2 (follow-up PR) replaces the position field with a Yjs
+ * RelativePosition — recommended in the Phase 9 plan §3 spec but
+ * deferred because it requires:
+ *   1. Yjs encode/decode logic over the mark range.
+ *   2. A tombstone strategy when the anchored text is deleted.
+ *   3. A migration path for v1 anchors.
+ * Phase 9 v1 is the user-visible win; v2 is the robustness upgrade.
+ */
+
+/**
+ * The mark carries only the threadId + the position-at-creation-time.
+ * The threadId is the link to the server-side CommentThread record
+ * (route: GET /api/documents/:id/comments/:threadId); the position is
+ * used by the UI to focus / scroll to the anchor when a thread is
+ * selected from the sidebar. Text-content is never stored on the
+ * mark — the server-side thread holds the snippet captured at
+ * creation time.
+ */
+interface CommentMarkAttrs {
+    threadId: string;
+    /** Document position at creation time (volatile — recomputed by the
+     *  editor on each click). v2 will replace this with a Yjs
+     *  RelativePosition. */
+    pos: number;
+}
+declare const CommentMark: Mark<any, any>;
+/**
+ * The comment plugin (Phase 9 P9-4). Library-only — server-side
+ * persistence + role-gated API + UI live in apps/server + apps/web.
+ */
+declare const commentPlugin: DocsEditorPlugin;
+
+/**
+ * Bibliography — a fully derived block. It stores NOTHING (no attrs): the
+ * node view renders the engine's citeproc-sorted entries and repaints on
+ * every engine change (source edit, style switch, citation add/remove).
+ */
+declare const BibliographyNode: Node<any, any>;
+
+interface SlashState {
+    open: boolean;
+    query: string;
+    position: {
+        top: number;
+        left: number;
+    };
+    commands: Array<{
+        name: string;
+        command: string;
+        action: (() => boolean) | null;
+    }>;
+    selectedIndex: number;
+}
+declare let slashState: SlashState;
+declare function onSlashStateChange(fn: () => void): () => void;
+declare function registerSlashCommands(editorId: string, commands: Array<{
+    name: string;
+    command: string;
+}>): void;
+declare const SlashMenuExtension: Extension<any, any>;
+declare const slashMenuPlugin: _kedata_indonesia_docflow_core.DocsEditorPlugin;
+
 declare const defaultPlugins: _kedata_indonesia_docflow_core.DocsEditorPlugin[];
 
-export { FootnoteNode, PageBreak, type PlaceholderPluginOptions, alignmentPlugin, blockquotePlugin, codeBlockPlugin, createPlaceholderPlugin, defaultPlugins, fontSizePlugin, footnotePlugin, formattingPlugin, headingsPlugin, imagePlugin, linkPlugin, listsPlugin, pageBreakPlugin, placeholderPlugin, tablePlugin };
+export { AIExtension, type AIPreviewState, BibliographyNode, CitationEngineExtension, CitationNode, CiteEngine, type CommentMarkAttrs, CommentMark as CommentMarkExtension, FootnoteNode, PageBreak, type PlaceholderPluginOptions, SlashMenuExtension, TocEntryNode, TocNode, TocPageNumNode, aiPlugin, aiPluginKey, alignmentPlugin, blockquotePlugin, citationPlugin, codeBlockPlugin, collectHeadings, commentPlugin, createPlaceholderPlugin, defaultPlugins, fontSizePlugin, footnotePlugin, formattingPlugin, getAIPreview, getCitationEngine, headingsPlugin, highlightPlugin, imagePlugin, linkPlugin, listsPlugin, onSlashStateChange, pageBreakPlugin, placeholderPlugin, regenerateToc, registerSlashCommands, slashMenuPlugin, slashState, tablePlugin, textColorPlugin, tocPlugin };

package/dist/index.d.ts

@@ -1,6 +1,26 @@
 import * as _kedata_indonesia_docflow_core from '@kedataindo/docflow-core';
+import { AIAction, DocsEditorPlugin } from '@kedataindo/docflow-core';
 export { DocsEditorPlugin, FontSizeExtension, SlashCommand, ToolbarItem } from '@kedataindo/docflow-core';
-import { Node } from '@tiptap/core';
+import { Extension, Node, Editor, Mark } from '@tiptap/core';
+import { CiteEngine } from './citations.js';
+export { CSL_LOCALE_EN_US, CSL_STYLES, CitationAttrs, CitationCluster, CitationMode, CiteEngineOptions, CslStyleInfo, DEFAULT_CSL_STYLE, buildCitationNodes, nextCitationId, sanitizeCiteprocHtml } from './citations.js';
+import { PluginKey } from '@tiptap/pm/state';
+
+declare function getCitationEngine(editor: Editor): CiteEngine | null;
+/**
+ * Carries the document-scoped CiteEngine in editor storage. The engine is
+ * created by citationPlugin.hooks.onInit (from the injected CitationPort) and
+ * disposed on destroy — one instance per editor, never per node.
+ */
+declare const CitationEngineExtension: Extension<any, any>;
+/**
+ * Inline citation — `{ sourceId, locator, … }` only. The visible text is
+ * derived by the CiteEngine at render time and is NEVER stored in the
+ * document (the #1 correctness invariant of the phase-6 design: two clients
+ * with the same sources + style derive identical output through Yjs).
+ */
+declare const CitationNode: Node<any, any>;
+declare const citationPlugin: _kedata_indonesia_docflow_core.DocsEditorPlugin;
 
 declare const formattingPlugin: _kedata_indonesia_docflow_core.DocsEditorPlugin;
 
@@ -32,6 +52,54 @@ declare const pageBreakPlugin: _kedata_indonesia_docflow_core.DocsEditorPlugin;
 declare const FootnoteNode: Node<any, any>;
 declare const footnotePlugin: _kedata_indonesia_docflow_core.DocsEditorPlugin;
 
+interface TocHeading {
+    level: number;
+    text: string;
+    pos: number;
+}
+/**
+ * Walk the doc and collect H1–H3 headings in document order. Same algorithm
+ * as the outline sidebar (TOCSidebar.vue) — positions are captured now and go
+ * stale as the doc is edited; refresh to recapture.
+ */
+declare function collectHeadings(editor: Editor): TocHeading[];
+/** Standalone refresh (refresh button, plugin action): builds and dispatches its own transaction. */
+declare function regenerateToc(editor: Editor): boolean;
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        toc: {
+            /** Insert a table-of-contents block prefilled with the current H1–H3 headings. */
+            insertToc: () => ReturnType;
+            /** Regenerate the entries of every toc block from the current headings. */
+            refreshToc: () => ReturnType;
+        };
+    }
+}
+/**
+ * A page number inside a TOC entry — an inline atom holding the page captured
+ * at generation time (GDocs "with page numbers": stale until refresh). Being
+ * real node content, it serializes to JSON (attrs.page) and to HTML as an
+ * actual `<span>` with the number as text, so exports show it even without
+ * the editor stylesheet.
+ */
+declare const TocPageNumNode: Node<any, any>;
+/**
+ * One TOC entry — a paragraph variant carrying the heading level (CSS indents
+ * by it) and the heading's doc position at generation time (click-to-jump).
+ * Only valid inside a `toc` block (no group), so regular paragraphs never
+ * turn into entries and entries never leak into the doc body.
+ */
+declare const TocEntryNode: Node<any, any>;
+/**
+ * Table of contents — a container block holding real generated entry
+ * paragraphs (one per H1–H3). The entries are real document content, so
+ * export/print/Yjs/undo all work without special-casing; the `0` hole in
+ * renderHTML is what keeps them in the serialized output. The NodeView adds
+ * only the chrome (caption + refresh button) around the contentDOM.
+ */
+declare const TocNode: Node<any, any>;
+declare const tocPlugin: _kedata_indonesia_docflow_core.DocsEditorPlugin;
+
 /**
  * fontSizePlugin — provides the `setFontSize` command action for toolbar use.
  *
@@ -42,6 +110,151 @@ declare const footnotePlugin: _kedata_indonesia_docflow_core.DocsEditorPlugin;
  */
 declare const fontSizePlugin: _kedata_indonesia_docflow_core.DocsEditorPlugin;
 
+declare const textColorPlugin: _kedata_indonesia_docflow_core.DocsEditorPlugin;
+
+declare const highlightPlugin: _kedata_indonesia_docflow_core.DocsEditorPlugin;
+
+/**
+ * AI writing assistance (Phase 7B inline transforms + 7C generation at cursor).
+ *
+ * The two non-negotiables from the phase-7 design:
+ *
+ *  1. Streaming NEVER mutates the document. Tokens accumulate in plugin state
+ *     and render as decorations (highlight + ghost preview). Meta-only
+ *     transactions carry no steps, so a collaborative Yjs doc sees zero churn
+ *     while a preview streams.
+ *  2. Accept is ONE ProseMirror transaction replacing the selection range
+ *     (transform) or inserting at the cursor (generate), so y-prosemirror
+ *     propagates it exactly like a human edit.
+ *
+ * The library never names a URL: the host injects `aiStream` through the
+ * editorContext port (mirroring onImageUpload). Without it, actions are inert.
+ */
+type AIMode = 'transform' | 'generate';
+interface AIPreviewState {
+    mode: AIMode;
+    /** 'prompt' — waiting for the /ai instruction input (7C, generate only). */
+    status: 'prompt' | 'streaming' | 'done' | 'error';
+    /**
+     * Transform: range of the original selection. Generate: collapsed cursor
+     * position. Mapped through doc changes.
+     */
+    from: number;
+    to: number;
+    /** Selection text at start (transform) — detects external edits; '' for generate. */
+    originalText: string;
+    /** Accumulated streamed text. */
+    text: string;
+    action: AIAction;
+    error?: string;
+}
+declare const aiPluginKey: PluginKey<AIPreviewState | null>;
+declare function getAIPreview(editor: Editor): AIPreviewState | null;
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        ai: {
+            /** Start an AI transform over the current selection (streams a preview). */
+            aiTransform: (options: {
+                action: AIAction;
+                prompt?: string;
+            }) => ReturnType;
+            /** Open the /ai prompt input at the cursor (7C). */
+            aiGenerate: () => ReturnType;
+            /** Submit the /ai instruction and stream ghost text at the cursor (7C). */
+            aiPromptSubmit: (options: {
+                prompt: string;
+            }) => ReturnType;
+            /** Apply the streamed text in ONE transaction (replace or insert). */
+            aiAccept: () => ReturnType;
+            /** Discard the preview; the document stays untouched. */
+            aiReject: () => ReturnType;
+        };
+    }
+}
+declare const AIExtension: Extension<any, any>;
+declare const aiPlugin: _kedata_indonesia_docflow_core.DocsEditorPlugin;
+
+/**
+ * Phase 9 P9-4 — comment plugin.
+ *
+ * The mark carries ONLY \`threadId\` — never the anchored text. The
+ * anchored text + position live in the server-side CommentThread
+ * record; the mark is the in-doc pointer to that record. This is the
+ * same invariant the citation plugin uses (Phase 6), extended with
+ * thread id + position.
+ *
+ * ### Anchor survival (v1 — position-based)
+ *
+ * This v1 stores the absolute document position at the time the
+ * comment was created. It survives concurrent edits from OTHER
+ * users until someone deletes or restructures the surrounding text.
+ * For a docflow-style \"inline review comment\" workflow, drift is
+ * rare (commenters don't aggressively edit each other's paragraphs
+ * mid-review) and the rendered side panel shows the snippet + author
+ * so the reader can locate the anchor by content if needed.
+ *
+ * v2 (follow-up PR) replaces the position field with a Yjs
+ * RelativePosition — recommended in the Phase 9 plan §3 spec but
+ * deferred because it requires:
+ *   1. Yjs encode/decode logic over the mark range.
+ *   2. A tombstone strategy when the anchored text is deleted.
+ *   3. A migration path for v1 anchors.
+ * Phase 9 v1 is the user-visible win; v2 is the robustness upgrade.
+ */
+
+/**
+ * The mark carries only the threadId + the position-at-creation-time.
+ * The threadId is the link to the server-side CommentThread record
+ * (route: GET /api/documents/:id/comments/:threadId); the position is
+ * used by the UI to focus / scroll to the anchor when a thread is
+ * selected from the sidebar. Text-content is never stored on the
+ * mark — the server-side thread holds the snippet captured at
+ * creation time.
+ */
+interface CommentMarkAttrs {
+    threadId: string;
+    /** Document position at creation time (volatile — recomputed by the
+     *  editor on each click). v2 will replace this with a Yjs
+     *  RelativePosition. */
+    pos: number;
+}
+declare const CommentMark: Mark<any, any>;
+/**
+ * The comment plugin (Phase 9 P9-4). Library-only — server-side
+ * persistence + role-gated API + UI live in apps/server + apps/web.
+ */
+declare const commentPlugin: DocsEditorPlugin;
+
+/**
+ * Bibliography — a fully derived block. It stores NOTHING (no attrs): the
+ * node view renders the engine's citeproc-sorted entries and repaints on
+ * every engine change (source edit, style switch, citation add/remove).
+ */
+declare const BibliographyNode: Node<any, any>;
+
+interface SlashState {
+    open: boolean;
+    query: string;
+    position: {
+        top: number;
+        left: number;
+    };
+    commands: Array<{
+        name: string;
+        command: string;
+        action: (() => boolean) | null;
+    }>;
+    selectedIndex: number;
+}
+declare let slashState: SlashState;
+declare function onSlashStateChange(fn: () => void): () => void;
+declare function registerSlashCommands(editorId: string, commands: Array<{
+    name: string;
+    command: string;
+}>): void;
+declare const SlashMenuExtension: Extension<any, any>;
+declare const slashMenuPlugin: _kedata_indonesia_docflow_core.DocsEditorPlugin;
+
 declare const defaultPlugins: _kedata_indonesia_docflow_core.DocsEditorPlugin[];
 
-export { FootnoteNode, PageBreak, type PlaceholderPluginOptions, alignmentPlugin, blockquotePlugin, codeBlockPlugin, createPlaceholderPlugin, defaultPlugins, fontSizePlugin, footnotePlugin, formattingPlugin, headingsPlugin, imagePlugin, linkPlugin, listsPlugin, pageBreakPlugin, placeholderPlugin, tablePlugin };
+export { AIExtension, type AIPreviewState, BibliographyNode, CitationEngineExtension, CitationNode, CiteEngine, type CommentMarkAttrs, CommentMark as CommentMarkExtension, FootnoteNode, PageBreak, type PlaceholderPluginOptions, SlashMenuExtension, TocEntryNode, TocNode, TocPageNumNode, aiPlugin, aiPluginKey, alignmentPlugin, blockquotePlugin, citationPlugin, codeBlockPlugin, collectHeadings, commentPlugin, createPlaceholderPlugin, defaultPlugins, fontSizePlugin, footnotePlugin, formattingPlugin, getAIPreview, getCitationEngine, headingsPlugin, highlightPlugin, imagePlugin, linkPlugin, listsPlugin, onSlashStateChange, pageBreakPlugin, placeholderPlugin, regenerateToc, registerSlashCommands, slashMenuPlugin, slashState, tablePlugin, textColorPlugin, tocPlugin };