@notectl/core 0.0.2 → 0.0.5

package/dist/types/index.d.ts

@@ -8,6 +8,12 @@ export declare interface ApplyMarkOp extends BaseOperation {
     add: boolean;
 }
 
+/**
+ * Default timeout for screen reader announcements
+ * Used to clear and reset the aria-live region
+ */
+export declare const ARIA_ANNOUNCEMENT_DELAY = 100;
+
 /**
  * Attribute specification
  */
@@ -52,6 +58,33 @@ export declare interface BlockAttrs {
     [key: string]: unknown;
 }
 
+/**
+ * Block type utilities
+ */
+export declare interface BlockHelpers {
+    /**
+     * Check if a node is a text node
+     */
+    isTextNode(node: Node_2): node is TextNode;
+    /**
+     * Check if a node is a block node
+     */
+    isBlockNode(node: Node_2): node is BlockNode;
+    /**
+     * Get all text content from a block
+     */
+    getTextContent(block: BlockNode): string;
+    /**
+     * Check if block is empty
+     */
+    isEmpty(block: BlockNode): boolean;
+}
+
+/**
+ * Block helper implementation
+ */
+export declare const blockHelpers: BlockHelpers;
+
 /**
  * Core type definitions for Notectl editor
  */
@@ -75,11 +108,33 @@ export declare interface BlockNode {
  */
 export declare function canCompose(deltaA: Delta, deltaB: Delta): boolean;
 
+/**
+ * Command definition with type safety
+ */
+export declare interface CommandDefinition<TArgs extends unknown[] = unknown[], TReturn = unknown> {
+    name: string;
+    description?: string;
+    handler: CommandHandler_2<TArgs, TReturn>;
+}
+
 /**
  * Command handler function
  */
 export declare type CommandHandler = (...args: unknown[]) => unknown;
 
+/**
+ * Command handler function signature
+ */
+declare type CommandHandler_2<TArgs extends unknown[] = unknown[], TReturn = unknown> = (...args: TArgs) => TReturn | Promise<TReturn>;
+
+/**
+ * Built-in command registry
+ * Maps command names to their handlers
+ */
+export declare interface CommandRegistry {
+    [key: string]: CommandHandler_2<unknown[], unknown>;
+}
+
 /**
  * Compose two deltas into a single delta
  * Applies deltaB after deltaA
@@ -109,6 +164,16 @@ export declare function createEditor(container: HTMLElement, config?: EditorConf
  */
 export declare function createNodeFactory(schema: Schema): NodeFactory;
 
+/**
+ * Default maximum number of history entries to keep
+ */
+export declare const DEFAULT_MAX_HISTORY_DEPTH = 100;
+
+/**
+ * Default minimum height for the editor content area
+ */
+export declare const DEFAULT_MIN_HEIGHT = 200;
+
 /**
  * Delete a block
  */
@@ -202,6 +267,23 @@ declare interface Document_2 {
 }
 export { Document_2 as Document }
 
+/**
+ * Timeout in milliseconds to wait for editor's connectedCallback to complete
+ * and render the DOM structure including plugin containers.
+ *
+ * This is needed when registering plugins immediately after appending the editor
+ * to the DOM, as the connectedCallback runs asynchronously.
+ *
+ * @example
+ * ```typescript
+ * const editor = document.createElement('notectl-editor');
+ * container.appendChild(editor);
+ * await new Promise(resolve => setTimeout(resolve, EDITOR_READY_TIMEOUT));
+ * await editor.registerPlugin(new ToolbarPlugin());
+ * ```
+ */
+export declare const EDITOR_READY_TIMEOUT = 100;
+
 /**
  * Editor API interface
  * Public methods exposed by the NotectlEditor class
@@ -239,6 +321,7 @@ export declare interface EditorConfig {
     autofocus?: boolean;
     sanitizeHTML?: boolean;
     maxHistoryDepth?: number;
+    content?: string | Document_2;
     [key: string]: unknown;
 }
 
@@ -346,6 +429,39 @@ export declare class EditorState {
     static fromJSON(json: Document_2, schema?: Schema): EditorState;
 }
 
+/**
+ * Type for error codes
+ */
+export declare type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes];
+
+/**
+ * Error codes for structured error handling
+ */
+export declare const ErrorCodes: {
+    readonly PLUGIN_ALREADY_REGISTERED: "PLUGIN_ALREADY_REGISTERED";
+    readonly PLUGIN_NOT_FOUND: "PLUGIN_NOT_FOUND";
+    readonly PLUGIN_MISSING_DEPENDENCY: "PLUGIN_MISSING_DEPENDENCY";
+    readonly PLUGIN_INVALID_CONFIG: "PLUGIN_INVALID_CONFIG";
+    readonly PLUGIN_INIT_FAILED: "PLUGIN_INIT_FAILED";
+    readonly PLUGIN_DESTROY_FAILED: "PLUGIN_DESTROY_FAILED";
+    readonly PLUGIN_DEPENDENCY_CONFLICT: "PLUGIN_DEPENDENCY_CONFLICT";
+    readonly EDITOR_NOT_MOUNTED: "EDITOR_NOT_MOUNTED";
+    readonly EDITOR_NOT_INITIALIZED: "EDITOR_NOT_INITIALIZED";
+    readonly EDITOR_DESTROYED: "EDITOR_DESTROYED";
+    readonly COMMAND_NOT_FOUND: "COMMAND_NOT_FOUND";
+    readonly COMMAND_ALREADY_REGISTERED: "COMMAND_ALREADY_REGISTERED";
+    readonly COMMAND_EXECUTION_FAILED: "COMMAND_EXECUTION_FAILED";
+    readonly COMMAND_INVALID_ARGS: "COMMAND_INVALID_ARGS";
+    readonly INVALID_CONTENT: "INVALID_CONTENT";
+    readonly INVALID_DELTA: "INVALID_DELTA";
+    readonly INVALID_DOCUMENT: "INVALID_DOCUMENT";
+    readonly SANITIZATION_FAILED: "SANITIZATION_FAILED";
+    readonly XSS_DETECTED: "XSS_DETECTED";
+    readonly UNSAFE_OPERATION: "UNSAFE_OPERATION";
+    readonly INVALID_OPERATION: "INVALID_OPERATION";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+};
+
 /**
  * Error response envelope
  */
