@notectl/core 0.0.11 → 1.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 # notectl
 
-**A modern rich text editor, shipped as a single Web Component.**
+## **A framework-agnostic rich text editor as a Web Component — ship only what you use.**
 
 Built on immutable state, a transaction-based architecture, and a plugin system that powers every feature — from bold text to full table editing.
 
@@ -92,7 +92,7 @@ Every capability is a plugin. Compose exactly the editor you need.
 | **LinkPlugin** | Hyperlink insertion and editing |
 | **TablePlugin** | Full table support with row/column controls |
 | **TextColorPlugin** | Text color picker |
-| **TextAlignmentPlugin** | Left, center, right, justify |
+| **AlignmentPlugin** | Left, center, right, justify |
 | **FontPlugin** | Font family selection with custom font support |
 | **FontSizePlugin** | Configurable font sizes |
 | **HorizontalRulePlugin** | Horizontal dividers |
@@ -188,7 +188,7 @@ const editor = await createEditor({
     [new FontPlugin(), new FontSizePlugin()],
     [new TextFormattingPlugin(), new StrikethroughPlugin(), new TextColorPlugin()],
     [new HeadingPlugin(), new BlockquotePlugin()],
-    [new TextAlignmentPlugin()],
+    [new AlignmentPlugin()],
     [new ListPlugin()],
     [new LinkPlugin(), new TablePlugin(), new HorizontalRulePlugin()],
   ],

package/dist/index.d.ts

@@ -18,6 +18,58 @@ export declare interface AddMarkStep {
     readonly path?: readonly BlockId[];
 }
 
+export declare const ALIGNMENT_ICONS: Readonly<Record<BlockAlignment, string>>;
+
+declare interface AlignmentConfig {
+    /** Which alignments to expose. Defaults to all four. */
+    readonly alignments: readonly BlockAlignment[];
+    /** Block types that support alignment. Defaults to paragraph + heading + title + subtitle + table_cell + image. */
+    readonly alignableTypes: readonly string[];
+    /** Per-type default alignment (e.g. `{ image: 'center' }`). Falls back to `'left'`. */
+    readonly defaults: Readonly<Record<string, BlockAlignment>>;
+    /** When true, a separator is rendered after the toolbar item. */
+    readonly separatorAfter?: boolean;
+}
+export { AlignmentConfig }
+export { AlignmentConfig as TextAlignmentConfig }
+
+declare class AlignmentPlugin implements Plugin_2 {
+    readonly id = "alignment";
+    readonly name = "Alignment";
+    readonly priority = 90;
+    private readonly config;
+    private alignableTypes;
+    constructor(config?: Partial<AlignmentConfig>);
+    init(context: PluginContext): void;
+    /**
+     * Patches existing NodeSpecs for alignable block types to support the
+     * `align` attribute and render it as an inline style. Skips types
+     * that already define an `align` attribute in their spec.
+     */
+    private patchNodeSpecs;
+    private registerCommands;
+    private registerKeymaps;
+    private registerToolbarItem;
+    /**
+     * Preserves the `align` attribute when other plugins change the block
+     * type (e.g. paragraph → heading) via `setBlockType`, which replaces attrs.
+     */
+    private registerMiddleware;
+    /**
+     * Gets the selected block, handling both TextSelection and NodeSelection.
+     */
+    private getSelectedBlock;
+    /**
+     * Gets the block ID of the selected block, handling both selection types.
+     */
+    private getSelectedBlockId;
+    private setAlignment;
+    private isNonDefaultAlignment;
+    private isAlignable;
+}
+export { AlignmentPlugin }
+export { AlignmentPlugin as TextAlignmentPlugin }
+
 /** Applies a single step to a document and returns the new document. */
 export declare function applyStep(doc: Document_2, step: Step): Document_2;
 
@@ -25,6 +77,10 @@ export declare interface AttrSpec {
     readonly default?: string | number | boolean;
 }
 
+declare type BlockAlignment = 'left' | 'center' | 'right' | 'justify';
+export { BlockAlignment }
+export { BlockAlignment as TextAlignment }
+
 export declare interface BlockAttrs {
     readonly [key: string]: string | number | boolean;
 }
@@ -93,6 +149,112 @@ export declare interface CellRange {
 declare type ChildNode_2 = TextNode | InlineNode | BlockNode;
 export { ChildNode_2 as ChildNode }
 
+export declare class ClipboardHandler {
+    private readonly element;
+    private readonly getState;
+    private readonly dispatch;
+    private readonly schemaRegistry?;
+    private readonly syncSelection?;
+    private readonly handleCopy;
+    private readonly handleCut;
+    constructor(element: HTMLElement, options: ClipboardHandlerOptions);
+    private onCopy;
+    private onCut;
+    private writeNodeSelectionToClipboard;
+    private writeTextSelectionToClipboard;
+    /** Serializes a range of inline content within a block to an HTML string. */
+    private serializeBlockRangeToHTML;
+    /** Wraps escaped text in mark HTML tags using MarkSpec.toHTMLString when available. */
+    private serializeTextWithMarks;
+    destroy(): void;
+}
+
+declare interface ClipboardHandlerOptions {
+    readonly getState: GetStateFn;
+    readonly dispatch: DispatchFn;
+    readonly schemaRegistry?: SchemaRegistry;
+    /** Force-sync DOM selection to state (selectionchange may fire async). */
+    readonly syncSelection?: () => void;
+}
+
+export declare const CODE_BLOCK_SERVICE_KEY: ServiceKey<CodeBlockService>;
+
+export declare interface CodeBlockConfig {
+    readonly highlighter?: SyntaxHighlighter;
+    readonly defaultLanguage?: string;
+    readonly useSpaces?: boolean;
+    readonly spaceCount?: number;
+    readonly showCopyButton?: boolean;
+    readonly separatorAfter?: boolean;
+    /** Default body background color (overrides --notectl-code-block-bg). */
+    readonly background?: string;
+    /** Default header background color (overrides --notectl-code-block-header-bg). */
+    readonly headerBackground?: string;
+    /** Default text color (overrides --notectl-code-block-color). */
+    readonly textColor?: string;
+    /** Default header/label text color (overrides --notectl-code-block-header-color). */
+    readonly headerColor?: string;
+}
+
+export declare class CodeBlockPlugin implements Plugin_2 {
+    readonly id = "code-block";
+    readonly name = "Code Block";
+    readonly priority = 36;
+    private readonly config;
+    private context;
+    constructor(config?: Partial<CodeBlockConfig>);
+    init(context: PluginContext): void;
+    destroy(): void;
+    decorations(state: EditorState): DecorationSet;
+    private registerNodeSpec;
+    private registerNodeView;
+    private registerCommands;
+    private registerKeymaps;
+    private registerInputRule;
+    private registerToolbarItem;
+    private registerMiddleware;
+    private registerService;
+    private patchTableCellContent;
+    /**
+     * Handles Backspace at the start of a code block.
+     * Converts the code block back to a paragraph, preserving text.
+     */
+    private handleBackspace;
+    private handleEnter;
+    private handleTab;
+    private handleShiftTab;
+    private handleEscape;
+    /**
+     * Handles ArrowDown at the last line of a code block.
+     * Exits to the next block or creates a paragraph below.
+     */
+    private handleArrowDown;
+    /**
+     * Handles ArrowUp at the first line of a code block.
+     * Exits to the previous block.
+     */
+    private handleArrowUp;
+    private toggleCodeBlock;
+    private insertCodeBlock;
+    private exitOnDoubleEnter;
+    private insertParagraphAfter;
+    private setAttr;
+    /**
+     * Strips all marks from a block's inline content.
+     * Used when converting to code_block so no formatting carries over.
+     */
+    private stripAllMarks;
+}
+
+export declare interface CodeBlockService {
+    setLanguage(blockId: BlockId, language: string): void;
+    getLanguage(blockId: BlockId): string;
+    setBackground(blockId: BlockId, color: string): void;
+    getBackground(blockId: BlockId): string;
+    isCodeBlock(blockId: BlockId): boolean;
+    getSupportedLanguages(): readonly string[];
+}
+
 export declare interface CommandEntry {
     readonly name: string;
     readonly handler: CommandHandler;
@@ -154,6 +316,15 @@ export declare function createSelection(anchor: Position, head: Position): Selec
 /** Creates a new {@link TextNode}. */
 export declare function createTextNode(text: string, marks?: readonly Mark[]): TextNode;
 
+/** Creates a custom theme by extending a base theme with partial overrides. */
+export declare function createTheme(base: Theme, overrides: PartialTheme): Theme;
+
+/** Creates a CSSStyleSheet populated with theme CSS variables. */
+export declare function createThemeStyleSheet(theme: Theme): CSSStyleSheet;
+
+/** Built-in dark theme. */
+export declare const DARK_THEME: Theme;
+
 export declare type Decoration = InlineDecoration | NodeDecoration | WidgetDecoration;
 
 export declare interface DecorationAttrs {
@@ -228,6 +399,8 @@ export declare interface DeleteTextStep {
     readonly path?: readonly BlockId[];
 }
 
+declare type DispatchFn = (tr: Transaction) => void;
+
 declare interface Document_2 {
     readonly children: readonly BlockNode[];
 }
@@ -502,6 +675,9 @@ export declare class FontSizePlugin implements Plugin_2 {
  */
 export declare function formatShortcut(binding: string): string;
 
+/** Generates CSS text with all theme custom properties on :host. */
+export declare function generateThemeCSS(theme: Theme): string;
+
 /** Returns only the BlockNode children of a block. */
 export declare function getBlockChildren(node: BlockNode): readonly BlockNode[];
 
@@ -527,6 +703,8 @@ export declare function getContentAtOffset(block: BlockNode, offset: number): {
 /** Returns the inline content children (TextNode | InlineNode) of a block. */
 export declare function getInlineChildren(node: BlockNode): readonly (TextNode | InlineNode)[];
 
+declare type GetStateFn = () => EditorState;
+
 /** Returns only the TextNode children of a block. */
 export declare function getTextChildren(node: BlockNode): readonly TextNode[];
 
@@ -536,6 +714,16 @@ export declare interface GridPickerConfig {
     onSelect(rows: number, cols: number): void;
 }
 
+export declare class HardBreakPlugin implements Plugin_2 {
+    readonly id = "hard-break";
+    readonly name = "Hard Break";
+    readonly priority = 10;
+    init(context: PluginContext): void;
+    private registerInlineNodeSpec;
+    private registerCommands;
+    private registerKeymap;
+}
+
 /** Returns true if the mark set contains a mark of the given type. */
 export declare function hasMark(marks: readonly Mark[], markType: MarkTypeName): boolean;
 
@@ -569,6 +757,14 @@ export declare class HeadingPlugin implements Plugin_2 {
     private dismissPopup;
     private renderHeadingPopup;
     private createPickerItem;
+    private static readonly HEADING_TYPES;
+    /**
+     * Handles Enter inside a heading block.
+     * Empty heading → convert to paragraph.
+     * Cursor at end → split and convert new block to paragraph.
+     * Cursor in middle → normal split (both stay heading).
+     */
+    private handleEnter;
     /**
      * Toggles between a special block type (title/subtitle) and paragraph.
      * If the block is already that type, resets to paragraph.
@@ -682,6 +878,55 @@ export declare class HorizontalRulePlugin implements Plugin_2 {
     private insertHorizontalRule;
 }
 
+export declare const IMAGE_UPLOAD_SERVICE: ServiceKey<ImageUploadService>;
+
+export declare interface ImageAttrs {
+    readonly src: string;
+    readonly alt: string;
+    readonly width?: number;
+    readonly height?: number;
+    readonly align: 'left' | 'center' | 'right';
+}
+
+export declare class ImagePlugin implements Plugin_2 {
+    readonly id = "image";
+    readonly name = "Image";
+    readonly priority = 45;
+    private readonly config;
+    private readonly uploadStates;
+    private readonly blobUrls;
+    constructor(config?: Partial<ImagePluginConfig>);
+    init(context: PluginContext): void;
+    destroy(): void;
+    onStateChange(_oldState: EditorState, newState: EditorState, _tr: Transaction): void;
+    private registerNodeSpec;
+    private registerNodeView;
+    private registerFileHandler;
+    private handleFileInsert;
+    private uploadFile;
+    private registerToolbarItem;
+    private renderImagePopup;
+    private isAcceptedType;
+}
+
+export declare interface ImagePluginConfig {
+    readonly maxWidth: number;
+    readonly maxFileSize: number;
+    readonly acceptedTypes: readonly string[];
+    readonly resizable: boolean;
+    readonly separatorAfter?: boolean;
+}
+
+export declare interface ImageUploadResult {
+    readonly url: string;
+    readonly width?: number;
+    readonly height?: number;
+}
+
+export declare interface ImageUploadService {
+    upload(file: File): Promise<ImageUploadResult>;
+}
+
 export declare interface InlineDecoration {
     readonly type: 'inline';
     readonly blockId: BlockId;
@@ -735,6 +980,9 @@ export declare interface InputRule {
     handler(state: EditorState, match: RegExpMatchArray, start: number, end: number): Transaction | null;
 }
 
+/** Inserts a hard line break (InlineNode) at the current cursor position. */
+export declare function insertHardBreakCommand(state: EditorState): Transaction | null;
+
 export declare interface InsertInlineNodeStep {
     readonly type: 'insertInlineNode';
     readonly blockId: BlockId;
@@ -847,6 +1095,9 @@ export declare type Keymap = Readonly<Record<string, KeymapHandler>>;
  */
 export declare type KeymapHandler = () => boolean;
 
+/** Built-in light theme. */
+export declare const LIGHT_THEME: Theme;
+
 export declare interface LinkConfig {
     /** Whether to add rel="noopener noreferrer" and target="_blank" by default. */
     readonly openInNewTab: boolean;
@@ -983,7 +1234,7 @@ export declare function navigateArrowIntoVoid(state: EditorState, direction: 'le
 /** Plugins augment this interface to register typed node attributes. */
 export declare interface NodeAttrRegistry {
     paragraph: {
-        textAlign?: TextAlignment;
+        align?: BlockAlignment;
     };
 }
 
@@ -1081,6 +1332,9 @@ export declare class NotectlEditor extends HTMLElement {
     private readonly readyPromise;
     private initialized;
     private preInitPlugins;
+    private themeStyleSheet;
+    private systemThemeQuery;
+    private systemThemeHandler;
     constructor();
     static get observedAttributes(): string[];
     connectedCallback(): void;
@@ -1134,8 +1388,18 @@ export declare class NotectlEditor extends HTMLElement {
     whenReady(): Promise<void>;
     /** Updates configuration at runtime. */
     configure(config: Partial<NotectlEditorConfig>): void;
+    /** Changes the theme at runtime. */
+    setTheme(theme: ThemePreset | Theme): void;
+    /** Returns the current theme setting. */
+    getTheme(): ThemePreset | Theme;
     /** Cleans up the editor. Awaiting ensures async plugin teardown completes. */
     destroy(): Promise<void>;
+    /** Applies a theme. Called during init() and on runtime changes. */
+    private applyTheme;
+    private setThemeStyleSheet;
+    private setupSystemThemeListener;
+    private cleanupSystemThemeListener;
+    private getSystemTheme;
     /**
      * Processes the declarative `toolbar` config: registers a ToolbarPlugin
      * with layout groups, then registers all plugins from the toolbar groups.
@@ -1174,6 +1438,8 @@ export declare interface NotectlEditorConfig {
     readonly?: boolean;
     autofocus?: boolean;
     maxHistoryDepth?: number;
+    /** Theme preset or custom Theme object. Defaults to ThemePreset.Light. */
+    theme?: ThemePreset | Theme;
 }
 
 /**
@@ -1187,6 +1453,15 @@ export declare interface ParseRule {
     readonly priority?: number;
 }
 
+/** Partial custom theme — deeply partial for creating overrides. */
+export declare interface PartialTheme {
+    readonly name: string;
+    readonly primitives?: Partial<ThemePrimitives>;
+    readonly toolbar?: Partial<ThemeToolbar>;
+    readonly codeBlock?: Partial<ThemeCodeBlock>;
+    readonly tooltip?: Partial<ThemeTooltip>;
+}
+
 declare interface Plugin_2<TConfig extends Record<string, unknown> = Record<string, unknown>> {
     readonly id: string;
     readonly name: string;
@@ -1353,6 +1628,9 @@ export declare function resolveParentByPath(doc: Document_2, path: readonly stri
     index: number;
 } | undefined;
 
+/** Resolves a ThemePreset string or Theme object to a full Theme. */
+export declare function resolveTheme(theme: ThemePreset | Theme): Theme;
+
 /**
  * SanitizeConfig: declares which HTML tags and attributes a spec needs
  * to survive DOMPurify sanitization.
@@ -1578,6 +1856,17 @@ export declare interface SuperSubToolbarConfig {
     readonly subscript?: boolean;
 }
 
+export declare interface SyntaxHighlighter {
+    tokenize(code: string, language: string): readonly SyntaxToken[];
+    getSupportedLanguages(): readonly string[];
+}
+
+export declare interface SyntaxToken {
+    readonly from: number;
+    readonly to: number;
+    readonly type: string;
+}
+
 export declare interface TableConfig {
     /** Maximum rows in grid picker. Defaults to 8. */
     readonly maxPickerRows?: number;
@@ -1627,43 +1916,6 @@ export declare interface TableSelectionService {
 
 export declare const TableSelectionServiceKey: ServiceKey<TableSelectionService>;
 
-export declare type TextAlignment = 'left' | 'center' | 'right' | 'justify';
-
-export declare interface TextAlignmentConfig {
-    /** Which alignments to expose. Defaults to all four. */
-    readonly alignments: readonly TextAlignment[];
-    /** Block types that support alignment. Defaults to paragraph + heading. */
-    readonly alignableTypes: readonly string[];
-    /** When true, a separator is rendered after the toolbar item. */
-    readonly separatorAfter?: boolean;
-}
-
-export declare class TextAlignmentPlugin implements Plugin_2 {
-    readonly id = "text-alignment";
-    readonly name = "Text Alignment";
-    readonly priority = 90;
-    private readonly config;
-    private alignableTypes;
-    constructor(config?: Partial<TextAlignmentConfig>);
-    init(context: PluginContext): void;
-    /**
-     * Patches existing NodeSpecs for alignable block types to support the
-     * `textAlign` attribute and render it as an inline style.
-     */
-    private patchNodeSpecs;
-    private registerCommands;
-    private registerKeymaps;
-    private registerToolbarItem;
-    /**
-     * Preserves the `textAlign` attribute when other plugins change the block
-     * type (e.g. paragraph → heading) via `setBlockType`, which replaces attrs.
-     */
-    private registerMiddleware;
-    private setAlignment;
-    private isNonDefaultAlignment;
-    private isAlignable;
-}
-
 export declare interface TextColorConfig {
     /**
      * Restricts the color picker to a specific set of hex colors.
@@ -1740,6 +1992,69 @@ export declare interface TextSegment {
     readonly marks: readonly Mark[];
 }
 
+/** Full theme definition. */
+export declare interface Theme {
+    readonly name: string;
+    readonly primitives: ThemePrimitives;
+    readonly toolbar?: Partial<ThemeToolbar>;
+    readonly codeBlock?: Partial<ThemeCodeBlock>;
+    readonly tooltip?: Partial<ThemeTooltip>;
+}
+
+/** Component-level code block overrides. */
+export declare interface ThemeCodeBlock {
+    readonly background: string;
+    readonly foreground: string;
+    readonly headerBackground: string;
+    readonly headerForeground: string;
+    readonly headerBorder: string;
+}
+
+/** Built-in theme presets. */
+export declare const ThemePreset: {
+    readonly Light: "light";
+    readonly Dark: "dark";
+    readonly System: "system";
+};
+
+export declare type ThemePreset = (typeof ThemePreset)[keyof typeof ThemePreset];
+
+/**
+ * Theme token types, built-in themes, and theme creation helpers.
+ */
+/** Primitive color palette a theme defines. */
+export declare interface ThemePrimitives {
+    readonly background: string;
+    readonly foreground: string;
+    readonly mutedForeground: string;
+    readonly border: string;
+    readonly borderFocus: string;
+    readonly primary: string;
+    readonly primaryForeground: string;
+    readonly primaryMuted: string;
+    readonly surfaceRaised: string;
+    readonly surfaceOverlay: string;
+    readonly hoverBackground: string;
+    readonly activeBackground: string;
+    readonly danger: string;
+    readonly dangerMuted: string;
+    readonly success: string;
+    readonly shadow: string;
+    readonly focusRing: string;
+}
+
+/** Component-level toolbar overrides. */
+export declare interface ThemeToolbar {
+    readonly background: string;
+    readonly borderColor: string;
+}
+
+/** Component-level tooltip overrides. */
+export declare interface ThemeTooltip {
+    readonly background: string;
+    readonly foreground: string;
+}
+
 export declare function toggleBold(state: EditorState, features?: FeatureConfig): Transaction | null;
 
 export declare function toggleItalic(state: EditorState, features?: FeatureConfig): Transaction | null;