draftly 0.1.0-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,257 @@
+import * as _codemirror_state from '@codemirror/state';
+import { Range, Extension, Facet } from '@codemirror/state';
+import { EditorView, Decoration, KeyBinding, ViewUpdate, WidgetType, ViewPlugin, DecorationSet } from '@codemirror/view';
+import { MarkdownConfig } from '@lezer/markdown';
+
+/**
+ * Context passed to plugin lifecycle methods
+ */
+interface PluginContext {
+    /** Current configuration */
+    readonly config: DraftlyConfig;
+}
+/**
+ * Plugin configuration schema
+ */
+interface PluginConfig {
+    [key: string]: unknown;
+}
+/**
+ * Decoration context passed to plugin decoration builders
+ * Provides access to view state and decoration collection
+ */
+interface DecorationContext {
+    /** The EditorView instance (readonly) */
+    readonly view: EditorView;
+    /** Array to push decorations into (will be sorted automatically) */
+    readonly decorations: Range<Decoration>[];
+    /** Check if selection overlaps with a range (to show raw markdown) */
+    selectionOverlapsRange(from: number, to: number): boolean;
+    /** Check if cursor is within a range */
+    cursorInRange(from: number, to: number): boolean;
+}
+/**
+ * Abstract base class for all draftly plugins
+ *
+ * Implements OOP principles:
+ * - Abstraction: abstract name/version must be implemented by subclasses
+ * - Encapsulation: private _config, protected _context
+ * - Inheritance: specialized plugin classes can extend this
+ */
+declare abstract class DraftlyPlugin {
+    /** Unique plugin identifier (abstract - must be implemented) */
+    abstract readonly name: string;
+    /** Plugin version (abstract - must be implemented) */
+    abstract readonly version: string;
+    /** Plugin dependencies - names of required plugins */
+    readonly dependencies: string[];
+    /** Private configuration storage */
+    private _config;
+    /** Protected context - accessible to subclasses */
+    protected _context: PluginContext | null;
+    /** Get plugin configuration */
+    get config(): PluginConfig;
+    /** Set plugin configuration */
+    set config(value: PluginConfig);
+    /** Get plugin context */
+    get context(): PluginContext | null;
+    /**
+     * Return CodeMirror extensions for this plugin
+     * Override to provide custom extensions
+     */
+    getExtensions(): Extension[];
+    /**
+     * Return markdown parser extensions
+     * Override to extend markdown parsing
+     */
+    getMarkdownConfig(): MarkdownConfig | null;
+    /**
+     * Return keybindings for this plugin
+     * Override to add custom keyboard shortcuts
+     */
+    getKeymap(): KeyBinding[];
+    /**
+     * Decoration priority (higher = applied later)
+     * Override to customize priority. Default: 100
+     */
+    get decorationPriority(): number;
+    /**
+     * Build decorations for the current view state
+     * Override to contribute decorations to the editor
+     *
+     * @param ctx - Decoration context with view and decoration array
+     */
+    buildDecorations(_ctx: DecorationContext): void;
+    /**
+     * Called when plugin is registered with draftly
+     * Override to perform initialization
+     *
+     * @param context - Plugin context with configuration
+     */
+    onRegister(context: PluginContext): void | Promise<void>;
+    /**
+     * Called when plugin is unregistered
+     * Override to perform cleanup
+     */
+    onUnregister(): void;
+    /**
+     * Called when EditorView is created and ready
+     * Override to perform view-specific initialization
+     *
+     * @param view - The EditorView instance
+     */
+    onViewReady(_view: EditorView): void;
+    /**
+     * Called on view updates (document changes, selection changes, etc.)
+     * Override to react to editor changes
+     *
+     * @param update - The ViewUpdate with change information
+     */
+    onViewUpdate(_update: ViewUpdate): void;
+    /**
+     * Return ARIA attributes to add to the editor
+     * Override to improve accessibility
+     */
+    getAriaAttributes(): Record<string, string>;
+    /**
+     * Return widget types this plugin provides
+     * Override to contribute custom widgets
+     */
+    getWidgets(): WidgetType[];
+    /**
+     * Helper to get current editor state
+     * @param view - The EditorView instance
+     */
+    protected getState(view: EditorView): _codemirror_state.EditorState;
+    /**
+     * Helper to get current document
+     * @param view - The EditorView instance
+     */
+    protected getDocument(view: EditorView): _codemirror_state.Text;
+}
+/**
+ * Base class for plugins that primarily contribute decorations
+ * Extends DraftlyPlugin with decoration-focused defaults
+ */
+declare abstract class DecorationPlugin extends DraftlyPlugin {
+    /**
+     * Decoration priority - lower than default for decoration plugins
+     * Override to customize
+     */
+    get decorationPriority(): number;
+    /**
+     * Subclasses must implement this to provide decorations
+     * @param ctx - Decoration context
+     */
+    abstract buildDecorations(ctx: DecorationContext): void;
+}
+/**
+ * Base class for plugins that add syntax/parser extensions
+ * Extends DraftlyPlugin with syntax-focused requirements
+ */
+declare abstract class SyntaxPlugin extends DraftlyPlugin {
+    /**
+     * Subclasses must implement this to provide markdown config
+     */
+    abstract getMarkdownConfig(): MarkdownConfig;
+}
+
+/**
+ * DraftlyNode: represents a node in the markdown tree
+ *
+ * Useful for debugging and development
+ */
+type DraftlyNode = {
+    from: number;
+    to: number;
+    name: string;
+    children: DraftlyNode[];
+    isSelected: boolean;
+};
+/**
+ * Configuration options for the draftly editor
+ */
+interface DraftlyConfig {
+    /** Plugins to load */
+    plugins?: DraftlyPlugin[];
+    /** Additional markdown extensions for the parser */
+    markdown?: MarkdownConfig[];
+    /** Additional CodeMirror extensions */
+    extensions?: Extension[];
+    /** Additional keybindings */
+    keymap?: KeyBinding[];
+    /** Disable the built-in view plugin (for raw markdown mode) */
+    disableViewPlugin?: boolean;
+    /** Enable default keybindings */
+    defaultKeybindings?: boolean;
+    /** Enable history */
+    history?: boolean;
+    /** Enable indent with tab */
+    indentWithTab?: boolean;
+    /** Draw selection */
+    drawSelection?: boolean;
+    /** Highlight active line */
+    highlightActiveLine?: boolean;
+    /** Rectangular selection */
+    rectangularSelection?: boolean;
+    /** Line wrapping in raw markdown mode */
+    lineWrapping?: boolean;
+    /** Callback to receive the nodes on every update */
+    onNodesChange?: (nodes: DraftlyNode[]) => void;
+}
+/**
+ * Creates a draftly editor extension bundle for CodeMirror 6
+ *
+ * @param config - Configuration options for the editor
+ * @returns CodeMirror Extension that can be added to EditorState
+ *
+ * @example
+ * ```ts
+ * import { EditorView } from '@codemirror/view';
+ * import { EditorState } from '@codemirror/state';
+ * import { draftly } from 'draftly';
+ *
+ * const view = new EditorView({
+ *   state: EditorState.create({
+ *     doc: '# Hello draftly',
+ *     extensions: [draftly()]
+ *   }),
+ *   parent: document.getElementById('editor')
+ * });
+ * ```
+ */
+declare function draftly(config?: DraftlyConfig): Extension[];
+
+/**
+ * Facet to register plugins with the view plugin
+ */
+declare const DraftlyPluginsFacet: Facet<DraftlyPlugin[], DraftlyPlugin[]>;
+/**
+ * Facet to register the onNodesChange callback
+ */
+declare const draftlyOnNodesChangeFacet: Facet<((nodes: DraftlyNode[]) => void) | undefined, ((nodes: DraftlyNode[]) => void) | undefined>;
+/**
+ * draftly View Plugin
+ * Handles rich markdown rendering with decorations
+ */
+declare class draftlyViewPluginClass {
+    decorations: DecorationSet;
+    private plugins;
+    private onNodesChange?;
+    constructor(view: EditorView);
+    update(update: ViewUpdate): void;
+    private buildNodes;
+}
+/**
+ * The main draftly ViewPlugin extension
+ */
+declare const draftlyViewPlugin: ViewPlugin<draftlyViewPluginClass, undefined>;
+/**
+ * Create draftly view extension bundle with plugin support
+ * @param plugins - Optional array of DraftlyPlugin instances
+ * @param onNodesChange - Optional callback to receive nodes on every update
+ * @returns Extension array including view plugin, theme, and plugin facet
+ */
+declare function createDraftlyViewExtension(plugins?: DraftlyPlugin[], onNodesChange?: (nodes: DraftlyNode[]) => void): Extension[];
+
+export { type DecorationContext, DecorationPlugin, type DraftlyConfig, type DraftlyNode, DraftlyPlugin, DraftlyPluginsFacet, type PluginConfig, type PluginContext, SyntaxPlugin, createDraftlyViewExtension, draftly as default, draftly, draftlyOnNodesChangeFacet, draftlyViewPlugin };