@jackuait/blok 0.6.0-beta.9 → 0.7.0-beta.1

package/src/components/inline-tools/utils/formatting-range-utils.ts

@@ -44,12 +44,15 @@ export const createRangeTextWalker = (range: Range): TreeWalker => {
  * Find first ancestor element matching the predicate
  * @param node - The node to start searching from
  * @param predicate - Function to test elements
+ * @param boundary - Optional node that stops the upward traversal.
+ *                   When reached, the search returns null instead of continuing.
  */
 export const findFormattingAncestor = (
   node: Node | null,
-  predicate: (element: Element) => boolean
+  predicate: (element: Element) => boolean,
+  boundary?: Node
 ): HTMLElement | null => {
-  if (!node) {
+  if (!node || node === boundary) {
     return null;
   }
 
@@ -57,7 +60,7 @@ export const findFormattingAncestor = (
     return node as HTMLElement;
   }
 
-  return findFormattingAncestor(node.parentNode, predicate);
+  return findFormattingAncestor(node.parentNode, predicate, boundary);
 };
 
 /**

package/src/components/inline-tools/utils/marker-dom-utils.ts

@@ -0,0 +1,17 @@
+import { findFormattingAncestor } from './formatting-range-utils';
+
+/**
+ * Check if an element is a <mark> tag
+ * @param element - The element to check
+ */
+export const isMarkTag = (element: Element): boolean => {
+  return element.tagName === 'MARK';
+};
+
+/**
+ * Find closest <mark> ancestor from a node
+ * @param node - The node to start searching from
+ */
+export const findMarkElement = (node: Node | null): HTMLElement | null => {
+  return findFormattingAncestor(node, isMarkTag);
+};

package/src/components/modules/api/blocks.ts

@@ -20,7 +20,12 @@ export class BlocksAPI extends Module {
    * @returns {Blocks}
    */
   public get methods(): Blocks {
+    const blocksAPI = this;
+
     return {
+      get isSyncingFromYjs(): boolean {
+        return blocksAPI.Blok.BlockManager.isSyncingFromYjs;
+      },
       clear: (): Promise<void> => this.clear(),
       render: (data: OutputData): Promise<void> => this.render(data),
       renderFromHTML: (data: string): Promise<void> => this.renderFromHTML(data),
@@ -41,6 +46,7 @@ export class BlocksAPI extends Module {
       setBlockParent: (blockId: string, parentId: string | null): void => this.setBlockParent(blockId, parentId),
       stopBlockMutationWatching: (index: number): void => this.stopBlockMutationWatching(index),
       splitBlock: this.splitBlock,
+      transact: (fn: () => void): void => this.transact(fn),
     };
   }
 
@@ -168,12 +174,12 @@ export class BlocksAPI extends Module {
     }
 
     /**
-     * in case of last block deletion
-     * Insert the new default empty block
+     * Note: default-block insertion when the store is empty is handled
+     * synchronously by removeBlock(block, addLastBlock=true).
+     * A redundant async check here would race with clear()/render()
+     * and could insert a spurious paragraph after the store has been
+     * repopulated by Renderer.
      */
-    if (this.Blok.BlockManager.blocks.length === 0) {
-      this.Blok.BlockManager.insert();
-    }
 
     /**
      * After Block deletion currentBlock is updated
@@ -207,9 +213,14 @@ export class BlocksAPI extends Module {
      * So we need to disable modifications observer temporarily
      */
     this.Blok.ModificationsObserver.disable();
+    this.Blok.Renderer.markRenderStart();
 
-    await this.Blok.BlockManager.clear();
-    await this.Blok.Renderer.render(data.blocks);
+    try {
+      await this.Blok.BlockManager.clear();
+      await this.Blok.Renderer.render(data.blocks);
+    } finally {
+      this.Blok.Renderer.markRenderEnd();
+    }
 
     this.Blok.ModificationsObserver.enable();
   }
@@ -220,9 +231,15 @@ export class BlocksAPI extends Module {
    * @returns {Promise<void>}
    */
   public async renderFromHTML(data: string): Promise<void> {
-    await this.Blok.BlockManager.clear();
+    this.Blok.Renderer.markRenderStart();
+
+    try {
+      await this.Blok.BlockManager.clear();
 
-    return this.Blok.Paste.processText(data, true);
+      return this.Blok.Paste.processText(data, true);
+    } finally {
+      this.Blok.Renderer.markRenderEnd();
+    }
   }
 
   /**
@@ -446,6 +463,14 @@ export class BlocksAPI extends Module {
     return new BlockAPI(newBlock);
   };
 
+  /**
+   * Execute a function within a transaction, grouping all block operations
+   * into a single undo entry.
+   */
+  private transact(fn: () => void): void {
+    this.Blok.BlockManager.transactForTool(fn);
+  }
+
   /**
    * Validated block index and throws an error if it's invalid
    * @param index - index to validate

package/src/components/modules/blockEvents/composers/keyboardNavigation.ts

@@ -43,6 +43,33 @@ export class KeyboardNavigation extends BlockEventComposer {
     return ui.isRtl ?? false;
   }
 
+  /**
+   * Check if the current block is inside a table cell.
+   * Used to prevent closing the toolbar when the user navigates
+   * within a table — closing it makes the toolbar permanently
+   * disappear because the hover controller deduplicates by block id
+   * and all cells resolve to the same parent table block.
+   */
+  private get isCurrentBlockInsideTableCell(): boolean {
+    const currentBlock = this.Blok.BlockManager.currentBlock;
+
+    return Boolean(currentBlock?.holder?.closest('[data-blok-table-cell-blocks]'));
+  }
+
+  /**
+   * Fully close the toolbar if the current block is NOT inside a table cell.
+   * Used for destructive operations (Backspace, Delete, merge) where the
+   * toolbar should be dismissed — unlike arrow navigation where
+   * hideBlockActions() is preferred to allow reopening.
+   */
+  private closeToolbarIfNotInTableCell(): void {
+    if (this.isCurrentBlockInsideTableCell) {
+      return;
+    }
+
+    this.Blok.Toolbar.close();
+  }
+
   /**
    * Tab pressed inside a Block.
    * @param event - keydown event
@@ -105,17 +132,31 @@ export class KeyboardNavigation extends BlockEventComposer {
       return;
     }
 
-    // Force new undo group so block creation is separate from previous typing
-    this.Blok.YjsManager.stopCapturing();
-
-    const blockToFocus = this.createBlockOnEnter(currentBlock);
-
-    this.Blok.Caret.setToBlock(blockToFocus);
+    /**
+     * Capture caret position before block creation so undo can restore it.
+     * Must run before stopCapturing/block insertion since the keyboard capture
+     * handler fires AFTER handleEnter (document capture runs before redactor capture).
+     */
+    this.Blok.YjsManager.markCaretBeforeChange();
 
     /**
-     * Show Toolbar
+     * Use transactForTool to keep the entire Enter operation in a single undo entry:
+     * 1. Calls stopCapturing() to separate from previous typing
+     * 2. Suppresses stopCapturing during block creation + caret movement
+     *    (prevents currentBlockIndex setter from splitting the undo entry
+     *    before async table cell content sync completes)
+     * 3. Calls stopCapturing() in rAF after all async syncs complete
      */
-    this.Blok.Toolbar.moveAndOpen(blockToFocus);
+    this.Blok.BlockManager.transactForTool(() => {
+      const blockToFocus = this.createBlockOnEnter(currentBlock);
+
+      this.Blok.Caret.setToBlock(blockToFocus);
+
+      /**
+       * Show Toolbar
+       */
+      this.Blok.Toolbar.moveAndOpen(blockToFocus);
+    });
 
     event.preventDefault();
   }
@@ -132,27 +173,18 @@ export class KeyboardNavigation extends BlockEventComposer {
    */
   private createBlockOnEnter(currentBlock: Block): Block {
     // Case 1: Caret at start - insert block above
-    if (currentBlock.currentInput !== undefined && isCaretAtStartOfInput(currentBlock.currentInput) && !currentBlock.hasMedia) {
+    if (currentBlock.currentInput !== undefined && isCaretAtStartOfInput(currentBlock.currentInput) && !currentBlock.hasMedia && (currentBlock.parentId === null || !currentBlock.isEmpty)) {
       this.Blok.BlockManager.insertDefaultBlockAtIndex(this.Blok.BlockManager.currentBlockIndex);
 
-      // Force new undo group so typing in the new block is separate from block creation
-      this.Blok.YjsManager.stopCapturing();
-
       return currentBlock;
     }
 
     // Case 2: Caret at end - insert block below
     if (currentBlock.currentInput && isCaretAtEndOfInput(currentBlock.currentInput)) {
-      const newBlock = this.Blok.BlockManager.insertDefaultBlockAtIndex(this.Blok.BlockManager.currentBlockIndex + 1);
-
-      // Force new undo group so typing in the new block is separate from block creation
-      this.Blok.YjsManager.stopCapturing();
-
-      return newBlock;
+      return this.Blok.BlockManager.insertDefaultBlockAtIndex(this.Blok.BlockManager.currentBlockIndex + 1);
     }
 
     // Case 3: Caret in middle - split block
-    // Note: split() uses transact() internally, so it's already atomic - no stopCapturing needed
     return this.Blok.BlockManager.split();
   }
 
@@ -186,7 +218,8 @@ export class KeyboardNavigation extends BlockEventComposer {
      * All the cases below have custom behaviour, so we don't need a native one
      */
     event.preventDefault();
-    this.Blok.Toolbar.close();
+
+    this.closeToolbarIfNotInTableCell();
 
     const isFirstInputFocused = currentBlock.currentInput === currentBlock.firstInput;
 
@@ -273,7 +306,8 @@ export class KeyboardNavigation extends BlockEventComposer {
      * All the cases below have custom behaviour, so we don't need a native one
      */
     event.preventDefault();
-    this.Blok.Toolbar.close();
+
+    this.closeToolbarIfNotInTableCell();
 
     const isLastInputFocused = currentBlock.currentInput === currentBlock.lastInput;
 
@@ -316,7 +350,7 @@ export class KeyboardNavigation extends BlockEventComposer {
       const newCurrentBlock = BlockManager.currentBlock;
 
       newCurrentBlock && Caret.setToBlock(newCurrentBlock, Caret.positions.START);
-      this.Blok.Toolbar.close();
+      this.closeToolbarIfNotInTableCell();
 
       return;
     }
@@ -340,7 +374,7 @@ export class KeyboardNavigation extends BlockEventComposer {
    * @param blockToMerge - what Block we want to merge
    */
   private mergeBlocks(targetBlock: Block, blockToMerge: Block): void {
-    const { BlockManager, Toolbar } = this.Blok;
+    const { BlockManager } = this.Blok;
 
     if (targetBlock.lastInput === undefined) {
       return;
@@ -351,7 +385,7 @@ export class KeyboardNavigation extends BlockEventComposer {
     BlockManager
       .mergeBlocks(targetBlock, blockToMerge)
       .then(() => {
-        Toolbar.close();
+        this.closeToolbarIfNotInTableCell();
       })
       .catch(() => {
         // Error handling for mergeBlocks
@@ -391,9 +425,10 @@ export class KeyboardNavigation extends BlockEventComposer {
     /**
      * Close Toolbar when user moves cursor, but keep toolbars open if the user
      * is extending selection with the Shift key so inline interactions remain available.
+     * Skip closing when inside a table cell — the toolbar belongs to the parent
+     * table block and the hover controller won't re-emit BlockHovered for it.
      */
-    if (!event.shiftKey) {
-      this.Blok.Toolbar.close();
+    if (!event.shiftKey && !this.isCurrentBlockInsideTableCell) {
       this.Blok.InlineToolbar.close();
     }
 
@@ -477,6 +512,11 @@ export class KeyboardNavigation extends BlockEventComposer {
        */
       event.preventDefault();
 
+      /**
+       * Reopen the toolbar at the new block position after navigation
+       */
+      this.Blok.Toolbar.moveAndOpen(this.Blok.BlockManager.currentBlock);
+
       return;
     }
 
@@ -526,15 +566,16 @@ export class KeyboardNavigation extends BlockEventComposer {
       return;
     }
 
-    if (toolbarOpened) {
+    if (toolbarOpened && !this.isCurrentBlockInsideTableCell) {
       this.Blok.UI.closeAllToolbars();
     }
 
     /**
      * Close Toolbar when user moves cursor, but preserve it for Shift-based selection changes.
+     * Skip closing when inside a table cell — the toolbar belongs to the parent
+     * table block and the hover controller won't re-emit BlockHovered for it.
      */
-    if (!event.shiftKey) {
-      this.Blok.Toolbar.close();
+    if (!event.shiftKey && !this.isCurrentBlockInsideTableCell) {
       this.Blok.InlineToolbar.close();
     }
 
@@ -605,6 +646,11 @@ export class KeyboardNavigation extends BlockEventComposer {
        */
       event.preventDefault();
 
+      /**
+       * Reopen the toolbar at the new block position after navigation
+       */
+      this.Blok.Toolbar.moveAndOpen(this.Blok.BlockManager.currentBlock);
+
       return;
     }
 

package/src/components/modules/blockEvents/composers/markdownShortcuts.ts

@@ -1,5 +1,5 @@
 import type { Block } from '../../../block';
-import { HEADER_PATTERN, CHECKLIST_PATTERN, UNORDERED_LIST_PATTERN, ORDERED_LIST_PATTERN, HEADER_TOOL_NAME, LIST_TOOL_NAME } from '../constants';
+import { HEADER_PATTERN, CHECKLIST_PATTERN, UNORDERED_LIST_PATTERN, ORDERED_LIST_PATTERN, TOGGLE_PATTERN, HEADER_TOOL_NAME, LIST_TOOL_NAME, TOGGLE_TOOL_NAME } from '../constants';
 
 import { BlockEventComposer } from './__base';
 
@@ -26,8 +26,9 @@ export class MarkdownShortcuts extends BlockEventComposer {
 
     const handledList = this.handleListShortcut();
     const handledHeader = this.handleHeaderShortcut();
+    const handledToggle = this.handleToggleShortcut();
 
-    return handledList || handledHeader;
+    return handledList || handledHeader || handledToggle;
   }
 
   /**
@@ -207,6 +208,57 @@ export class MarkdownShortcuts extends BlockEventComposer {
     return true;
   }
 
+  /**
+   * Check if current block matches a toggle shortcut pattern ("> ") and convert it.
+   */
+  private handleToggleShortcut(): boolean {
+    const { BlockManager, Tools } = this.Blok;
+    const currentBlock = BlockManager.currentBlock;
+
+    if (!currentBlock) {
+      return false;
+    }
+
+    if (!currentBlock.tool.isDefault) {
+      return false;
+    }
+
+    const toggleTool = Tools.blockTools.get(TOGGLE_TOOL_NAME);
+
+    if (!toggleTool) {
+      return false;
+    }
+
+    const currentInput = currentBlock.currentInput;
+
+    if (!currentInput) {
+      return false;
+    }
+
+    const textContent = currentInput.textContent || '';
+    const match = TOGGLE_PATTERN.exec(textContent);
+
+    if (!match) {
+      return false;
+    }
+
+    this.Blok.YjsManager.stopCapturing();
+
+    const shortcutLength = 2; // "> "
+    const remainingHtml = this.extractRemainingHtml(currentInput, shortcutLength);
+    const caretOffset = this.getCaretOffset(currentInput) - shortcutLength;
+
+    const newBlock = BlockManager.replace(currentBlock, TOGGLE_TOOL_NAME, {
+      text: remainingHtml,
+    });
+
+    this.setCaretAfterConversion(newBlock, caretOffset);
+
+    this.Blok.YjsManager.stopCapturing();
+
+    return true;
+  }
+
   /**
    * Match default header shortcuts like "# ", "## ", etc.
    */

package/src/components/modules/blockEvents/constants.ts

@@ -63,3 +63,15 @@ export const ORDERED_LIST_PATTERN = /^(\d+)[.)]\s([\s\S]*)$/;
  * Captures remaining content after the shortcut in group 2
  */
 export const HEADER_PATTERN = /^(#{1,6})\s([\s\S]*)$/;
+
+/**
+ * Tool name for toggle blocks.
+ */
+export const TOGGLE_TOOL_NAME = 'toggle';
+
+/**
+ * Regex pattern for detecting toggle shortcuts.
+ * Matches ">" followed by a space at the start of text.
+ * Captures remaining content after the shortcut in group 1.
+ */
+export const TOGGLE_PATTERN = /^>\s([\s\S]*)$/;

package/src/components/modules/blockEvents/index.ts

@@ -228,16 +228,13 @@ export class BlockEvents extends Module {
     }
 
     /**
-     * When user type something:
-     *  - close Toolbar
-     *  - clear block highlighting
+     * When user types something, clear block highlighting.
+     * The toolbar stays visible — it should persist during typing.
      */
     if (!isPrintableKeyEvent(event)) {
       return;
     }
 
-    this.Blok.Toolbar.close();
-
     /**
      * Allow to use shortcuts with selected blocks
      * @type {boolean}
@@ -305,6 +302,17 @@ export class BlockEvents extends Module {
       return;
     }
 
+    /**
+     * Eagerly update currentBlock from the event target.
+     * The debounced selectionchange handler (180ms) may not have fired yet
+     * if '/' was typed quickly after clicking into a different block (e.g. a table cell).
+     * Without this, currentBlockIndex is stale and the toolbox checks
+     * the wrong block for table-cell containment, failing to hide restricted tools.
+     */
+    if (event.target instanceof Node) {
+      this.Blok.BlockManager.setCurrentBlockByChildNode(event.target);
+    }
+
     const currentBlock = this.Blok.BlockManager.currentBlock;
     const canOpenToolbox = currentBlock?.isEmpty;
 

package/src/components/modules/blockManager/blockManager.ts

@@ -143,6 +143,14 @@ export class BlockManager extends Module {
     return this.repository.isBlokEmpty();
   }
 
+  /**
+   * Returns true when a Yjs sync operation (undo/redo) is in progress.
+   * Used by the Blocks API to expose sync state to tools.
+   */
+  public get isSyncingFromYjs(): boolean {
+    return this.yjsSync.isSyncingFromYjs;
+  }
+
   /**
    * Index of current working block
    * @type {number}
@@ -186,6 +194,12 @@ export class BlockManager extends Module {
    */
   private yjsSync!: BlockYjsSync;
 
+  /**
+   * Set of parent block IDs awaiting deferred Yjs sync.
+   * Batched via queueMicrotask to avoid multiple syncs during batch operations.
+   */
+  private parentsSyncScheduled = new Set<string>();
+
   /**
    * Operations handler for state changes
    */
@@ -261,8 +275,12 @@ export class BlockManager extends Module {
       this.bindBlockEvents.bind(this)
     );
 
-    // Initialize hierarchy
-    this.hierarchy = new BlockHierarchy(this.repository);
+    // Initialize hierarchy with callback to sync parent data to Yjs
+    this.hierarchy = new BlockHierarchy(this.repository, (parentId) => {
+      if (!this.yjsSync.isSyncingFromYjs) {
+        this.scheduleParentSync(parentId);
+      }
+    });
 
     // Initialize operations first (before yjsSync) to allow circular dependency resolution
     this.operations = new BlockOperations(
@@ -637,6 +655,30 @@ export class BlockManager extends Module {
     return result;
   }
 
+  /**
+   * Execute a function with stopCapturing suppressed.
+   * All block operations within fn are kept in the same undo group.
+   * Used by tools that perform multi-step structural operations
+   * (e.g., table add row = multiple block inserts).
+   */
+  public transactForTool(fn: () => void): void {
+    this.Blok.YjsManager.stopCapturing();
+
+    const prevSuppress = this.operations.suppressStopCapturing;
+
+    this.operations.suppressStopCapturing = true;
+
+    try {
+      fn();
+    } finally {
+      this.operations.suppressStopCapturing = prevSuppress;
+
+      requestAnimationFrame(() => {
+        this.Blok.YjsManager.stopCapturing();
+      });
+    }
+  }
+
   /**
    * Splits a block by updating the current block's data and inserting a new block.
    * Both operations are grouped into a single undo entry.
@@ -682,6 +724,16 @@ export class BlockManager extends Module {
     return this.repository.getBlockById(id);
   }
 
+  /**
+   * Walks up the parentId chain and returns the top-level (root) block.
+   * If the block has no parent, returns it as-is.
+   * @param block - the block to resolve
+   * @returns {Block} the root ancestor block
+   */
+  public resolveToRootBlock(block: Block): Block {
+    return this.repository.resolveToRootBlock(block);
+  }
+
   /**
    * Returns the depth (nesting level) of a block in the hierarchy.
    * @param block - the block to get depth for
@@ -928,6 +980,33 @@ export class BlockManager extends Module {
     return block;
   }
 
+  /**
+   * Schedule a deferred sync of a parent block's data to Yjs.
+   * Uses queueMicrotask to batch multiple parent changes (e.g. when initializing
+   * all cells in a new table row) into a single flush.
+   */
+  private scheduleParentSync(parentId: string): void {
+    if (this.parentsSyncScheduled.size === 0) {
+      queueMicrotask(() => this.flushParentSyncs());
+    }
+    this.parentsSyncScheduled.add(parentId);
+  }
+
+  /**
+   * Flush all scheduled parent syncs to Yjs.
+   * Called from the microtask scheduled by scheduleParentSync.
+   */
+  private flushParentSyncs(): void {
+    for (const parentId of this.parentsSyncScheduled) {
+      const parent = this.repository.getBlockById(parentId);
+
+      if (parent !== undefined) {
+        void this.syncBlockDataToYjs(parent);
+      }
+    }
+    this.parentsSyncScheduled.clear();
+  }
+
   /**
    * Sync block data to Yjs after DOM mutation
    */

package/src/components/modules/blockManager/hierarchy.ts

@@ -12,12 +12,15 @@ import type { BlockRepository } from './repository';
  */
 export class BlockHierarchy {
   private readonly repository: BlockRepository;
+  private readonly onParentChanged?: (parentId: string) => void;
 
   /**
    * @param repository - BlockRepository for looking up blocks by id
+   * @param onParentChanged - optional callback invoked after a block is assigned a non-null parent
    */
-  constructor(repository: BlockRepository) {
+  constructor(repository: BlockRepository, onParentChanged?: (parentId: string) => void) {
     this.repository = repository;
+    this.onParentChanged = onParentChanged;
   }
 
   /**
@@ -73,6 +76,11 @@ export class BlockHierarchy {
 
     // Update visual indentation
     this.updateBlockIndentation(block);
+
+    // Notify listener so parent data can be synced (e.g. to Yjs)
+    if (newParentId !== null && this.onParentChanged !== undefined) {
+      this.onParentChanged(newParentId);
+    }
   }
 
   /**
@@ -80,9 +88,19 @@ export class BlockHierarchy {
    * @param block - the block to update indentation for
    */
   public updateBlockIndentation(block: Block): void {
+    const { holder } = block;
+
+    // Blocks inside table cells should not receive visual indentation.
+    // The parent-child relationship is semantic (data tracking), not visual.
+    if (holder.closest('[data-blok-table-cell-blocks]')) {
+      holder.style.marginLeft = '';
+      holder.setAttribute('data-blok-depth', '0');
+
+      return;
+    }
+
     const depth = this.getBlockDepth(block);
     const indentationPx = depth * 24; // 24px per level
-    const { holder } = block;
 
     holder.style.marginLeft = indentationPx > 0 ? `${indentationPx}px` : '';
     holder.setAttribute('data-blok-depth', depth.toString());