@sendbird/actionbook-core 0.7.2

package/dist/types-rEXLrfo_.d.ts

@@ -0,0 +1,191 @@
+type BoldMark = {
+    readonly type: 'bold';
+};
+type ItalicMark = {
+    readonly type: 'italic';
+};
+type UnderlineMark = {
+    readonly type: 'underline';
+};
+type StrikethroughMark = {
+    readonly type: 'strikethrough';
+};
+type CodeMark = {
+    readonly type: 'code';
+};
+type LinkMark = {
+    readonly type: 'link';
+    readonly href: string;
+    readonly title?: string;
+};
+type Mark = BoldMark | ItalicMark | UnderlineMark | StrikethroughMark | CodeMark | LinkMark;
+type TextNode = {
+    readonly type: 'text';
+    readonly text: string;
+    readonly marks?: readonly Mark[];
+};
+type ResourceTagNode = {
+    readonly type: 'resourceTag';
+    readonly tagType: 'tool' | 'manual' | 'agent_message_template' | 'handoff' | 'time_diff';
+    readonly resourceId: string;
+    readonly text: string;
+};
+type JumpPointNode = {
+    readonly type: 'jumpPoint';
+    readonly id: string;
+};
+type HardBreakNode = {
+    readonly type: 'hardBreak';
+};
+type JinjaIfBranch<T> = {
+    readonly branchType: 'if' | 'elif' | 'else';
+    readonly condition?: string;
+    readonly content: readonly T[];
+};
+type JinjaIfInlineNode = {
+    readonly type: 'jinjaIfInline';
+    readonly branches: readonly JinjaIfBranch<InlineNode>[];
+};
+type InlineNode = TextNode | ResourceTagNode | JumpPointNode | HardBreakNode | JinjaIfInlineNode;
+type ParagraphNode = {
+    readonly type: 'paragraph';
+    readonly content: readonly InlineNode[];
+};
+type HeadingNode = {
+    readonly type: 'heading';
+    readonly level: 1 | 2 | 3 | 4 | 5 | 6;
+    readonly content: readonly InlineNode[];
+};
+type ListItemNode = {
+    readonly type: 'listItem';
+    readonly checked?: boolean | null;
+    readonly content: readonly BlockNode[];
+};
+type BulletListNode = {
+    readonly type: 'bulletList';
+    readonly content: readonly ListItemNode[];
+};
+type OrderedListNode = {
+    readonly type: 'orderedList';
+    readonly start: number;
+    readonly content: readonly ListItemNode[];
+};
+type BlockquoteNode = {
+    readonly type: 'blockquote';
+    readonly content: readonly BlockNode[];
+};
+type HorizontalRuleNode = {
+    readonly type: 'horizontalRule';
+};
+type TableCellNode = {
+    readonly type: 'tableCell';
+    readonly header?: boolean;
+    readonly content: readonly InlineNode[];
+};
+type TableRowNode = {
+    readonly type: 'tableRow';
+    readonly content: readonly TableCellNode[];
+};
+type TableNode = {
+    readonly type: 'table';
+    readonly content: readonly TableRowNode[];
+};
+type JinjaIfBlockNode = {
+    readonly type: 'jinjaIfBlock';
+    readonly branches: readonly JinjaIfBranch<BlockNode>[];
+};
+type BlockNode = ParagraphNode | HeadingNode | BulletListNode | OrderedListNode | ListItemNode | BlockquoteNode | HorizontalRuleNode | TableNode | JinjaIfBlockNode;
+type DocumentNode = {
+    readonly type: 'doc';
+    readonly content: readonly BlockNode[];
+};
+type AstNode = DocumentNode | BlockNode | InlineNode | TableRowNode | TableCellNode;
+type NodePath = readonly number[];
+declare const RESOURCE_TAG_TYPES: readonly ["tool", "manual", "agent_message_template", "handoff", "time_diff"];
+type ResourceTagType = (typeof RESOURCE_TAG_TYPES)[number];
+declare const JUMP_POINT_ID_PATTERN: RegExp;
+
+/**
+ * Convert ProseMirror/Tiptap JSONContent to ActionbookAST.
+ *
+ * This handles the legacy editor_data format stored in LogicV2.
+ */
+
+type JSONContent = {
+    type?: string;
+    attrs?: Record<string, unknown>;
+    content?: JSONContent[];
+    marks?: {
+        type: string;
+        attrs?: Record<string, unknown>;
+    }[];
+    text?: string;
+};
+declare function fromProseMirrorJSON(pmJSON: JSONContent): DocumentNode;
+
+type LintSeverity = 'error' | 'warning' | 'info';
+type LintResult = {
+    readonly ruleId: string;
+    readonly severity: LintSeverity;
+    readonly message: string;
+    readonly path?: NodePath;
+    readonly suggestion?: string;
+};
+type LintVisitorHandler = (node: AstNode, path?: NodePath) => void;
+/**
+ * Optional visitor-based interface for LintRule.
+ * When a rule provides `buildVisitor`, the runner will invoke it as part of a
+ * single combined AST traversal instead of running `rule.run()` per-rule.
+ *
+ * `buildVisitor` returns per-node-type handlers and a `finish()` function
+ * that collects accumulated results after the traversal completes.
+ */
+type LintVisitorFactory = (ctx: LintContext) => {
+    visitor: Partial<Record<string, LintVisitorHandler>>;
+    finish: (severity: LintSeverity) => LintResult[];
+};
+type LintRule = {
+    readonly id: string;
+    readonly description: string;
+    readonly defaultSeverity: LintSeverity;
+    readonly run: (doc: DocumentNode, ctx: LintContext) => LintResult[];
+    /**
+     * Optional: optimized visitor-based implementation.
+     * When present, the runner uses a single combined traversal for all visitor rules.
+     */
+    readonly buildVisitor?: LintVisitorFactory;
+};
+type LintContext = {
+    readonly severityOverrides?: Readonly<Record<string, LintSeverity>>;
+    readonly disabledRules?: readonly string[];
+};
+/**
+ * Generic completion endpoint interface.
+ * Accepts a prompt string and returns the model's text response.
+ * Implementations can wrap any LLM backend (OpenAI, Anthropic, Gemini Nano, etc.).
+ */
+type LlmCompletionEndpoint = (prompt: string, options?: {
+    signal?: AbortSignal;
+}) => Promise<string>;
+/**
+ * A document section extracted for LLM analysis.
+ * Sections are split by headings to stay within token limits.
+ */
+type LintSection = {
+    readonly heading: string;
+    readonly headingPath: readonly string[];
+    readonly text: string;
+    readonly blockRange: readonly [start: number, end: number];
+};
+/**
+ * Async lint rule that uses an LLM endpoint for analysis.
+ */
+type LlmLintRule = {
+    readonly id: string;
+    readonly description: string;
+    readonly defaultSeverity: LintSeverity;
+    readonly buildPrompt: (section: LintSection) => string;
+    readonly parseResponse: (response: string, section: LintSection) => LintResult[];
+};
+
+export { type AstNode as A, type BlockNode as B, type CodeMark as C, type DocumentNode as D, type HardBreakNode as H, type InlineNode as I, type JinjaIfBranch as J, type ListItemNode as L, type Mark as M, type NodePath as N, type OrderedListNode as O, type ParagraphNode as P, type ResourceTagType as R, type StrikethroughMark as S, type TableRowNode as T, type UnderlineMark as U, type BlockquoteNode as a, type BoldMark as b, type BulletListNode as c, type HeadingNode as d, type HorizontalRuleNode as e, type ItalicMark as f, type JinjaIfBlockNode as g, type JinjaIfInlineNode as h, type JumpPointNode as i, type LinkMark as j, type ResourceTagNode as k, type TableNode as l, type TableCellNode as m, type TextNode as n, type LintRule as o, type LintContext as p, type LintResult as q, type LlmLintRule as r, type LlmCompletionEndpoint as s, type LintSection as t, type JSONContent as u, JUMP_POINT_ID_PATTERN as v, type LintSeverity as w, RESOURCE_TAG_TYPES as x, fromProseMirrorJSON as y };