@@ -538,6 +654,10 @@ export declare class NotectlEditor extends HTMLElement {
     private config;
     private keyboardShortcutCleanup?;
     private ariaLiveRegion;
+    private pendingPlugins;
+    private readyPromise;
+    private readyResolve?;
+    private isReady;
     constructor();
     /**
      * Observed attributes for the web component
@@ -546,7 +666,7 @@ export declare class NotectlEditor extends HTMLElement {
     /**
      * Called when element is connected to DOM
      */
-    connectedCallback(): void;
+    connectedCallback(): Promise<void>;
     /**
      * Called when element is disconnected from DOM
      */
@@ -583,6 +703,10 @@ export declare class NotectlEditor extends HTMLElement {
      * Escape HTML
      */
     private escapeHTML;
+    private tableToHTML;
+    private tableRowToHTML;
+    private tableCellToHTML;
+    private styleObjectToString;
     /**
      * Setup accessibility features
      */
@@ -627,6 +751,7 @@ export declare class NotectlEditor extends HTMLElement {
      * Handle blur event
      */
     private handleBlur;
+    private handleContextMenu;
     /**
      * Update placeholder visibility
      */
@@ -657,12 +782,81 @@ export declare class NotectlEditor extends HTMLElement {
     private updateReadonly;
     /**
      * Register a plugin
+     *
+     * Plugins can be registered before or after the editor is mounted.
+     * If registered before mounting, they will be queued and initialized
+     * automatically when the editor connects to the DOM.
+     *
+     * @param plugin - The plugin to register
+     * @returns Promise that resolves when the plugin is registered
      */
     registerPlugin(plugin: Plugin_2): Promise<void>;
     /**
      * Unregister a plugin
      */
     unregisterPlugin(pluginId: string): Promise<void>;
+    /**
+     * Wait for the editor to be ready
+     *
+     * Returns a Promise that resolves when the editor has been mounted
+     * and all pending plugins have been initialized. This is useful when
+     * you need to ensure the editor is fully initialized before performing
+     * operations that depend on the editor being mounted.
+     *
+     * @returns Promise that resolves when the editor is ready
+     * @example
+     * ```typescript
+     * const editor = document.createElement('notectl-editor');
+     * container.appendChild(editor);
+     * await editor.whenReady();
+     * // Editor is now fully initialized
+     * ```
+     */
+    whenReady(): Promise<void>;
+    /**
+     * Get the block containing the current selection
+     */
+    private getSelectedBlock;
+    /**
+     * Find all blocks of a specific type
+     */
+    private findBlocksByType;
+    /**
+     * Find parent block of a given block
+     */
+    private findParentBlock;
+    /**
+     * Get block at current cursor position
+     */
+    private getBlockAtCursor;
+    /**
+     * Insert a block after another block (Delta-based)
+     */
+    private insertBlockAfter;
+    /**
+     * Insert a block before another block (Delta-based)
+     */
+    private insertBlockBefore;
+    /**
+     * Update block attributes (Delta-based)
+     */
+    private updateBlockAttrs;
+    /**
+     * Delete a block (Delta-based)
+     */
+    private deleteBlockById;
+    /**
+     * Add mark to current selection (Delta-based)
+     */
+    private addMarkToSelection;
+    /**
+     * Remove mark from current selection (Delta-based)
+     */
+    private removeMarkFromSelection;
+    /**
+     * Toggle mark on current selection (Delta-based)
+     */
+    private toggleMarkOnSelection;
     /**
      * Create plugin context
      */
@@ -755,6 +949,25 @@ export declare class NotectlEditor extends HTMLElement {
     blur(): void;
 }
 
+/**
+ * Structured error class for Notectl
+ */
+export declare class NotectlError extends Error {
+    code: ErrorCode;
+    details?: unknown | undefined;
+    constructor(code: ErrorCode, message: string, details?: unknown | undefined);
+    /**
+     * Convert to JSON-serializable format
+     */
+    toJSON(): {
+        error: {
+            code: ErrorCode;
+            message: string;
+            details: unknown;
+        };
+    };
+}
+
 /**
  * Union of all operation types
  */
@@ -811,6 +1024,78 @@ export declare interface PluginContext {
      * Apply a delta to the editor
      */
     applyDelta(delta: Delta): void;
+    /**
+     * Get current selection
+     */
+    getSelection(): Selection_2 | null;
+    /**
+     * Set selection
+     */
+    setSelection(selection: Selection_2): void;
+    /**
+     * Get the block containing the current cursor/selection
+     */
+    getSelectedBlock(): BlockNode | null;
+    /**
+     * Find all blocks of a specific type
+     * @param type - Block type to search for (e.g., 'table', 'heading', 'paragraph')
+     * @returns Array of matching blocks
+     */
+    findBlocksByType(type: string): BlockNode[];
+    /**
+     * Find a block by its ID
+     * @param blockId - Block identifier
+     * @returns Block or undefined if not found
+     */
+    findBlockById(blockId: BlockId): BlockNode | undefined;
+    /**
+     * Find parent block of a given block
+     * @param block - Child block
+     * @returns Parent block or null if block is at root level
+     */
+    findParentBlock(block: BlockNode): BlockNode | null;
+    /**
+     * Get block at current cursor position
+     */
+    getBlockAtCursor(): BlockNode | null;
+    /**
+     * Insert a block after another block
+     * @param block - Block to insert
+     * @param afterId - ID of block to insert after (if undefined, appends to end)
+     */
+    insertBlockAfter(block: BlockNode, afterId?: BlockId): void;
+    /**
+     * Insert a block before another block
+     * @param block - Block to insert
+     * @param beforeId - ID of block to insert before (if undefined, prepends to start)
+     */
+    insertBlockBefore(block: BlockNode, beforeId?: BlockId): void;
+    /**
+     * Update block attributes
+     * @param blockId - Block to update
+     * @param attrs - Attributes to merge
+     */
+    updateBlockAttrs(blockId: BlockId, attrs: Record<string, unknown>): void;
+    /**
+     * Delete a block
+     * @param blockId - Block to delete
+     */
+    deleteBlock(blockId: BlockId): void;
+    /**
+     * Add mark to current selection
+     * @param mark - Mark to add
+     */
+    addMark(mark: Mark): void;
+    /**
+     * Remove mark from current selection
+     * @param markType - Type of mark to remove
+     */
+    removeMark(markType: string): void;
+    /**
+     * Toggle mark on current selection
+     * @param markType - Type of mark to toggle
+     */
+    toggleMark(markType: string): void;
     /**
      * Register event listener
      */
@@ -833,6 +1118,7 @@ export declare interface PluginContext {
     executeCommand(name: string, ...args: unknown[]): unknown;
     /**
      * Access DOM container (editable area)
+     * @deprecated Prefer using Delta operations instead of direct DOM manipulation
      */
     getContainer(): HTMLElement;
     /**
@@ -856,10 +1142,29 @@ export declare class PluginManager {
     constructor();
     /**
      * Register a plugin
+     *
+     * @param plugin - The plugin to register
+     * @param context - Plugin context with editor APIs
+     * @throws {NotectlError} If plugin validation fails or initialization errors occur
+     *
+     * @example
+     * ```typescript
+     * const toolbarPlugin = new ToolbarPlugin();
+     * await pluginManager.register(toolbarPlugin, context);
+     * ```
      */
     register(plugin: Plugin_2, context: PluginContext): Promise<void>;
     /**
      * Unregister a plugin
+     *
+     * @param pluginId - ID of the plugin to unregister
+     * @param context - Plugin context for event emission
+     * @throws {NotectlError} If plugin is not found or has dependents
+     *
+     * @example
+     * ```typescript
+     * await pluginManager.unregister('toolbar-plugin', context);
+     * ```
      */
     unregister(pluginId: string, context: PluginContext): Promise<void>;
     /**
@@ -951,6 +1256,37 @@ declare interface Selection_2 {
 }
 export { Selection_2 as Selection }
 
+/**
+ * Selection helper utilities
+ */
+export declare interface SelectionHelpers {
+    /**
+     * Check if selection is collapsed (cursor)
+     */
+    isCollapsed(selection: Selection_2): boolean;
+    /**
+     * Check if selection spans multiple blocks
+     */
+    isMultiBlock(selection: Selection_2): boolean;
+    /**
+     * Get the direction of selection (forward/backward)
+     */
+    getDirection(selection: Selection_2): 'forward' | 'backward' | 'none';
+    /**
+     * Create a collapsed selection at a position
+     */
+    createCollapsed(position: Position): Selection_2;
+    /**
+     * Create a selection range
+     */
+    createRange(start: Position, end: Position): Selection_2;
+}
+
+/**
+ * Selection helper implementation
+ */
+export declare const selectionHelpers: SelectionHelpers;
+
 /**
  * Set attributes on a block
  */
@@ -962,6 +1298,27 @@ export declare interface SetAttrsOp extends BaseOperation {
     attrs: BlockAttrs;
 }
 
+/**
+ * Table cell structure
+ */
+export declare interface TableCell {
+    id?: string;
+    content: string;
+    rowSpan?: number;
+    colSpan?: number;
+    attrs?: {
+        style?: Record<string, string | number>;
+        [key: string]: unknown;
+    };
+}
+
+/**
+ * Table structure for attributes
+ */
+export declare interface TableData {
+    rows: TableRow[];
+}
+
 /**
  * Table operation: delete column
  */
@@ -1018,6 +1375,18 @@ export declare interface TableMergeCellsOp extends BaseOperation {
     };
 }
 
+/**
+ * Table row structure
+ */
+export declare interface TableRow {
+    id?: string;
+    cells: TableCell[];
+    attrs?: {
+        style?: Record<string, string | number>;
+        [key: string]: unknown;
+    };
+}
+
 /**
  * Table operation: split cell
  */
@@ -1075,6 +1444,16 @@ export declare function validateDelta(delta: Delta): {
  */
 export declare type ValidationConstraint = 'noDanglingRefs' | 'tableGridConsistent' | 'altOrDecorative' | 'rtlIntegrity' | string;
 
+/**
+ * Validation constraints for document structure
+ */
+export declare const ValidationConstraints: {
+    readonly NO_DANGLING_REFS: "noDanglingRefs";
+    readonly TABLE_GRID_CONSISTENT: "tableGridConsistent";
+    readonly ALT_OR_DECORATIVE: "altOrDecorative";
+    readonly RTL_INTEGRITY: "rtlIntegrity";
+};
+
 export declare const VERSION = "0.0.1";
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@notectl/core",
-  "version": "0.0.2",
+  "version": "0.0.5",
   "description": "Framework-agnostic rich text editor core for Notectl",
   "type": "module",
   "main": "./dist/notectl-core.umd.cjs",
@@ -51,7 +51,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/neuravision-io/notectl.git",
+    "url": "git+https://github.com/Samyssmile/notectl.git",
     "directory": "packages/core"
   }
 }