/**
 * Dhwani Plugin SDK Declaration File
 * Provides auto-suggestions, typings, and intellisense in VS Code for Dhwani plugins.
 */

declare namespace DhwaniEditorSDK {
    /**
     * Base Tiptap Node class for building custom editor blocks.
     */
    export class Node {
        name: string;
        static create(config: {
            name: string;
            group?: "block" | "inline";
            content?: string;
            defining?: boolean;
            inline?: boolean;
            draggable?: boolean;
            parseHTML?(): { tag: string; getAttrs?: (node: any) => any }[];
            renderHTML?(props: { HTMLAttributes: Record<string, any> }): [string, any, ...any[]];
            addNodeView?(): any;
            addAttributes?(): Record<string, { default?: any; parseHTML?: (element: any) => any }>;
            addCommands?(): Record<string, (...args: any[]) => any>;
            [key: string]: any;
        }): any;
    }

    /**
     * Base Tiptap Mark class for styling text (e.g. bold, highlight).
     */
    export class Mark {
        name: string;
        static create(config: {
            name: string;
            parseHTML?(): { tag: string }[];
            renderHTML?(props: { HTMLAttributes: Record<string, any> }): [string, any, ...any[]];
            [key: string]: any;
        }): any;
    }

    /**
     * Base Tiptap Extension class for adding custom behaviors and commands.
     */
    export class Extension {
        name: string;
        static create(config: {
            name: string;
            addOptions?(): Record<string, any>;
            addCommands?(): Record<string, (...args: any[]) => any>;
            [key: string]: any;
        }): any;
    }

    /**
     * Merges HTML attributes safely during Tiptap rendering.
     */
    export function mergeAttributes(...attributes: Record<string, any>[]): Record<string, any>;

    /**
     * Renderer to map custom React components as Tiptap interactive node views.
     */
    export function ReactNodeViewRenderer(component: any, options?: { stopPropagation?: boolean }): any;

    /**
     * React component wrapper for custom Node Views (holds outer container bindings).
     */
    export const NodeViewWrapper: React.ComponentType<{
        className?: string;
        style?: React.CSSProperties;
        children?: React.ReactNode;
        [key: string]: any;
    }>;

    /**
     * React component placeholder for editable nested text blocks inside a custom Node View.
     */
    export const NodeViewContent: React.ComponentType<{
        className?: string;
        style?: React.CSSProperties;
        [key: string]: any;
    }>;
}

/**
 * Tiptap Editor interface wrapper.
 */
interface DhwaniTiptapEditor {
    /**
     * Starts a command chain transaction (e.g., editor.chain().focus().insertContent(...).run()).
     */
    chain(): DhwaniTiptapEditorChain;
    
    /**
     * Direct commands register.
     */
    commands: {
        /**
         * Sets text selection cursor at document index.
         */
        setTextSelection(position: number): boolean;
        [key: string]: any;
    };

    /**
     * Current editor ProseMirror state.
     */
    state: {
        selection: {
            from: number;
            to: number;
        };
    };
}

/**
 * Tiptap Command Chain Helper.
 */
interface DhwaniTiptapEditorChain {
    /**
     * Directs keyboard focus to the editor.
     */
    focus(): DhwaniTiptapEditorChain;

    /**
     * Inserts content (HTML markup, markdown, or node objects) at the cursor.
     */
    insertContent(content: string | Record<string, any>): DhwaniTiptapEditorChain;

    /**
     * Runs and executes the chained transactions.
     */
    run(): boolean;

    [key: string]: any;
}

/**
 * Registry configuration structure for custom Page Extensions.
 */
interface PageExtensionConfig {
    /**
     * Unique identifier matching the Tiptap node view name.
     */
    name: string;

    /**
     * Tiptap Node extension instance.
     */
    tiptapExtension: import("@tiptap/core").AnyExtension;

    /**
     * Slash commands registry configuration.
     */
    slashCommand: {
        /**
         * Heading title inside the dropdown.
         */
        title: string;

        /**
         * Sub-text details describing the action.
         */
        description: string;

        /**
         * Inline SVG markup string for the command icon.
         */
        icon: string;

        /**
         * Callback fired when selected from the dropdown list.
         */
        command: (editor: DhwaniTiptapEditor, range?: { from: number; to: number }) => void;
    };
}

/**
 * Scoped, pre-bound SDK instance returned to a plugin upon registration.
 */
interface DhwaniSDKInstance {
    api: {
        /**
         * Saves a file as a page attachment.
         * Requires the 'save_attachment' permission.
         * 
         * @param contentId ID of the current page/content
         * @param buffer File content as an ArrayBuffer
         * @param fileName Original name of the file
         * @returns Promise resolving to the saved attachment object
         */
        saveAttachment(
            contentId: string,
            buffer: ArrayBuffer,
            fileName: string
        ): Promise<{
            id: string;
            file_path: string;
            title: string;
            content_id: string;
        }>;

        /**
         * Deletes a saved page attachment.
         * Requires the 'delete_attachment' permission.
         * 
         * @param id ID of the attachment to delete
         */
        deleteAttachment(id: string): Promise<void>;

        /**
         * Retrieves the ID of the currently active page/content.
         * Does not require any permissions.
         * 
         * @returns The active content ID, or null if not in an active page context
         */
        getCurrentContentId(): string | null;
    };
}

declare namespace Dhwani {
    /**
     * Registers a custom page extension and slash command in the Dhwani editor workspace.
     * Returns a scoped, pre-bound SDK instance for the calling plugin.
     */
    export function registerPageExtension(config: PageExtensionConfig): DhwaniSDKInstance;
}

declare namespace DhwaniSDK {
    export namespace api {
        /**
         * Saves a file as a page attachment.
         * Requires the 'save_attachment' permission.
         * 
         * @param pluginId Unique system name of the plugin (e.g. 'tip.callout.plugin')
         * @param contentId ID of the current page/content
         * @param buffer File content as an ArrayBuffer
         * @param fileName Original name of the file
         * @returns Promise resolving to the saved attachment object
         */
        export function saveAttachment(
            pluginId: string,
            contentId: string,
            buffer: ArrayBuffer,
            fileName: string
        ): Promise<{
            id: string;
            file_path: string;
            title: string;
            content_id: string;
        }>;

        /**
         * Deletes a saved page attachment.
         * Requires the 'delete_attachment' permission.
         * 
         * @param pluginId Unique system name of the plugin
         * @param id ID of the attachment to delete
         */
        export function deleteAttachment(
            pluginId: string,
            id: string
        ): Promise<void>;

        /**
         * Retrieves the ID of the currently active page/content.
         * Does not require any permissions.
         * 
         * @returns The active content ID, or null if not in an active page context
         */
        export function getCurrentContentId(): string | null;
    }
}

interface Window {
    DhwaniEditorSDK: typeof DhwaniEditorSDK;
    Dhwani: typeof Dhwani;
    DhwaniSDK: typeof DhwaniSDK;
    React: typeof import("react");
    ReactDOM: typeof import("react-dom");
}
