@notectl/core 1.0.0 → 1.0.3

package/README.md

@@ -28,6 +28,7 @@ Most editors bolt formatting on top of `contenteditable` and hope for the best.
 - **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
+- **Native Angular integration** — available as [`@notectl/angular`](https://www.npmjs.com/package/@notectl/angular) for idiomatic Angular usage
 - **Tiny dependency footprint** — single runtime dependency (DOMPurify)
 
 <br />
@@ -37,6 +38,7 @@ Check out the [live playground](https://samyssmile.github.io/notectl/playground/
 
 ## Wanna see full working example?
 `examples/vanillajs/` is a great place to see everything in action.
+`examples/angular/` shows how to use notectl in Angular with the `@notectl/angular` package.
 
 ## Quick Start
 
@@ -52,15 +54,16 @@ npm install @notectl/core
 ```ts
 import {
   createEditor,
+  ThemePreset,
   TextFormattingPlugin,
   HeadingPlugin,
   ListPlugin,
   LinkPlugin,
   TablePlugin,
-  ToolbarPlugin,
 } from '@notectl/core';
 
 const editor = await createEditor({
+  theme: ThemePreset.Light,
   toolbar: [
     [new TextFormattingPlugin({ bold: true, italic: true, underline: true })],
     [new HeadingPlugin()],
@@ -74,7 +77,7 @@ const editor = await createEditor({
 document.body.appendChild(editor);
 ```
 
-That's it. A full-featured editor in 15 lines.
+That's it. A full-featured editor in 16 lines. `ThemePreset.Light` and `ThemePreset.Dark` are available out of the box.
 
 <br />
 

package/dist/index.d.ts

@@ -122,6 +122,21 @@ export declare class BlockquotePlugin implements Plugin_2 {
     private setBlockType;
 }
 
+export declare interface BlockTypePickerEntry {
+    /** Unique identifier, e.g. 'heading-1', 'footer'. */
+    readonly id: string;
+    /** Display label shown in the picker, e.g. 'Heading 1'. */
+    readonly label: string;
+    /** Command to execute when the entry is selected. */
+    readonly command: string;
+    /** Sort order — lower values appear first. */
+    readonly priority: number;
+    /** Optional styling for the label in the picker dropdown. */
+    readonly style?: PickerEntryStyle;
+    /** Returns true when this entry matches the current block type. */
+    isActive(state: EditorState): boolean;
+}
+
 export declare interface BoldMark extends Mark {
     readonly type: MarkTypeName & 'bold';
 }
@@ -194,6 +209,28 @@ export declare interface CodeBlockConfig {
     readonly textColor?: string;
     /** Default header/label text color (overrides --notectl-code-block-header-color). */
     readonly headerColor?: string;
+    /** Customize keyboard bindings for code block actions. */
+    readonly keymap?: CodeBlockKeymap;
+}
+
+/**
+ * Configurable keyboard bindings for CodeBlockPlugin actions.
+ * Omit a slot to use the default; set to `null` to disable the binding.
+ *
+ * Key descriptor format: `'Mod-Enter'`, `'Mod-Shift-M'`, etc.
+ * `Mod` resolves to Cmd on macOS, Ctrl on Windows/Linux.
+ */
+export declare interface CodeBlockKeymap {
+    /**
+     * Insert a new paragraph below the code block and move the cursor there.
+     * @default 'Mod-Enter'
+     */
+    readonly insertAfter?: string | null;
+    /**
+     * Toggle the current block between code block and paragraph.
+     * @default 'Mod-Shift-M'
+     */
+    readonly toggle?: string | null;
 }
 
 export declare class CodeBlockPlugin implements Plugin_2 {
@@ -201,10 +238,12 @@ export declare class CodeBlockPlugin implements Plugin_2 {
     readonly name = "Code Block";
     readonly priority = 36;
     private readonly config;
+    private readonly resolvedKeymap;
     private context;
     constructor(config?: Partial<CodeBlockConfig>);
     init(context: PluginContext): void;
     destroy(): void;
+    onStateChange(oldState: EditorState, newState: EditorState, _tr: Transaction): void;
     decorations(state: EditorState): DecorationSet;
     private registerNodeSpec;
     private registerNodeView;
@@ -234,6 +273,21 @@ export declare class CodeBlockPlugin implements Plugin_2 {
      * Exits to the previous block.
      */
     private handleArrowUp;
+    /**
+     * Handles ArrowRight at the end of a code block.
+     * Exits to the next block or creates a paragraph below.
+     */
+    private handleArrowRight;
+    /**
+     * Handles ArrowLeft at the start of a code block.
+     * Exits to the previous block at end.
+     */
+    private handleArrowLeft;
+    /**
+     * Handles Mod+Enter: always creates a paragraph below and moves cursor there.
+     */
+    private handleModEnter;
+    private setBlockFocused;
     private toggleCodeBlock;
     private insertCodeBlock;
     private exitOnDoubleEnter;
@@ -751,6 +805,7 @@ export declare class HeadingPlugin implements Plugin_2 {
     private registerCommands;
     private registerKeymaps;
     private registerInputRules;
+    private registerPickerEntries;
     private registerToolbarItem;
     private updateComboLabel;
     private getActiveLabel;
@@ -1286,6 +1341,14 @@ export declare interface NodeSpec<T extends string = string> {
     readonly parseHTML?: readonly ParseRule[];
     /** Tags and attributes this spec needs through DOMPurify sanitization. */
     readonly sanitize?: SanitizeConfig;
+    /**
+     * If provided, the Reconciler groups consecutive blocks with the same
+     * wrapper key into a shared wrapper element. Useful for semantic list
+     * wrappers (`<ul>`, `<ol>`) around `<li>` block elements.
+     */
+    wrapper?(node: Omit<BlockNode, 'attrs'> & {
+        readonly attrs: NodeAttrsFor<T>;
+    }): WrapperSpec;
 }
 
 /** @deprecated Use {@link NodeTypeName} for new code. */
@@ -1413,7 +1476,7 @@ export declare class NotectlEditor extends HTMLElement {
     private emit;
     private onStateChange;
     private updateEmptyState;
-    private announceFormatChange;
+    private announceStateChange;
     private replaceState;
     private serializeBlock;
     private serializeInlineContent;
@@ -1462,6 +1525,11 @@ export declare interface PartialTheme {
     readonly tooltip?: Partial<ThemeTooltip>;
 }
 
+export declare interface PickerEntryStyle {
+    readonly fontSize: string;
+    readonly fontWeight: string;
+}
+
 declare interface Plugin_2<TConfig extends Record<string, unknown> = Record<string, unknown>> {
     readonly id: string;
     readonly name: string;
@@ -1504,7 +1572,10 @@ export declare interface PluginContext {
     registerToolbarItem(item: ToolbarItem): void;
     registerInlineNodeSpec<T extends string>(spec: InlineNodeSpec<T>): void;
     registerFileHandler(pattern: string, handler: FileHandler): void;
+    registerBlockTypePickerEntry(entry: BlockTypePickerEntry): void;
     getSchemaRegistry(): SchemaRegistry;
+    /** Pushes a screen reader announcement via the editor's aria-live region. */
+    announce(text: string): void;
 }
 
 export declare interface PluginEventBus {
@@ -1573,6 +1644,8 @@ export declare interface PluginManagerInitOptions {
     dispatch(transaction: Transaction): void;
     getContainer(): HTMLElement;
     getPluginContainer(position: 'top' | 'bottom'): HTMLElement;
+    /** Pushes a screen reader announcement via the editor's aria-live region. */
+    announce?(text: string): void;
     /** Called after all plugin init() calls complete, before onReady(). */
     onBeforeReady?(): void | Promise<void>;
 }
@@ -1660,6 +1733,7 @@ export declare class SchemaRegistry {
     private readonly _toolbarItems;
     private readonly _toolbarItemPluginMap;
     private readonly _fileHandlers;
+    private readonly _blockTypePickerEntries;
     registerNodeSpec<T extends string>(spec: NodeSpec<T>): void;
     getNodeSpec(type: string): NodeSpec | undefined;
     removeNodeSpec(type: string): void;
@@ -1690,6 +1764,9 @@ export declare class SchemaRegistry {
     getFileHandlers(): readonly FileHandlerEntry[];
     matchFileHandlers(mimeType: string): FileHandler[];
     removeFileHandler(handler: FileHandler): void;
+    registerBlockTypePickerEntry(entry: BlockTypePickerEntry): void;
+    getBlockTypePickerEntries(): readonly BlockTypePickerEntry[];
+    removeBlockTypePickerEntry(id: string): void;
     /** Returns all NodeSpec parseHTML rules, sorted by priority descending. */
     getBlockParseRules(): readonly {
         readonly rule: ParseRule;
@@ -2126,37 +2203,38 @@ export declare class ToolbarPlugin implements Plugin_2 {
     private context;
     private toolbarElement;
     private buttons;
-    private activePopup;
-    private closePopupHandler;
     private readonly hiddenItems;
-    private tooltipElement;
-    private tooltipTimer;
     private readonly layoutConfig;
+    private focusedIndex;
+    private tooltip;
+    private popupController;
     constructor(layoutConfig?: ToolbarLayoutConfig);
     init(context: PluginContext): void;
     onReady(): void;
     destroy(): void;
     onStateChange(_oldState: EditorState, newState: EditorState, _tr: Transaction): void;
     onConfigure(config: PluginConfig): void;
-    private createTooltipElement;
-    private showTooltip;
-    private hideTooltip;
     private createToolbarElement;
     private renderItems;
+    private initRovingTabindex;
+    private setRovingFocus;
+    /** Returns the active element, respecting shadow DOM boundaries. */
+    private getActiveElement;
+    private syncFocusedIndex;
+    private handleToolbarKeydown;
+    /** Activates a toolbar button (shared between mouse click and keyboard). */
+    private activateButton;
     private renderItemsByLayout;
     private renderItemsByPriority;
     private createButton;
-    private activePopupButton;
-    private togglePopup;
-    private closePopup;
-    private renderGridPicker;
-    private renderDropdown;
     private updateButtonStates;
 }
 
 export declare interface ToolbarServiceAPI {
     /** Re-reads isActive/isEnabled from state and updates all buttons. */
     refresh(): void;
+    /** Closes the currently open popup, if any. */
+    closePopup(): void;
 }
 
 export declare const ToolbarServiceKey: ServiceKey<ToolbarServiceAPI>;
@@ -2229,6 +2307,7 @@ export declare class TransactionBuilder {
 export declare interface TransactionMetadata {
     readonly origin: TransactionOrigin;
     readonly timestamp: number;
+    readonly historyDirection?: 'undo' | 'redo';
 }
 
 export declare type TransactionMiddleware = (tr: Transaction, state: EditorState, next: MiddlewareNext) => void;
@@ -2266,4 +2345,16 @@ export declare function widgetDecoration(blockId: BlockId, offset: number, toDOM
     readonly key?: string;
 }): WidgetDecoration;
 
+/** Describes a wrapper element that groups consecutive blocks of the same kind. */
+export declare interface WrapperSpec {
+    /** The HTML tag for the wrapper element (e.g., 'ul', 'ol'). */
+    readonly tag: string;
+    /** A key to group consecutive blocks. Blocks with the same key share a wrapper. */
+    readonly key: string;
+    /** Optional CSS class for the wrapper element. */
+    readonly className?: string;
+    /** Optional attributes for the wrapper element. */
+    readonly attrs?: Readonly<Record<string, string>>;
+}
+
 export { }