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

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

@@ -1,6 +1,7 @@
 import type { BlockToolData, OutputBlockData, OutputData, ToolConfig } from '../../../../types';
 import type { BlockAPI as BlockAPIInterface, Blocks } from '../../../../types/api';
 import type { BlockTuneData } from '../../../../types/block-tunes/block-tune-data';
+import { isInsideTableCell, isRestrictedInTableCell } from '../../../tools/table/table-restrictions';
 import { Module } from '../../__module';
 import { Block } from '../../block';
 import { BlockAPI } from '../../block/api';
@@ -114,7 +115,7 @@ export class BlocksAPI extends Module {
     const block = this.Blok.BlockManager.getBlock(element);
 
     if (block === undefined) {
-      logLabeled(`There is no block corresponding to element <${element.tagName.toLowerCase()}>`, 'warn');
+      logLabeled(`There is no block corresponding to element <${element.tagName?.toLowerCase() ?? 'unknown'}>`, 'warn');
 
       return;
     }
@@ -242,7 +243,21 @@ export class BlocksAPI extends Module {
     replace?: boolean,
     id?: string
   ): BlockAPIInterface => {
-    const tool = type ?? (this.config.defaultBlock);
+    const defaultTool = type ?? (this.config.defaultBlock);
+    const tool = (() => {
+      if (!defaultTool) {
+        return defaultTool;
+      }
+
+      const targetIndex = index ?? this.Blok.BlockManager.currentBlockIndex;
+      const targetBlock = this.Blok.BlockManager.getBlockByIndex(targetIndex);
+
+      if (targetBlock !== undefined && isInsideTableCell(targetBlock) && isRestrictedInTableCell(defaultTool)) {
+        return 'paragraph';
+      }
+
+      return defaultTool;
+    })();
 
     const insertedBlock = this.Blok.BlockManager.insert({
       id,

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/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/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)
    */

package/src/components/utils/popover/components/popover-item/popover-item-default/popover-item-default.ts

@@ -324,6 +324,8 @@ export class PopoverItemDefault extends PopoverItem {
 
     return twMerge(
       css.item,
+      // Asymmetric padding for vertical popovers (better visual balance)
+      !isInline && !isNestedInline && 'pl-2 pr-8',
       isInline && cssInline.item,
       isNestedInline && cssNestedInline.item,
       this.params.isDisabled && css.itemDisabled
@@ -338,7 +340,7 @@ export class PopoverItemDefault extends PopoverItem {
       css.icon,
       isInline && 'w-auto h-auto [&_svg]:w-icon [&_svg]:h-icon mobile:[&_svg]:w-icon-mobile mobile:[&_svg]:h-icon-mobile',
       isNestedInline && 'w-toolbox-btn h-toolbox-btn',
-      iconWithGap && 'mr-2',
+      iconWithGap && 'mr-3',
       iconWithGap && isInline && 'shadow-none bg-transparent !mr-0',
       iconWithGap && isNestedInline && '!mr-2',
       isWobbling && 'animate-wobble'

package/src/components/utils/popover/popover-desktop.ts

@@ -217,31 +217,50 @@ export class PopoverDesktop extends PopoverAbstract {
     this.flipper?.focusItem(0, { skipNextTab: true });
   }
 
+  /**
+   * Updates the popover position dynamically.
+   * Used when the trigger position changes or when positioning at caret location.
+   * @param position - new DOMRect position for the popover
+   */
+  public updatePosition(position: DOMRect): void {
+    this.params.position = position;
+
+    // Recalculate and apply position if already shown
+    if (this.nodes.popover.hasAttribute('data-blok-popover-opened')) {
+      const { top, left } = this.calculatePosition();
+
+      this.nodes.popover.style.top = `${top}px`;
+      this.nodes.popover.style.left = `${left}px`;
+    }
+  }
+
   /**
    * Calculates position for the popover
    */
   private calculatePosition(): { top: number; left: number } {
-    if (!this.trigger) {
+    // Use provided position if available, otherwise fall back to trigger element
+    const rect = this.params.position ?? this.trigger?.getBoundingClientRect();
+
+    if (!rect) {
       return {
         top: 0,
         left: 0,
       };
     }
 
-    const triggerRect = this.trigger.getBoundingClientRect();
     const popoverRect = this.size;
     const windowWidth = window.innerWidth;
     const windowHeight = window.innerHeight;
     const offset = 8;
 
-    const initialTop = triggerRect.bottom + offset + window.scrollY;
-    const shouldFlipTop = (triggerRect.bottom + offset + popoverRect.height > windowHeight + window.scrollY) &&
-      (triggerRect.top - offset - popoverRect.height > window.scrollY);
-    const top = shouldFlipTop ? triggerRect.top - offset - popoverRect.height + window.scrollY : initialTop;
+    const initialTop = rect.bottom + offset + window.scrollY;
+    const shouldFlipTop = (rect.bottom + offset + popoverRect.height > windowHeight + window.scrollY) &&
+      (rect.top - offset - popoverRect.height > window.scrollY);
+    const top = shouldFlipTop ? rect.top - offset - popoverRect.height + window.scrollY : initialTop;
 
-    const initialLeft = triggerRect.left + window.scrollX;
+    const initialLeft = rect.left + window.scrollX;
     const shouldFlipLeft = initialLeft + popoverRect.width > windowWidth + window.scrollX;
-    const left = shouldFlipLeft ? Math.max(0, triggerRect.right - popoverRect.width + window.scrollX) : initialLeft;
+    const left = shouldFlipLeft ? Math.max(0, rect.right - popoverRect.width + window.scrollX) : initialLeft;
 
     return {
       top,