@dhwaniapp/plugin-sdk 1.0.0

package/README.md

@@ -0,0 +1,58 @@
+# @dhwaniapp/plugin-sdk
+
+Software Development Kit (SDK) typings and manifest schemas for building custom extensions in **Dhwani Note Taking**.
+
+---
+
+## Installation
+
+Install the SDK as a devDependency in your plugin project:
+
+```bash
+npm install --save-dev @dhwaniapp/plugin-sdk
+```
+
+---
+
+## 1. JSON Schema Validation (`application.json`)
+
+To enable autocomplete and inline schema validation in your editor (e.g. VS Code), add the `$schema` reference pointing to the node_modules location at the top of your `application.json` manifest:
+
+```json
+{
+  "$schema": "./node_modules/@dhwaniapp/plugin-sdk/plugin-manifest.schema.json",
+  "display_name": "My Custom Node Plugin",
+  "system_name": "my.custom.node",
+  "version": "1.0.0",
+  "author": "Developer Name",
+  "license": "MIT",
+  "permissions_required": ["use_page_extention"]
+}
+```
+
+---
+
+## 2. Editor typings and Intellisense (`dist/*.js`)
+
+To enable code suggestions for `window.Dhwani` and `window.DhwaniEditorSDK` namespaces, add the type reference directive at the top of your JavaScript source files:
+
+```javascript
+/// <reference types="@dhwaniapp/plugin-sdk" />
+
+(function() {
+    const React = window.React;
+    const { Node, ReactNodeViewRenderer, NodeViewWrapper } = window.DhwaniEditorSDK;
+
+    // Your custom editor node view code...
+})();
+```
+
+If you are developing your plugin with TypeScript, configure your project's `tsconfig.json` to load the SDK typings automatically:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["@dhwaniapp/plugin-sdk"]
+  }
+}
+```

package/index.d.ts

@@ -0,0 +1,189 @@
+/**
+ * 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: any;
+
+    /**
+     * 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;
+    };
+}
+
+declare namespace Dhwani {
+    /**
+     * Registers a custom page extension and slash command in the Dhwani editor workspace.
+     */
+    export function registerPageExtension(config: PageExtensionConfig): void;
+}
+
+interface Window {
+    DhwaniEditorSDK: typeof DhwaniEditorSDK;
+    Dhwani: typeof Dhwani;
+    React: typeof import("react");
+    ReactDOM: typeof import("react-dom");
+}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@dhwaniapp/plugin-sdk",
+  "version": "1.0.0",
+  "description": "Software Development Kit (SDK) and manifest schemas for building Dhwani Note Taking plugins.",
+  "main": "",
+  "types": "index.d.ts",
+  "files": [
+    "index.d.ts",
+    "plugin-manifest.schema.json"
+  ],
+  "author": "Dhwani Team",
+  "license": "MIT",
+  "keywords": [
+    "dhwani",
+    "plugin",
+    "sdk",
+    "tiptap",
+    "electron"
+  ]
+}

package/plugin-manifest.schema.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "DhwaniPluginManifest",
+  "type": "object",
+  "description": "Manifest schema for Dhwani Note Taking plugins",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Path or URL to the plugin manifest schema file"
+    },
+    "display_name": {
+      "type": "string",
+      "description": "The user-facing display name of the plugin",
+      "minLength": 1
+    },
+    "system_name": {
+      "type": "string",
+      "description": "Unique system identifier for the plugin. Can only contain alphanumeric characters and dots (.)",
+      "pattern": "^[a-zA-Z0-9\\.]+$"
+    },
+    "version": {
+      "type": "string",
+      "description": "Semantic version number of the plugin (e.g. '1.0.0')",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"
+    },
+    "description": {
+      "type": "string",
+      "description": "Brief description of what the plugin does"
+    },
+    "author": {
+      "type": "string",
+      "description": "The author or organization who developed the plugin"
+    },
+    "license": {
+      "type": "string",
+      "description": "Software license for the plugin (e.g., 'MIT', 'GPL-3.0')"
+    },
+    "permissions_required": {
+      "type": "array",
+      "description": "List of system permissions requested by the plugin",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "enum": ["use_page_extention"],
+        "description": "System permissions available in Dhwani"
+      }
+    },
+    "icon_in_svg": {
+      "type": "string",
+      "description": "Relative path to the plugin's main SVG icon inside the ZIP package (e.g. 'assets/icon.svg')"
+    },
+    "extentions": {
+      "type": "array",
+      "description": "List of editor extensions provided by this plugin",
+      "items": {
+        "type": "object",
+        "required": [
+          "type",
+          "extention_file",
+          "extention_svg_icon",
+          "extention_display_name"
+        ],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["page"],
+            "description": "Type of editor extension (currently only 'page' is supported)"
+          },
+          "extention_file": {
+            "type": "string",
+            "description": "Relative path to the compiled JavaScript asset file (e.g., 'dist/tip-callout.js')"
+          },
+          "extention_svg_icon": {
+            "type": "string",
+            "description": "Relative path to the extension's icon inside the ZIP package (e.g., 'assets/tip.svg')"
+          },
+          "extention_display_name": {
+            "type": "string",
+            "description": "User-facing label for the slash command / extension"
+          }
+        }
+      }
+    }
+  },
+  "required": [
+    "display_name",
+    "system_name",
+    "version",
+    "author",
+    "license",
+    "permissions_required"
+  ]
+}