@notectl/core 0.0.6 → 0.0.8

package/README.md

@@ -0,0 +1,246 @@
+<div align="center">
+
+# notectl
+
+**A modern rich text editor, shipped as a single Web Component.**
+
+Built on immutable state, a transaction-based architecture, and a plugin system that powers every feature — from bold text to full table editing.
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Web Component](https://img.shields.io/badge/Web_Component-%3Cnotectl--editor%3E-purple)](https://developer.mozilla.org/en-US/docs/Web/API/Web_components)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![npm](https://img.shields.io/npm/v/@notectl/core)](https://www.npmjs.com/package/@notectl/core)
+
+<br />
+
+<img src="docs-site/src/assets/screenshots/hero-editor-rich.png" alt="notectl editor with rich content" width="720" />
+
+</div>
+
+<br />
+
+## Why notectl?
+
+Most editors bolt formatting on top of `contenteditable` and hope for the best. notectl takes a different approach: every keystroke produces an immutable transaction, every feature is a plugin, and the DOM is a projection of state — never the source of truth.
+
+- **Web Component** — drop `<notectl-editor>` into any framework or vanilla HTML
+- **Plugin architecture** — every feature (bold, tables, lists, ...) is a plugin; add only what you need
+- **Immutable state** — predictable updates, time-travel undo/redo, zero mutation bugs
+- **Transaction system** — atomic, invertible steps with middleware support
+- **Zero framework lock-in** — works with React, Vue, Svelte, Angular, or plain JS
+- **Tiny dependency footprint** — single runtime dependency (DOMPurify)
+
+<br />
+
+## Quick Start
+
+### Install
+
+```bash
+npm install @notectl/core
+```
+
+### Use
+
+```ts
+import {
+  createEditor,
+  TextFormattingPlugin,
+  HeadingPlugin,
+  ListPlugin,
+  LinkPlugin,
+  TablePlugin,
+  ToolbarPlugin,
+} from '@notectl/core';
+
+const editor = await createEditor({
+  toolbar: [
+    [new TextFormattingPlugin({ bold: true, italic: true, underline: true })],
+    [new HeadingPlugin()],
+    [new ListPlugin()],
+    [new LinkPlugin(), new TablePlugin()],
+  ],
+  placeholder: 'Start typing...',
+  autofocus: true,
+});
+
+document.body.appendChild(editor);
+```
+
+That's it. A full-featured editor in 15 lines.
+
+<br />
+
+## Plugins
+
+Every capability is a plugin. Compose exactly the editor you need.
+
+| Plugin | What it does |
+|---|---|
+| **TextFormattingPlugin** | Bold, italic, underline — individually toggleable |
+| **StrikethroughPlugin** | ~~Strikethrough~~ text |
+| **HeadingPlugin** | H1 – H6 headings |
+| **BlockquotePlugin** | Block quotes |
+| **ListPlugin** | Bullet and ordered lists |
+| **LinkPlugin** | Hyperlink insertion and editing |
+| **TablePlugin** | Full table support with row/column controls |
+| **TextColorPlugin** | Text color picker |
+| **TextAlignmentPlugin** | Left, center, right, justify |
+| **FontPlugin** | Font family selection with custom font support |
+| **FontSizePlugin** | Configurable font sizes |
+| **HorizontalRulePlugin** | Horizontal dividers |
+| **SuperSubPlugin** | Superscript and subscript |
+| **HighlightPlugin** | Text highlighting / background color |
+| **ToolbarPlugin** | Visual toolbar with grouped items |
+
+### Tables
+
+Full table editing — add/remove rows and columns, navigate with Tab, resize, and select.
+
+<div align="center">
+<img src="docs-site/src/assets/screenshots/editor-table-showcase.png" alt="Table editing in notectl" width="720" />
+</div>
+
+<br />
+
+## Content API
+
+Read and write content in multiple formats:
+
+```ts
+// JSON (immutable Document)
+const doc = editor.getJSON();
+editor.setJSON(doc);
+
+// HTML (sanitized via DOMPurify)
+const html = editor.getHTML();
+editor.setHTML('<p>Hello <strong>world</strong></p>');
+
+// Plain text
+const text = editor.getText();
+
+// State
+editor.isEmpty(); // true | false
+```
+
+## Command API
+
+```ts
+editor.commands.toggleBold();
+editor.commands.toggleItalic();
+editor.commands.toggleUnderline();
+editor.commands.undo();
+editor.commands.redo();
+editor.commands.selectAll();
+```
+
+## Events
+
+```ts
+editor.on('stateChange', ({ oldState, newState, transaction }) => { /* ... */ });
+editor.on('selectionChange', ({ selection }) => { /* ... */ });
+editor.on('ready', () => { /* ... */ });
+editor.on('focus', () => { /* ... */ });
+editor.on('blur', () => { /* ... */ });
+```
+
+<br />
+
+## Custom Fonts
+
+Bring your own fonts — notectl handles `@font-face` injection automatically.
+
+```ts
+import { FontPlugin, STARTER_FONTS } from '@notectl/core';
+
+const Inter = {
+  name: 'Inter',
+  family: "'Inter', sans-serif",
+  category: 'sans-serif',
+  fontFaces: [
+    {
+      src: "url('/fonts/Inter-Variable.ttf') format('truetype')",
+      weight: '100 900',
+      style: 'normal',
+    },
+  ],
+};
+
+new FontPlugin({ fonts: [...STARTER_FONTS, Inter] });
+```
+
+<br />
+
+## Toolbar Configuration
+
+Group plugins into toolbar sections for a clean UI:
+
+```ts
+const editor = await createEditor({
+  toolbar: [
+    [new FontPlugin(), new FontSizePlugin()],
+    [new TextFormattingPlugin(), new StrikethroughPlugin(), new TextColorPlugin()],
+    [new HeadingPlugin(), new BlockquotePlugin()],
+    [new TextAlignmentPlugin()],
+    [new ListPlugin()],
+    [new LinkPlugin(), new TablePlugin(), new HorizontalRulePlugin()],
+  ],
+});
+```
+
+Each inner array becomes a visually separated group in the toolbar.
+
+<br />
+
+## Examples
+
+Check out the full working example in [`examples/vanillajs`](examples/vanillajs) — it demonstrates every plugin, custom font loading, toolbar grouping, and the complete content API.
+
+```bash
+git clone https://github.com/Samyssmile/notectl.git
+cd notectl
+pnpm install
+pnpm dev
+```
+
+<br />
+
+## Architecture
+
+```
+Input Event → InputHandler / KeyboardHandler
+  → Transaction with atomic Steps
+  → Middleware chain (priority-ordered)
+  → EditorState.apply(tr) → new immutable EditorState
+  → Reconciler patches DOM (block-level diffing)
+  → Plugins notified via onStateChange()
+```
+
+| Layer | Responsibility |
+|---|---|
+| `model/` | Immutable data — Document, BlockNode, TextNode, Mark, Selection |
+| `state/` | EditorState, Transaction, StepApplication, History |
+| `view/` | DOM rendering, Reconciler, SelectionSync |
+| `input/` | Keyboard/input handling, paste, input rules |
+| `commands/` | High-level operations (toggleMark, splitBlock, ...) |
+| `plugins/` | All features — every capability is a plugin |
+| `editor/` | `<notectl-editor>` Web Component public API |
+
+<br />
+
+## Development
+
+```bash
+pnpm install          # install dependencies
+pnpm build            # build all packages
+pnpm test             # run unit tests (vitest + happy-dom)
+pnpm test:e2e         # run e2e tests (playwright)
+pnpm lint             # lint (biome)
+pnpm typecheck        # type check
+```
+
+<br />
+
+## License
+
+[MIT](LICENSE)

package/dist/index.d.ts

@@ -142,6 +142,9 @@ export declare function createEditor(config?: NotectlEditorConfig): Promise<Note
 /** Creates a new {@link InlineNode}. */
 export declare function createInlineNode(inlineType: InlineTypeName, attrs?: Readonly<Record<string, string | number | boolean>>): InlineNode;
 
+/** Creates a NodeSelection for the given block. */
+export declare function createNodeSelection(nodeId: BlockId, path: readonly BlockId[]): NodeSelection;
+
 /** Creates a Position, optionally with a path. */
 export declare function createPosition(blockId: BlockId, offset: number, path?: readonly BlockId[]): Position;
 
@@ -205,6 +208,12 @@ export declare function deleteBackward(state: EditorState): Transaction | null;
 /** Handles delete key. */
 export declare function deleteForward(state: EditorState): Transaction | null;
 
+/**
+ * Deletes the void block targeted by a NodeSelection and places cursor
+ * on the adjacent block. If it's the only block, replaces with empty paragraph.
+ */
+export declare function deleteNodeSelection(state: EditorState, sel: NodeSelection): Transaction | null;
+
 /** Deletes the current selection. */
 export declare function deleteSelectionCommand(state: EditorState): Transaction | null;
 
@@ -232,9 +241,12 @@ export declare interface DropdownConfig {
     }[];
 }
 