package/dist/ui/index.d.ts

@@ -0,0 +1,383 @@
+import { Schema, Node } from 'prosemirror-model';
+import { Plugin, Command, EditorState, PluginKey } from 'prosemirror-state';
+import { InputRule } from 'prosemirror-inputrules';
+import { EditorView, NodeView, Decoration } from 'prosemirror-view';
+import React$1, { ReactElement, RefObject } from 'react';
+import { D as DocumentNode, A as AstNode, s as LlmCompletionEndpoint, I as InlineNode, B as BlockNode, u as JSONContent } from '../types-rEXLrfo_.js';
+
+/**
+ * ProseMirror Schema for Actionbook documents.
+ */
+declare const actionbookSchema: Schema<"doc" | "paragraph" | "heading" | "bulletList" | "orderedList" | "listItem" | "blockquote" | "horizontalRule" | "table" | "tableRow" | "tableCell" | "tableHeader" | "text" | "inlineToolTag" | "jumpPoint" | "hardBreak", "bold" | "italic" | "underline" | "strikethrough" | "code" | "link" | "diffMark">;
+
+type NodeViewFactory = (node: Node, view: EditorView, getPos: () => number | undefined) => NodeView;
+interface ActionbookPlugin {
+    name: string;
+    plugins?: () => Plugin[];
+    inputRules?: () => InputRule[];
+    keymap?: () => Record<string, Command>;
+    nodeViews?: () => Record<string, NodeViewFactory>;
+}
+
+/**
+ * Converts ActionbookPlugin[] into a flat array of PM Plugins.
+ * Merges inputRules and keymaps from all plugins.
+ *
+ * Priority order (ProseMirror tries plugins in array order — first wins):
+ *   1. Merged inputRules  — highest priority for text-input transforms
+ *   2. Merged keymap      — custom handlers (e.g. splitListItem on Enter)
+ *   3. Raw PM plugins     — baseline behaviors (history, baseKeymap, etc.)
+ *
+ * Putting the merged keymap BEFORE raw plugins ensures that handlers like
+ * `splitListItem` on Enter take priority over `baseKeymap`'s `splitBlock`.
+ */
+declare function createPluginArray(plugins: ActionbookPlugin[]): {
+    pmPlugins: Plugin[];
+    nodeViews: Record<string, NodeViewFactory>;
+};
+
+interface ActionbookRendererProps {
+    doc: DocumentNode;
+    className?: string;
+    /** Custom node renderer for extension points */
+    renderNode?: (node: AstNode, defaultRender: () => ReactElement) => ReactElement;
+}
+declare function ActionbookRenderer({ doc, className, renderNode }: ActionbookRendererProps): ReactElement;
+
+interface EditorShellProps {
+    className?: string;
+    style?: React$1.CSSProperties;
+}
+/**
+ * Contenteditable container for ProseMirror EditorView.
+ * Pass the ref from `useEditorView().viewRef` to mount the editor.
+ */
+declare const EditorShell: React$1.ForwardRefExoticComponent<EditorShellProps & React$1.RefAttributes<HTMLDivElement>>;
+
+interface ReactNodeViewProps {
+    node: Node;
+    view: EditorView;
+    getPos: () => number | undefined;
+    selected: boolean;
+    /** Outer node decorations currently applied to this node. */
+    decorations: readonly Decoration[];
+}
+interface ReactNodeViewOptions {
+    /** The React component to render */
+    component: React.ComponentType<ReactNodeViewProps>;
+    /** Container tag name (default: 'span' for inline, 'div' for block) */
+    as?: string;
+    /** CSS class name for the container */
+    className?: string;
+    /** Whether this is an inline node (default: true) */
+    inline?: boolean;
+}
+/**
+ * Creates a NodeViewFactory that renders a React component as a PM NodeView.
+ *
+ * Usage:
+ * ```ts
+ * const jumpPointPlugin: ActionbookPlugin = {
+ *   name: 'jumpPoint',
+ *   nodeViews: () => ({
+ *     jumpPoint: createReactNodeView({ component: JumpPointView }),
+ *   }),
+ * };
+ * ```
+ */
+declare function createReactNodeView(options: ReactNodeViewOptions): NodeViewFactory;
+
+interface EditorViewConfig {
+    plugins?: ActionbookPlugin[];
+    content?: DocumentNode | null;
+    editable?: boolean;
+    onTransaction?: (state: EditorState) => void;
+    onContentChange?: (doc: DocumentNode) => void;
+    /**
+     * Optional LLM completion endpoint for LLM-based lint rules.
+     * When provided, the editor can run async lint rules that leverage LLM analysis.
+     * Accepts any backend: OpenAI, Anthropic, Gemini Nano, custom proxy, etc.
+     */
+    llmCompletionEndpoint?: LlmCompletionEndpoint;
+}
+interface EditorViewHandle {
+    viewRef: RefObject<HTMLDivElement | null>;
+    view: EditorView | null;
+    getAST: () => DocumentNode | null;
+    getMarkdown: () => string;
+    setContent: (doc: DocumentNode) => void;
+    focus: () => void;
+    destroy: () => void;
+}
+declare function useEditorView(config: EditorViewConfig): EditorViewHandle;
+
+declare function createInputRulesPlugin(): ActionbookPlugin;
+
+declare function createKeymapPlugin(): ActionbookPlugin;
+
+declare function createMarkdownClipboardPlugin(): ActionbookPlugin;
+
+/**
+ * Jump-point adjacent decoration + edit plugins.
+ *
+ * Adjacent plugin: marks jumpPoint nodes near the cursor with a decoration
+ * so the NodeView can show `^id^` raw syntax when the cursor is beside them.
+ *
+ * Edit plugin: tracks a "raw range" after ArrowLeft explodes a jumpPoint atom
+ * to `^aa^` text. When the cursor moves outside that range the plugin
+ * auto-reconverts the text back to a jumpPoint node (if it still matches
+ * `^validId^` and the id has no duplicates elsewhere in the doc).
+ *
+ * Keymap:
+ *   Backspace  — explode atom to `^aa`  (closing `^` consumed), cursor at end
+ *   ArrowLeft  — explode atom to `^aa^`, cursor before closing `^`
+ */
+
+/** Decoration spec set on a jumpPoint node when the cursor is adjacent. */
+declare const JUMP_POINT_ADJACENT_SPEC: {
+    readonly jumpPointAdjacent: true;
+};
+declare function createJumpPointAdjacentPlugin(): ActionbookPlugin;
+
+declare function createJumpPointNodeViewPlugin(): ActionbookPlugin;
+
+declare function createInlineToolTagNodeViewPlugin(): ActionbookPlugin;
+
+declare function createJinjaDecorationPlugin(): ActionbookPlugin;
+
+/**
+ * Link editing plugin for the Actionbook editor.
+ *
+ * UX flow:
+ *  1. `[aa](#aa)` is rendered as a clickable "aa" link mark.
+ *  2. Pressing Backspace while cursor is inside or just after the link
+ *     "explodes" it to raw markdown `[aa](#aa)` for editing.
+ *  3. While the cursor stays inside the raw text, normal editing applies.
+ *  4. When the cursor leaves the raw region:
+ *     - If the text still matches `[label](href)` → reconverts to link mark.
+ *     - Otherwise → stays as plain text (user intentionally broke the link).
+ *  5. Completing the markdown syntax by typing `)` triggers the input rule
+ *     and immediately converts to a link mark.
+ */
+
+/**
+ * Creates the link editing `ActionbookPlugin`.
+ *
+ * Bundles:
+ * - Backspace → explode to raw markdown
+ * - `appendTransaction` auto-reconvert on cursor leave
+ * - Input rule for `[label](href)` → link mark
+ * - Click handler for internal `#anchor` links
+ */
+declare function createLinkPlugin(): ActionbookPlugin;
+
+declare function createDragHandlePlugin(): ActionbookPlugin;
+
+declare function createTodoNodeViewPlugin(): ActionbookPlugin;
+
+/**
+ * Slash-command trigger plugin.
+ *
+ * Tracks whether the cursor is inside a `/query` pattern and exposes the
+ * active range + query string via `slashCommandKey` so that the
+ * `SlashCommandMenu` React component can read it and render the popup.
+ *
+ * The plugin also handles:
+ *  - Escape → dismisses the menu (sets dismissed state so the same `/`
+ *    position doesn't re-trigger until the user moves away and types `/` again)
+ *  - ArrowUp / ArrowDown / Enter → consumed by the React component through
+ *    a capture-phase keydown listener; the plugin just marks them as handled
+ *    when the menu is active so ProseMirror doesn't move the cursor.
+ */
+
+interface SlashCommandState {
+    /** Whether a slash trigger is currently active. */
+    active: boolean;
+    /** Document positions of the full `/query` text (inclusive). */
+    range: {
+        from: number;
+        to: number;
+    } | null;
+    /** Text typed after `/`, not including the slash itself. */
+    query: string;
+}
+declare const slashCommandKey: PluginKey<SlashCommandState>;
+declare function createSlashCommandPlugin(): ActionbookPlugin;
+
+/**
+ * SlashCommandMenu — injectable floating slash-command picker.
+ *
+ * Usage:
+ * ```tsx
+ * // Define items (inject from outside)
+ * const items: SlashCommandItem[] = [
+ *   {
+ *     id: 'heading1',
+ *     title: 'Heading 1',
+ *     description: 'Large section heading',
+ *     icon: <span>H1</span>,
+ *     command({ view, range }) {
+ *       const { state, dispatch } = view;
+ *       const tr = state.tr.delete(range.from, range.to);
+ *       setBlockType(heading, { level: 1 })(
+ *         state.apply(tr),
+ *         (newTr) => dispatch(tr.steps.length ? tr : newTr),
+ *       );
+ *     },
+ *   },
+ * ];
+ *
+ * // In your editor component:
+ * const [editorState, setEditorState] = useState<EditorState | null>(null);
+ * const handle = useEditorView({ ..., onTransaction: setEditorState });
+ *
+ * return (
+ *   <>
+ *     <EditorShell ref={handle.viewRef} />
+ *     <SlashCommandMenu
+ *       view={handle.view}
+ *       editorState={editorState}
+ *       items={items}
+ *     />
+ *   </>
+ * );
+ * ```
+ *
+ * The `command` callback receives the editor view and the range of the
+ * `/query` trigger text. It is responsible for deleting the trigger and
+ * inserting whatever content it wants.
+ */
+
+interface SlashCommandItem {
+    /** Unique key; falls back to `title` if omitted. */
+    id?: string;
+    title: string;
+    description?: string;
+    /** Optional icon node rendered to the left of the title. */
+    icon?: React$1.ReactNode;
+    /**
+     * Execute this command.
+     *
+     * @param view  - Live EditorView; use `view.state` / `view.dispatch`.
+     * @param range - Positions of the full `/query` text in the document.
+     *                Delete this range before inserting your content.
+     */
+    command: (props: {
+        view: EditorView;
+        range: {
+            from: number;
+            to: number;
+        };
+    }) => void;
+}
+interface SlashCommandMenuProps {
+    view: EditorView | null;
+    editorState: EditorState | null;
+    /** Full item list. Filtered by the current query automatically. */
+    items: SlashCommandItem[];
+}
+declare function SlashCommandMenu({ view, editorState, items }: SlashCommandMenuProps): React$1.ReactPortal | null;
+
+interface JinjaTreeViewProps {
+    doc: DocumentNode;
+    className?: string;
+}
+declare function JinjaTreeView({ doc, className }: JinjaTreeViewProps): ReactElement | null;
+
+/**
+ * Floating UI for the Actionbook editor.
+ *
+ * Two interaction patterns:
+ *
+ * 1. SelectionToolbar — appears above a non-empty text selection.
+ *    Buttons: Bold · Italic · Underline · Strikethrough · Code · Link · ─ · Block type ▾
+ *
+ * 2. EmptyParaHandle — appears to the left of an empty paragraph/heading
+ *    after the cursor has dwelled there for DWELL_MS (600 ms).
+ *    A small "+" button opens a block-type picker menu.
+ *
+ * Both are rendered into document.body via React portals so they never
+ * get clipped by overflow:hidden ancestors.
+ */
+
+interface FloatingMenuProps {
+    view: EditorView | null;
+    editorState: EditorState | null;
+}
+declare function FloatingMenu({ view, editorState }: FloatingMenuProps): React$1.ReactPortal | null;
+
+/**
+ * Inline suggestion (ghost text) plugin.
+ *
+ * Debounces after the cursor stops moving, calls an LLM endpoint via a
+ * user-supplied `InlineSuggestProvider`, then renders the response as gray
+ * ghost text after the cursor using a ProseMirror widget decoration.
+ *
+ * Accepts:
+ *   Tab    → insert the suggestion at the cursor
+ *   Escape → dismiss the suggestion
+ *
+ * Fully detachable: just omit `createInlineSuggestPlugin()` from the plugins
+ * array to disable the feature entirely.
+ */
+
+/**
+ * Cursor context passed to the provider's `buildPrompt`.
+ */
+type InlineSuggestContext = {
+    /** Text before the cursor — current paragraph plus up to 2 preceding paragraphs. */
+    textBefore: string;
+    /** Text in the current paragraph after the cursor (up to 100 chars). */
+    textAfter: string;
+};
+/**
+ * Extensible provider interface, analogous to `LlmLintRule`.
+ *
+ * Implement this to customize what gets sent to the LLM and how the
+ * response is parsed into a suggestion string.
+ */
+type InlineSuggestProvider = {
+    /** Unique identifier for this provider. */
+    id: string;
+    /**
+     * Build the prompt string sent to the LLM endpoint.
+     * Return an empty string to suppress the request entirely.
+     */
+    buildPrompt: (ctx: InlineSuggestContext) => string;
+    /**
+     * Parse the raw LLM response into the text to insert at the cursor.
+     * Return an empty string to suppress the decoration.
+     * `ctx` is the same context that was passed to `buildPrompt`.
+     */
+    parseResponse: (response: string, ctx: InlineSuggestContext) => string;
+};
+interface InlineSuggestState {
+    /** Ghost text currently shown, or null if nothing is active. */
+    suggestion: string | null;
+    /** Document position the suggestion is anchored to. */
+    anchorPos: number | null;
+}
+declare const inlineSuggestKey: PluginKey<InlineSuggestState>;
+declare function createInlineSuggestPlugin(provider: InlineSuggestProvider, endpoint: LlmCompletionEndpoint, options?: {
+    /**
+     * Called when the user accepts a suggestion (Tab) or the cursor moves to
+     * a new context. Use this to pre-create a fresh completion session so it's
+     * ready by the time the next debounce fires.
+     */
+    onContextChange?: () => void;
+}): ActionbookPlugin;
+
+/**
+ * Convert ActionbookAST → ProseMirror JSONContent.
+ */
+
+declare function convertInline(node: InlineNode): JSONContent;
+declare function convertBlock(node: BlockNode, listDepth?: number): JSONContent;
+declare function toProseMirrorJSON(doc: DocumentNode): JSONContent;
+/**
+ * Convert parseFragment() output (InlineNode[] | BlockNode[]) to PM JSONContent[].
+ * If nodes are inline, wraps them in a single paragraph.
+ */
+declare function astNodesToJSONContent(nodes: (InlineNode | BlockNode)[]): JSONContent[];
+
+export { type ActionbookPlugin, ActionbookRenderer, type ActionbookRendererProps, EditorShell, type EditorShellProps, type EditorViewConfig, type EditorViewHandle, FloatingMenu, type FloatingMenuProps, type InlineSuggestContext, type InlineSuggestProvider, type InlineSuggestState, JUMP_POINT_ADJACENT_SPEC, JinjaTreeView, type JinjaTreeViewProps, type NodeViewFactory, type ReactNodeViewOptions, type ReactNodeViewProps, type SlashCommandItem, SlashCommandMenu, type SlashCommandMenuProps, type SlashCommandState, actionbookSchema, astNodesToJSONContent, convertBlock, convertInline, createDragHandlePlugin, createInlineSuggestPlugin, createInlineToolTagNodeViewPlugin, createInputRulesPlugin, createJinjaDecorationPlugin, createJumpPointAdjacentPlugin, createJumpPointNodeViewPlugin, createKeymapPlugin, createLinkPlugin, createMarkdownClipboardPlugin, createPluginArray, createReactNodeView, createSlashCommandPlugin, createTodoNodeViewPlugin, inlineSuggestKey, slashCommandKey, toProseMirrorJSON, useEditorView };