@jackuait/blok 0.6.0-beta.4 → 0.6.0-beta.6

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

@@ -12,9 +12,10 @@ export class ReadOnlyAPI extends Module {
   public get methods(): ReadOnly {
     const getIsEnabled = (): boolean => this.isEnabled;
 
-     
+
     return {
       toggle: (state): Promise<boolean> => this.toggle(state),
+      set: (state): Promise<boolean> => this.set(state),
       get isEnabled(): boolean {
         return getIsEnabled();
       },
@@ -30,6 +31,15 @@ export class ReadOnlyAPI extends Module {
     return this.Blok.ReadOnly.toggle(state);
   }
 
+  /**
+   * Set read-only mode to the specified boolean state
+   * @param {boolean} state - read-only state to set
+   * @returns {Promise<boolean>} the new read-only state
+   */
+  public set(state: boolean): Promise<boolean> {
+    return this.Blok.ReadOnly.set(state);
+  }
+
   /**
    * Returns current read-only state
    */

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

@@ -153,7 +153,18 @@ export class MarkdownShortcuts extends BlockEventComposer {
     const { BlockManager, Tools } = this.Blok;
     const currentBlock = BlockManager.currentBlock;
 
-    if (!currentBlock?.tool.isDefault) {
+    if (!currentBlock) {
+      return false;
+    }
+
+    // Check if inside table cell
+    const isInsideTableCell = currentBlock.holder.closest('[data-blok-table-cell-blocks]') !== null;
+
+    if (isInsideTableCell) {
+      return false; // Don't convert to header
+    }
+
+    if (!currentBlock.tool.isDefault) {
       return false;
     }
 

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

@@ -7,6 +7,7 @@
 import type { BlockToolData, OutputBlockData, PasteEvent } from '../../../../types';
 import type { BlockTuneData } from '../../../../types/block-tunes/block-tune-data';
 import type { BlockMutationEventMap, BlockMutationType } from '../../../../types/events/block';
+import { BlockAddedMutationType } from '../../../../types/events/block/BlockAdded';
 import { BlockChangedMutationType } from '../../../../types/events/block/BlockChanged';
 import { BlockRemovedMutationType } from '../../../../types/events/block/BlockRemoved';
 import { Module } from '../../__module';
@@ -307,6 +308,12 @@ export class BlockManager extends Module {
         replaceBlock: (index, newBlock) => {
           this.blocksStore.replace(index, newBlock);
         },
+        onBlockRemoved: (block, index) => {
+          this.blockDidMutated(BlockRemovedMutationType, block, { index });
+        },
+        onBlockAdded: (block, index) => {
+          this.blockDidMutated(BlockAddedMutationType, block, { index });
+        },
       },
       this.blocksStore
     );

package/src/components/modules/blockManager/yjs-sync.ts

@@ -43,6 +43,10 @@ export interface SyncHandlers {
   updateIndentation: (block: Block) => void;
   /** Called to replace a block at a specific index with a new block instance */
   replaceBlock: (index: number, newBlock: Block) => void;
+  /** Called when a block is removed during undo/redo (before DOM removal) */
+  onBlockRemoved: (block: Block, index: number) => void;
+  /** Called when a block is added during undo/redo (after insertion) */
+  onBlockAdded: (block: Block, index: number) => void;
 }
 
 /**
@@ -273,10 +277,12 @@ export class BlockYjsSync {
         bindEventsImmediately: true,
       });
 
-      // Insert into blocks store at correct position - caller must handle this
-      // This is a limitation - we need the blocksStore.insert method
       this.blocksStore.insert(targetIndex, block);
 
+      // Emit block-added event so listeners (e.g., TableCellBlocks) can
+      // claim the block for the correct cell during undo/redo
+      this.handlers.onBlockAdded(block, targetIndex);
+
       // Apply indentation if needed
       if (parentId !== undefined) {
         this.handlers.updateIndentation(block);
@@ -300,6 +306,10 @@ export class BlockYjsSync {
       return;
     }
 
+    // Emit block-removed event BEFORE removal so listeners can inspect
+    // the block's DOM position (e.g., which table cell it's in)
+    this.handlers.onBlockRemoved(block, index);
+
     // Remove from DOM
     this.blocksStore.remove(index);
 

package/src/components/modules/index.ts

@@ -1,6 +1,7 @@
 import { BlocksAPI } from './api/blocks';
 import { CaretAPI } from './api/caret';
 import { EventsAPI } from './api/events';
+import { HistoryAPI } from './api/history';
 import { I18nAPI } from './api/i18n';
 import { API } from './api/index';
 import { InlineToolbarAPI } from './api/inlineToolbar';
@@ -44,6 +45,7 @@ export {
   BlocksAPI,
   CaretAPI,
   EventsAPI,
+  HistoryAPI,
   I18nAPI,
   API,
   InlineToolbarAPI,
@@ -91,6 +93,7 @@ export const Modules = {
   BlocksAPI,
   CaretAPI,
   EventsAPI,
+  HistoryAPI,
   I18nAPI,
   API,
   InlineToolbarAPI,

package/src/components/modules/readonly.ts

@@ -125,6 +125,17 @@ export class ReadOnly extends Module {
     return this.readOnlyEnabled;
   }
 
+  /**
+   * Set read-only mode to the specified boolean state
+   * Unlike toggle(), this method requires a parameter and does not have default toggle behavior
+   * Call all Modules `toggleReadOnly` method and re-render Blok
+   * @param state - read-only state to set (required)
+   * @returns the new read-only state
+   */
+  public async set(state: boolean): Promise<boolean> {
+    return this.toggle(state);
+  }
+
   /**
    * Throws an error about tools which don't support read-only mode
    */

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

@@ -320,17 +320,15 @@ export class Toolbar extends Module<ToolbarNodes> {
     /**
      * If no one Block selected as a Current
      */
-    const targetBlock = block ?? this.Blok.BlockManager.currentBlock;
+    const unresolvedBlock = block ?? this.Blok.BlockManager.currentBlock;
 
-    if (!targetBlock) {
+    if (!unresolvedBlock) {
       return;
     }
 
-    /**
-     * Don't show toolbar for blocks inside table cells.
-     * Uses the DOM attribute directly to avoid cross-module dependency on the table tool.
-     */
-    if (targetBlock.holder.closest('[data-blok-table-cell-blocks]')) {
+    const targetBlock = this.resolveTableCellBlock(unresolvedBlock);
+
+    if (!targetBlock) {
       this.close();
 
       return;
@@ -562,6 +560,30 @@ export class Toolbar extends Module<ToolbarNodes> {
     this.explicitlyClosed = false;
   }
 
+  /**
+   * If the block is inside a table cell, resolve to the parent table block.
+   * This ensures the toolbar shows for the table when clicking/focusing inside cells.
+   * Uses the DOM attribute directly to avoid cross-module dependency on the table tool.
+   *
+   * @param block - the block to resolve
+   * @returns the parent table block if inside a cell, the original block otherwise, or null if resolution fails
+   */
+  private resolveTableCellBlock(block: Block): Block | null {
+    const cellBlocksContainer = block.holder.closest('[data-blok-table-cell-blocks]');
+
+    if (!cellBlocksContainer) {
+      return block;
+    }
+
+    const tableBlockHolder = cellBlocksContainer.closest('[data-blok-testid="block-wrapper"]');
+
+    if (!tableBlockHolder) {
+      return null;
+    }
+
+    return this.Blok.BlockManager.getBlockByChildNode(tableBlockHolder) ?? null;
+  }
+
   /**
    * Reset the Toolbar position to prevent DOM height growth, for example after blocks deletion
    */

package/src/components/modules/ui.ts

@@ -30,6 +30,7 @@ interface UINodes extends Record<string, unknown> {
   holder: HTMLElement;
   wrapper: HTMLElement;
   redactor: HTMLElement;
+  bottomZone: HTMLElement;
 }
 
 /**
@@ -191,12 +192,11 @@ export class UI extends Module<UINodes> {
     this.selectionController.setWrapperElement(this.nodes.wrapper);
 
     /**
-     * Block hover controller needs content rect getter
+     * Block hover controller detects hover over blocks and finds nearest block
      */
     this.blockHoverController = new BlockHoverController({
       config: this.config,
       eventsDispatcher: this.eventsDispatcher,
-      contentRectGetter: () => this.contentRect,
     });
     this.blockHoverController.state = this.Blok;
 
@@ -452,11 +452,15 @@ export class UI extends Module<UINodes> {
     }
 
     /**
-     * Set customizable bottom zone height
+     * Create dedicated bottom zone element
      */
-    this.nodes.redactor.style.paddingBottom = this.config.minHeight + 'px';
+    this.nodes.bottomZone = $.make('div', ['cursor-text']);
+    this.nodes.bottomZone.setAttribute('data-blok-bottom-zone', '');
+    this.nodes.bottomZone.setAttribute('data-blok-testid', 'bottom-zone');
+    this.nodes.bottomZone.style.minHeight = this.config.minHeight + 'px';
 
     this.nodes.wrapper.appendChild(this.nodes.redactor);
+    this.nodes.wrapper.appendChild(this.nodes.bottomZone);
     this.nodes.holder.appendChild(this.nodes.wrapper);
 
     this.bindReadOnlyInsensitiveListeners();
@@ -541,7 +545,16 @@ export class UI extends Module<UINodes> {
    */
   private bindReadOnlySensitiveListeners(): void {
     /**
-     * Redactor click handler for bottom zone clicks
+     * Bottom zone click handler — creates new block when clicking below last block
+     */
+    this.readOnlyMutableListeners.on(this.nodes.bottomZone, 'click', (event: Event) => {
+      if (event instanceof MouseEvent) {
+        this.bottomZoneClicked(event);
+      }
+    }, false);
+
+    /**
+     * Redactor click handler for Ctrl+click anchor navigation
      */
     this.readOnlyMutableListeners.on(this.nodes.redactor, 'click', (event: Event) => {
       if (event instanceof MouseEvent) {
@@ -610,98 +623,63 @@ export class UI extends Module<UINodes> {
   }
 
   /**
-   * All clicks on the redactor zone
-   * @param {MouseEvent} event - click event
-   * @description
-   * - By clicks on the Blok's bottom zone:
-   *      - if last Block is empty, set a Caret to this
-   *      - otherwise, add a new empty Block and set a Caret to that
+   * Handle click on the bottom zone element below the last block.
+   * Creates a new default block if needed, focuses the last block, and opens the toolbar.
    */
-  private redactorClicked(event: MouseEvent): void {
+  private bottomZoneClicked(event: MouseEvent): void {
     if (!Selection.isCollapsed) {
       return;
     }
 
-    /**
-     * case when user clicks on anchor element
-     * if it is clicked via ctrl key, then we open new window with url
-     */
-    const element = event.target as Element;
-    const ctrlKey = event.metaKey || event.ctrlKey;
-    const shouldOpenAnchorInNewTab = $.isAnchor(element) && ctrlKey;
+    const { BlockSelection, BlockManager, Caret, Toolbar } = this.Blok;
 
-    if (!shouldOpenAnchorInNewTab) {
-      this.processBottomZoneClick(event);
+    if (BlockSelection.anyBlockSelected) {
+      return;
+    }
 
+    if (!BlockManager.lastBlock) {
       return;
     }
 
     event.stopImmediatePropagation();
     event.stopPropagation();
 
-    const href = element.getAttribute('href');
-
-    if (!href) {
-      return;
+    /**
+     * Insert a default-block at the bottom if:
+     * - last-block is not a default-block (Text)
+     * - Or, default-block is not empty
+     */
+    if (!BlockManager.lastBlock.tool.isDefault || !BlockManager.lastBlock.isEmpty) {
+      BlockManager.insertAtEnd();
     }
 
-    const validUrl = getValidUrl(href);
-
-    openTab(validUrl);
+    Caret.setToTheLastBlock();
+    Toolbar.moveAndOpen(BlockManager.lastBlock);
   }
 
   /**
-   * Check if user clicks on the Blok's bottom zone:
-   * - set caret to the last block
-   * - or add new empty block
-   * @param event - click event
+   * Handle Ctrl+click on anchor elements to open in new tab
    */
-  private processBottomZoneClick(event: MouseEvent): void {
-    const lastBlock = this.Blok.BlockManager.getBlockByIndex(-1);
-
-    if (lastBlock === undefined) {
-      return;
-    }
-
-    const lastBlockBottomCoord = $.offset(lastBlock.holder).bottom;
-    const clickedCoord = event.pageY;
-    const { BlockSelection } = this.Blok;
-    const isClickedBottom = event.target instanceof Element &&
-      event.target.isEqualNode(this.nodes.redactor) &&
-      /**
-       * If there is cross block selection started, target will be equal to redactor so we need additional check
-       */
-      !BlockSelection.anyBlockSelected &&
-
-      /**
-       * Prevent caret jumping (to last block) when clicking between blocks
-       */
-      lastBlockBottomCoord < clickedCoord;
+  private redactorClicked(event: MouseEvent): void {
+    const element = event.target as Element;
+    const ctrlKey = event.metaKey || event.ctrlKey;
 
-    if (!isClickedBottom) {
+    if (!$.isAnchor(element) || !ctrlKey) {
       return;
     }
 
     event.stopImmediatePropagation();
     event.stopPropagation();
 
-    const { BlockManager, Caret, Toolbar } = this.Blok;
+    const href = element.getAttribute('href');
 
-    /**
-     * Insert a default-block at the bottom if:
-     * - last-block is not a default-block (Text)
-     *   to prevent unnecessary tree-walking on Tools with many nodes (for ex. Table)
-     * - Or, default-block is not empty
-     */
-    if (!BlockManager.lastBlock?.tool.isDefault || !BlockManager.lastBlock?.isEmpty) {
-      BlockManager.insertAtEnd();
+    if (!href) {
+      return;
     }
 
-    /**
-     * Set the caret and toolbar to empty Block
-     */
-    Caret.setToTheLastBlock();
-    Toolbar.moveAndOpen(BlockManager.lastBlock);
+    const validUrl = getValidUrl(href);
+
+    openTab(validUrl);
   }
 
   /**

package/src/components/modules/uiControllers/controllers/blockHover.ts

@@ -5,20 +5,15 @@ import { throttle } from '../../../utils';
 import { Controller } from './_base';
 
 /**
- * BlockHoverController detects when user hovers over blocks, including extended hover zone.
+ * BlockHoverController detects when user hovers over blocks or finds nearest block.
  *
  * Responsibilities:
  * - Listen to mousemove events (throttled)
- * - Find block by element hit or extended zone
+ * - Find block by element hit or nearest by Y distance
  * - Emit BlockHovered events
  * - Track last hovered block to avoid duplicate events
  */
 export class BlockHoverController extends Controller {
-  /**
-   * Getter function for content rect
-   */
-  private contentRectGetter: () => DOMRect;
-
   /**
    * Used to not emit the same block multiple times to the 'block-hovered' event on every mousemove.
    * Stores block ID to ensure consistent comparison regardless of how the block was detected.
@@ -42,10 +37,8 @@ export class BlockHoverController extends Controller {
   constructor(options: {
     config: Controller['config'];
     eventsDispatcher: Controller['eventsDispatcher'];
-    contentRectGetter: () => DOMRect;
   }) {
     super(options);
-    this.contentRectGetter = options.contentRectGetter;
   }
 
   /**
@@ -83,35 +76,11 @@ export class BlockHoverController extends Controller {
         : closestBlockWrapper;
 
       /**
-       * If no block element found directly, try the extended hover zone
+       * If no block element found directly, find the nearest block by Y distance
        */
-      const zoneBlock = !hoveredBlockElement
-        ? this.findBlockInHoverZone(event.clientX, event.clientY)
-        : null;
-
-      if (zoneBlock !== null && this.blockHoveredState.lastHoveredBlockId !== zoneBlock.id) {
-        /**
-         * Emit the event but DON'T set lastHoveredBlockId for hover zone events.
-         * This allows the event to be emitted again when the mouse enters the actual block element,
-         * which is important for proper toolbar positioning after cross-block selection.
-         */
-        this.eventsDispatcher.emit(BlockHovered, {
-          block: zoneBlock,
-          target: zoneBlock.holder,
-        });
-      }
-
-      if (zoneBlock !== null) {
-        return;
-      }
-
       if (!hoveredBlockElement) {
-        /**
-         * When no block is found (mouse left the editor area), reset the hover state.
-         * This allows hover events to be emitted again when re-entering a block,
-         * which is important after cross-block selection completes.
-         */
-        this.blockHoveredState.lastHoveredBlockId = null;
+        this.emitNearestBlockHovered(event.clientY);
+
         return;
       }
 
@@ -143,9 +112,8 @@ export class BlockHoverController extends Controller {
     );
 
     /**
-     * Listen on document to detect hover in the extended zone
-     * which is outside the wrapper's bounds.
-     * We filter events to only process those over the editor or in the hover zone.
+     * Listen on document to detect hover anywhere on the page.
+     * When cursor is not directly on a block, finds the nearest block by Y distance.
      */
     this.readOnlyMutableListeners.on(document, 'mousemove', (event: Event) => {
       throttledHandleBlockHovered(event);
@@ -155,38 +123,49 @@ export class BlockHoverController extends Controller {
   }
 
   /**
-   * Finds a block by vertical position when cursor is in the hover zone.
-   * The hover zone extends indefinitely on both sides of the content (left and right),
-   * allowing the toolbar to follow hover anywhere outside the content area horizontally.
-   * @param clientX - Cursor X position
+   * Finds and emits a BlockHovered event for the nearest block by Y distance.
+   * Deduplicates by lastHoveredBlockId to avoid redundant events.
    * @param clientY - Cursor Y position
-   * @returns Block at the vertical position, or null if not in hover zone or no block found
    */
-  private findBlockInHoverZone(clientX: number, clientY: number): Block | null {
-    const contentRect = this.contentRectGetter();
+  private emitNearestBlockHovered(clientY: number): void {
+    const nearestBlock = this.findNearestBlock(clientY);
 
-    /**
-     * Check if cursor is outside the content area horizontally (either left OR right side).
-     * The zone extends indefinitely on both sides, not limited to HOVER_ZONE_SIZE.
-     */
-    const isInHoverZone = clientX < contentRect.left || clientX > contentRect.right;
+    if (nearestBlock === null || this.blockHoveredState.lastHoveredBlockId === nearestBlock.id) {
+      return;
+    }
 
-    if (!isInHoverZone) {
+    this.blockHoveredState.lastHoveredBlockId = nearestBlock.id;
+
+    this.eventsDispatcher.emit(BlockHovered, {
+      block: nearestBlock,
+      target: nearestBlock.holder,
+    });
+  }
+
+  /**
+   * Finds the nearest block by vertical distance to cursor position.
+   * Returns the block whose vertical center is closest to the cursor Y position.
+   * If cursor is above all blocks, returns the first block.
+   * If cursor is below all blocks, returns the last block.
+   * @param clientY - Cursor Y position
+   * @returns Nearest block, or null if no blocks exist
+   */
+  private findNearestBlock(clientY: number): Block | null {
+    const blocks = this.Blok.BlockManager.blocks;
+
+    if (blocks.length === 0) {
       return null;
     }
 
-    /**
-     * Find block by Y position
-     */
-    for (const block of this.Blok.BlockManager.blocks) {
+    const result = blocks.reduce<{ block: Block; distance: number }>((nearest, block) => {
       const rect = block.holder.getBoundingClientRect();
+      const centerY = (rect.top + rect.bottom) / 2;
+      const distance = Math.abs(clientY - centerY);
 
-      if (clientY >= rect.top && clientY <= rect.bottom) {
-        return block;
-      }
-    }
+      return distance < nearest.distance ? { block, distance } : nearest;
+    }, { block: blocks[0], distance: Infinity });
 
-    return null;
+    return result.block;
   }
 
   /**

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

@@ -189,6 +189,29 @@ export class YjsManager extends Module {
     this.undoHistory.redo();
   }
 
+  /**
+   * Check if undo is available.
+   * @returns true if undo is available
+   */
+  public canUndo(): boolean {
+    return this.undoHistory.canUndo();
+  }
+
+  /**
+   * Check if redo is available.
+   * @returns true if redo is available
+   */
+  public canRedo(): boolean {
+    return this.undoHistory.canRedo();
+  }
+
+  /**
+   * Clear all history.
+   */
+  public clear(): void {
+    this.undoHistory.clear();
+  }
+
   /**
    * Stop capturing changes into current undo group.
    * Call this to force next change into a new undo entry.

package/src/components/ui/toolbox.ts

@@ -1,5 +1,7 @@
+import { RESTRICTED_TOOLS } from '../../tools/table/table-restrictions';
 import { Dom } from '../dom';
 import { BlokMobileLayoutToggled } from '../events';
+import { SelectionUtils } from '../selection';
 import type { BlockToolAdapter } from '../tools/block';
 import type { ToolsCollection } from '../tools/collection';
 import { beautifyShortcut, capitalize, isMobileScreen } from '../utils';
@@ -155,7 +157,7 @@ export class Toolbox extends EventsDispatcher<ToolboxEventMap> {
 
   /**
    * Whether the toolbox was opened inside a table cell.
-   * Used to restore the table item visibility on close.
+   * Used to restore restricted tool visibility on close.
    */
   private isInsideTableCell = false;
 
@@ -273,17 +275,28 @@ export class Toolbox extends EventsDispatcher<ToolboxEventMap> {
     const currentBlock = this.api.blocks.getBlockByIndex(currentBlockIndex);
 
     /**
-     * Hide the table tool when the caret is inside a table cell
-     * to prevent nested tables.
+     * Hide restricted tools (headers, tables) when the caret is inside a table cell.
      */
     this.isInsideTableCell = currentBlock !== undefined
       && currentBlock.holder.closest('[data-blok-table-cell-blocks]') !== null;
 
     if (this.isInsideTableCell) {
-      this.popover?.toggleItemHiddenByName('table', true);
+      this.toggleRestrictedToolsHidden(true);
     }
 
     this.popover?.show();
+
+    /**
+     * When opening toolbox inside a table cell, position it at the caret
+     * instead of at the trigger element (which is outside the table).
+     * Must be called after show() so the popover is in the DOM.
+     */
+    if (this.isInsideTableCell && this.popover instanceof PopoverDesktop) {
+      const caretRect = SelectionUtils.rect;
+
+      this.popover.updatePosition(caretRect);
+    }
+
     this.opened = true;
     this.emit(ToolboxEvent.Opened);
     this.startListeningToBlockInput();
@@ -294,7 +307,7 @@ export class Toolbox extends EventsDispatcher<ToolboxEventMap> {
    */
   public close(): void {
     if (this.isInsideTableCell) {
-      this.popover?.toggleItemHiddenByName('table', false);
+      this.toggleRestrictedToolsHidden(false);
       this.isInsideTableCell = false;
     }
 
@@ -364,7 +377,7 @@ export class Toolbox extends EventsDispatcher<ToolboxEventMap> {
    */
   private onPopoverClose = (): void => {
     if (this.isInsideTableCell) {
-      this.popover?.toggleItemHiddenByName('table', false);
+      this.toggleRestrictedToolsHidden(false);
       this.isInsideTableCell = false;
     }
 
@@ -373,6 +386,28 @@ export class Toolbox extends EventsDispatcher<ToolboxEventMap> {
     this.emit(ToolboxEvent.Closed);
   };
 
+  /**
+   * Toggles hidden state for all popover items belonging to restricted tools.
+   * Handles tools like header that have multiple entries with custom names (header-1, header-2, etc.)
+   * by matching item names that equal or start with a restricted tool name.
+   */
+  private toggleRestrictedToolsHidden(isHidden: boolean): void {
+    for (const item of this.toolboxItemsToBeDisplayed) {
+      if (!('name' in item) || item.name === undefined) {
+        continue;
+      }
+
+      const { name } = item;
+      const isRestricted = RESTRICTED_TOOLS.some(
+        restricted => name === restricted || name.startsWith(`${restricted}-`)
+      );
+
+      if (isRestricted) {
+        this.popover?.toggleItemHiddenByName(name, isHidden);
+      }
+    }
+  }
+
   /**
    * Returns list of tools that enables the Toolbox (by specifying the 'toolbox' getter)
    */