+/** Union type representing either a text selection or a node selection. */
+export declare type EditorSelection = Selection_2 | NodeSelection;
+
 export declare class EditorState {
     readonly doc: Document_2;
-    readonly selection: Selection_2;
+    readonly selection: EditorSelection;
     readonly storedMarks: readonly Mark[] | null;
     readonly schema: Schema;
     private _blockMap;
@@ -243,7 +255,7 @@ export declare class EditorState {
     /** Creates a new EditorState with default document. */
     static create(options?: {
         doc?: Document_2;
-        selection?: Selection_2;
+        selection?: EditorSelection;
         schema?: Schema;
     }): EditorState;
     /** Creates a TransactionBuilder from this state. */
@@ -263,7 +275,7 @@ export declare class EditorState {
     /** Deserializes a state from JSON. */
     static fromJSON(json: {
         doc: Document_2;
-        selection: Selection_2;
+        selection: EditorSelection;
     }, schema?: Schema): EditorState;
 }
 
@@ -291,7 +303,7 @@ export declare class EventKey<T> {
 declare type EventMap = {
     stateChange: StateChangeEvent;
     selectionChange: {
-        selection: Selection_2;
+        selection: EditorSelection;
     };
     focus: undefined;
     blur: undefined;
@@ -304,6 +316,14 @@ export declare interface FeatureConfig {
     readonly underline: boolean;
 }
 
+/** Handler for files pasted or dropped into the editor. */
+export declare type FileHandler = (files: readonly File[], position: Position | null) => boolean | Promise<boolean>;
+
+export declare interface FileHandlerEntry {
+    readonly pattern: string;
+    readonly handler: FileHandler;
+}
+
 /**
  * Finds a block node by ID anywhere in the document tree (recursive DFS).
  */
@@ -448,6 +468,12 @@ export declare class FontSizePlugin implements Plugin_2 {
     private registerCommands;
     private registerKeymaps;
     private registerToolbarItem;
+    /**
+     * Sets the configured default font size on the editor content container
+     * so that unformatted text renders at the correct size instead of the
+     * browser default (16px).
+     */
+    private applyDefaultSizeToContainer;
     private updateComboLabel;
     private isFontSizeActive;
     private getActiveSize;
@@ -724,15 +750,16 @@ export declare function invertTransaction(tr: Transaction): Transaction;
 /** Checks whether a value is a {@link BlockNode}. */
 export declare function isBlockNode(node: unknown): node is BlockNode;
 
-/** Returns true if the selection is collapsed (cursor with no range). */
-export declare function isCollapsed(sel: Selection_2): boolean;
+/** Returns true if the selection is collapsed (cursor with no range). NodeSelection is never collapsed. */
+export declare function isCollapsed(sel: EditorSelection): boolean;
 
 /**
  * Returns true if the selection direction is forward (anchor before head).
  * When anchor and head are in the same block, compares offsets.
  * Cross-block ordering uses document order (not determinable here — caller provides block order).
+ * For NodeSelection, always returns true.
  */
-export declare function isForward(sel: Selection_2, blockOrder?: readonly BlockId[]): boolean;
+export declare function isForward(sel: EditorSelection, blockOrder?: readonly BlockId[]): boolean;
 
 /** Checks whether a value is an {@link InlineNode}. */
 export declare function isInlineNode(node: unknown): node is InlineNode;
@@ -770,9 +797,18 @@ export declare function isNodeOfType<T extends keyof NodeAttrRegistry>(node: Blo
     readonly attrs: NodeAttrRegistry[T];
 };
 
+/** Type guard: returns true if the selection is a NodeSelection. */
+export declare function isNodeSelection(sel: EditorSelection): sel is NodeSelection;
+
 /** Checks whether a value is a {@link TextNode}. */
 export declare function isTextNode(node: unknown): node is TextNode;
 
+/** Type guard: returns true if the selection is a text Selection. */
+export declare function isTextSelection(sel: EditorSelection): sel is Selection_2;
+
+/** Returns true if the block with the given ID is a void block (e.g. image, HR). */
+export declare function isVoidBlock(state: EditorState, bid: BlockId): boolean;
+
 export declare interface ItalicMark extends Mark {
     readonly type: MarkTypeName & 'italic';
 }
@@ -894,7 +930,10 @@ export declare function markType(name: string): MarkTypeName;
 /** Semantic name for a mark type (e.g. 'bold', 'link'). */
 export declare type MarkTypeName = Brand<string, 'MarkTypeName'>;
 
-/** Merges the current block with the previous block, respecting isolating boundaries. */
+/**
+ * Merges the current block with the previous block, respecting
+ * isolating boundaries and void blocks.
+ */
 export declare function mergeBlockBackward(state: EditorState): Transaction | null;
 
 export declare interface MergeBlocksStep {
@@ -907,6 +946,12 @@ export declare interface MergeBlocksStep {
 
 export declare type MiddlewareNext = (tr: Transaction) => void;
 
+/**
+ * Navigates arrow keys into/out of void blocks.
+ * Returns a transaction if navigation should create a NodeSelection, or null.
+ */
+export declare function navigateArrowIntoVoid(state: EditorState, direction: 'left' | 'right' | 'up' | 'down'): Transaction | null;
+
 /** Plugins augment this interface to register typed node attributes. */
 export declare interface NodeAttrRegistry {
     paragraph: {
@@ -926,7 +971,7 @@ export declare interface NodeDecoration {
 /** Creates a node decoration that applies to a whole block element. */
 export declare function nodeDecoration(blockId: BlockId, attrs: DecorationAttrs): NodeDecoration;
 
-/** A selection that selects an entire node (e.g. for table selection). */
+/** A selection that selects an entire node (e.g. void blocks, table selection). */
 export declare interface NodeSelection {
     readonly type: 'node';
     readonly nodeId: BlockId;
@@ -1130,6 +1175,7 @@ export declare interface PluginContext {
     registerInputRule(rule: InputRule): void;
     registerToolbarItem(item: ToolbarItem): void;
     registerInlineNodeSpec<T extends string>(spec: InlineNodeSpec<T>): void;
+    registerFileHandler(pattern: string, handler: FileHandler): void;
     getSchemaRegistry(): SchemaRegistry;
 }
 
@@ -1273,6 +1319,7 @@ export declare class SchemaRegistry {
     private readonly _inputRules;
     private readonly _toolbarItems;
     private readonly _toolbarItemPluginMap;
+    private readonly _fileHandlers;
     registerNodeSpec<T extends string>(spec: NodeSpec<T>): void;
     getNodeSpec(type: string): NodeSpec | undefined;
     removeNodeSpec(type: string): void;
@@ -1299,6 +1346,10 @@ export declare class SchemaRegistry {
     getToolbarItem(id: string): ToolbarItem | undefined;
     getToolbarItems(): ToolbarItem[];
     removeToolbarItem(id: string): void;
+    registerFileHandler(pattern: string, handler: FileHandler): void;
+    getFileHandlers(): readonly FileHandlerEntry[];
+    matchFileHandlers(mimeType: string): FileHandler[];
+    removeFileHandler(handler: FileHandler): void;
     clear(): void;
 }
 
@@ -1318,9 +1369,13 @@ export declare interface SelectionRange {
 
 /**
  * Returns a normalized range where `from` is always before `to`.
+ * Throws for NodeSelection — use isNodeSelection() guard first.
  */
 export declare function selectionRange(sel: Selection_2, blockOrder?: readonly BlockId[]): SelectionRange;
 
+/** Compares two EditorSelections for equality. */
+export declare function selectionsEqual(a: EditorSelection, b: EditorSelection): boolean;
+
 /** Type-safe service key for compile-time type checking. */
 export declare class ServiceKey<T> {
     readonly id: string;
@@ -1712,8 +1767,8 @@ export declare const ToolbarServiceKey: ServiceKey<ToolbarServiceAPI>;
 
 export declare interface Transaction {
     readonly steps: readonly Step[];
-    readonly selectionBefore: Selection_2;
-    readonly selectionAfter: Selection_2;
+    readonly selectionBefore: EditorSelection;
+    readonly selectionAfter: EditorSelection;
     readonly storedMarksAfter: readonly Mark[] | null;
     readonly metadata: TransactionMetadata;
 }
@@ -1726,7 +1781,7 @@ export declare class TransactionBuilder {
     private readonly selectionBefore;
     private readonly origin;
     private workingDoc;
-    constructor(currentSelection: Selection_2, currentStoredMarks: readonly Mark[] | null, origin?: TransactionOrigin, doc?: Document_2);
+    constructor(currentSelection: EditorSelection, currentStoredMarks: readonly Mark[] | null, origin?: TransactionOrigin, doc?: Document_2);
     /** Adds an insert-text step. Updates workingDoc if available. */
     insertText(blockId: BlockId, offset: number, text: string, marks: readonly Mark[], segments?: readonly TextSegment[]): this;
     /** Adds a delete-text step with explicit data. Updates workingDoc if available. */
@@ -1764,7 +1819,9 @@ export declare class TransactionBuilder {
     /** Sets attributes on an InlineNode at the given offset. */
     setInlineNodeAttr(blockId: BlockId, offset: number, attrs: Readonly<Record<string, string | number | boolean>>): this;
     /** Sets the selection for the resulting state. */
-    setSelection(selection: Selection_2): this;
+    setSelection(selection: EditorSelection): this;
+    /** Sets a NodeSelection for the resulting state. */
+    setNodeSelection(nodeId: BlockId, path: readonly BlockId[]): this;
     /** Sets stored marks for the resulting state. */
     setStoredMarks(marks: readonly Mark[] | null, previousMarks: readonly Mark[] | null): this;
     /** Builds the final transaction. */