@jackuait/blok 0.7.1 → 0.7.3-beta.1

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

@@ -3,7 +3,8 @@ import { Flipper } from '../../flipper';
 import { keyCodes } from '../../utils';
 
 import type { PopoverItem, PopoverItemRenderParamsMap } from './components/popover-item';
-import { PopoverItemSeparator, css as popoverItemCls , PopoverItemDefault } from './components/popover-item';
+import { PopoverItemSeparator, css as popoverItemCls, PopoverItemDefault, PopoverItemType } from './components/popover-item';
+import type { PopoverItemParams } from '@/types/utils/popover/popover-item';
 import { PopoverItemHtml } from './components/popover-item/popover-item-html/popover-item-html';
 import type { SearchableItem } from './components/search-input';
 import { SearchInput, SearchInputEvent, scoreSearchMatch } from './components/search-input';
@@ -67,6 +68,14 @@ export class PopoverDesktop extends PopoverAbstract {
    */
   private leftAlignElement: HTMLElement | undefined;
 
+  /**
+   * Updates the element whose left edge is used for horizontal positioning.
+   * @param element - new element to align against, or undefined to fall back to trigger
+   */
+  public setLeftAlignElement(element: HTMLElement | undefined): void {
+    this.leftAlignElement = element;
+  }
+
   /**
    * Popover size cache
    */
@@ -78,6 +87,20 @@ export class PopoverDesktop extends PopoverAbstract {
    */
   private originalItemOrder: Element[] | undefined;
 
+  /**
+   * Cache of promoted items built from nested children.
+   * Built once on first non-empty search, destroyed on clear/hide/destroy.
+   */
+  private promotedItemCache: {
+    items: PopoverItemDefault[];
+    parentChains: Map<PopoverItemDefault, string[]>;
+  } | null = null;
+
+  /**
+   * Temporary group separator elements injected during search.
+   */
+  private promotedSeparators: HTMLElement[] = [];
+
   /**
    * Construct the instance
    * @param params - popover params
@@ -313,6 +336,7 @@ export class PopoverDesktop extends PopoverAbstract {
    * Closes popover
    */
   public hide = (): void => {
+    this.cleanupPromotedItems();
     super.hide();
 
     this.destroyNestedPopoverIfExists();
@@ -405,7 +429,7 @@ export class PopoverDesktop extends PopoverAbstract {
    * Destroys nested popover unless the mouse moved into it.
    * @param event - mouseleave event
    */
-  private handleMouseLeave(event: Event): void {
+  protected handleMouseLeave(event: Event): void {
     const mouseEvent = event as MouseEvent;
     const relatedTarget = mouseEvent.relatedTarget;
 
@@ -422,6 +446,31 @@ export class PopoverDesktop extends PopoverAbstract {
     this.previouslyHoveredItem = null;
   }
 
+  /**
+   * Retrieves popover item that is the target of the specified event.
+   * Overridden to include promoted items from recursive search.
+   * @param event - event to retrieve popover item from
+   */
+  protected override getTargetItem(event: Event): PopoverItemDefault | PopoverItemHtml | undefined {
+    const allItems = this.promotedItemCache !== null
+      ? [...this.items, ...this.promotedItemCache.items]
+      : this.items;
+
+    return allItems
+      .filter((item): item is PopoverItemDefault | PopoverItemHtml =>
+        item instanceof PopoverItemDefault || item instanceof PopoverItemHtml
+      )
+      .find(item => {
+        const itemEl = item.getElement();
+
+        if (itemEl === null) {
+          return false;
+        }
+
+        return event.composedPath().includes(itemEl);
+      });
+  }
+
   /**
    * Sets CSS variable with position of item near which nested popover should be displayed.
    * Is used for correct positioning of the nested popover
@@ -724,6 +773,125 @@ export class PopoverDesktop extends PopoverAbstract {
     focusedItem?.onFocus();
   };
 
+  /**
+   * Builds cache of PopoverItemDefault instances from nested children.
+   * Recursively walks the item tree to arbitrary depth.
+   * Each cached item is mapped to its parent chain for group labeling.
+   */
+  private buildPromotedItemCache(): { items: PopoverItemDefault[]; parentChains: Map<PopoverItemDefault, string[]> } {
+    const cache = {
+      items: [] as PopoverItemDefault[],
+      parentChains: new Map<PopoverItemDefault, string[]>(),
+    };
+
+    this.collectPromotedChildren(this.items, [], cache);
+
+    return cache;
+  }
+
+  /**
+   * Recursively collects default child items from items that have children.
+   * @param items - items to inspect for children
+   * @param parentChain - ancestor label chain accumulated so far
+   * @param cache - mutable cache to populate
+   */
+  private collectPromotedChildren(
+    items: PopoverItem[],
+    parentChain: string[],
+    cache: { items: PopoverItemDefault[]; parentChains: Map<PopoverItemDefault, string[]> }
+  ): void {
+    for (const item of items) {
+      if (!(item instanceof PopoverItemDefault) || !item.hasChildren) {
+        continue;
+      }
+
+      const label = item.title ?? item.name ?? '';
+      const newChain = [...parentChain, label];
+
+      this.collectDefaultChildren(item.children, newChain, cache);
+    }
+  }
+
+  /**
+   * Constructs PopoverItemDefault instances from raw params and adds them to the cache.
+   * @param childParams - raw child item params from a parent item
+   * @param parentChain - ancestor label chain for this group
+   * @param cache - mutable cache to populate
+   */
+  private collectDefaultChildren(
+    childParams: PopoverItemParams[],
+    parentChain: string[],
+    cache: { items: PopoverItemDefault[]; parentChains: Map<PopoverItemDefault, string[]> }
+  ): void {
+    for (const childParam of childParams) {
+      if (childParam.type !== undefined && childParam.type !== PopoverItemType.Default) {
+        continue;
+      }
+
+      const childInstance = new PopoverItemDefault(childParam);
+
+      if (childInstance.name !== undefined && this.isNamePermanentlyHidden(childInstance.name)) {
+        childInstance.destroy();
+        continue;
+      }
+
+      cache.items.push(childInstance);
+      cache.parentChains.set(childInstance, parentChain);
+
+      if (childInstance.hasChildren) {
+        this.collectPromotedChildren([childInstance], parentChain, cache);
+      }
+    }
+  }
+
+  /**
+   * Removes promoted items and group separators from DOM and destroys cached instances.
+   * Idempotent — safe to call when cache is already null.
+   */
+  private cleanupPromotedItems(): void {
+    for (const separator of this.promotedSeparators) {
+      separator.remove();
+    }
+    this.promotedSeparators = [];
+
+    if (this.promotedItemCache !== null) {
+      for (const item of this.promotedItemCache.items) {
+        item.getElement()?.remove();
+        item.destroy();
+      }
+      this.promotedItemCache = null;
+    }
+  }
+
+  /**
+   * Creates a group separator element for promoted search results.
+   * @param label - the parent chain label (e.g., "Convert to" or "Parent › Child")
+   */
+  private createGroupSeparator(label: string): HTMLElement {
+    const el = document.createElement('div');
+
+    el.setAttribute(DATA_ATTR.promotedGroupLabel, '');
+    el.setAttribute('role', 'separator');
+    el.className = 'px-3 pt-2.5 pb-1 text-[11px] font-medium uppercase tracking-wide text-gray-text/50 cursor-default';
+    el.textContent = label;
+
+    return el;
+  }
+
+  /**
+   * Appends DOM elements for a group of promoted items to the items container.
+   * @param groupItems - promoted items with their scores
+   */
+  private appendPromotedGroupElements(groupItems: Array<{ item: PopoverItemDefault; score: number }>): void {
+    for (const { item } of groupItems) {
+      const el = item.getElement();
+
+      if (el !== null) {
+        this.nodes.items?.appendChild(el);
+      }
+    }
+  }
+
   /**
    * Adds search to the popover
    */
@@ -733,7 +901,42 @@ export class PopoverDesktop extends PopoverAbstract {
       placeholder: this.messages.search,
     });
 
-    this.search.on(SearchInputEvent.Search, this.onSearch);
+    this.search.on(SearchInputEvent.Search, (searchData: { query: string; items: SearchableItem[] }) => {
+      const isEmptyQuery = searchData.query === '';
+
+      if (isEmptyQuery) {
+        this.cleanupPromotedItems();
+        this.onSearch({
+          query: searchData.query,
+          topLevelItems: searchData.items as unknown as PopoverItemDefault[],
+          promotedItems: [],
+        });
+
+        return;
+      }
+
+      // Build cache on first non-empty search
+      if (this.promotedItemCache === null) {
+        this.promotedItemCache = this.buildPromotedItemCache();
+      }
+
+      // Score promoted items against the query
+      const { parentChains } = this.promotedItemCache;
+      const promotedScored = this.promotedItemCache.items
+        .map(item => ({
+          item,
+          score: scoreSearchMatch(item, searchData.query),
+          chain: parentChains.get(item) ?? [],
+        }))
+        .filter(({ score }) => score > 0)
+        .sort((a, b) => b.score - a.score);
+
+      this.onSearch({
+        query: searchData.query,
+        topLevelItems: searchData.items as unknown as PopoverItemDefault[],
+        promotedItems: promotedScored,
+      });
+    });
 
     const searchElement = this.search.getElement();
 
@@ -749,45 +952,60 @@ export class PopoverDesktop extends PopoverAbstract {
    */
   public override filterItems(query: string): void {
     if (query === '') {
+      this.cleanupPromotedItems();
       this.onSearch({
         query,
-        items: this.itemsDefault as unknown as SearchableItem[],
+        topLevelItems: this.itemsDefault,
+        promotedItems: [],
       });
 
       return;
     }
 
-    const scoredItems = this.itemsDefault
+    // Build cache on first non-empty search
+    if (this.promotedItemCache === null) {
+      this.promotedItemCache = this.buildPromotedItemCache();
+    }
+
+    // Score top-level items
+    const topLevelScored = this.itemsDefault
       .map(item => ({ item, score: scoreSearchMatch(item, query) }))
       .filter(({ score }) => score > 0)
       .sort((a, b) => b.score - a.score);
 
-    const matchingItems = scoredItems.map(({ item }) => item);
+    // Score promoted items from cache
+    const { parentChains: chains } = this.promotedItemCache;
+    const promotedScored = this.promotedItemCache.items
+      .map(item => ({
+        item,
+        score: scoreSearchMatch(item, query),
+        chain: chains.get(item) ?? [],
+      }))
+      .filter(({ score }) => score > 0)
+      .sort((a, b) => b.score - a.score);
 
     this.onSearch({
       query,
-      items: matchingItems as unknown as SearchableItem[],
+      topLevelItems: topLevelScored.map(({ item }) => item),
+      promotedItems: promotedScored,
     });
   }
 
   /**
-   * Handles input inside search field
-   * @param data - search input event data
-   * @param data.query - search query text
-   * @param data.items - search results
+   * Handles search results from both filterItems and SearchInput.
+   * Renders top-level matches and promoted children with group separators.
    */
-  private onSearch = (data: { query: string, items: SearchableItem[] }): void => {
+  private onSearch = (data: {
+    query: string;
+    topLevelItems: PopoverItemDefault[] | SearchableItem[];
+    promotedItems: Array<{ item: PopoverItemDefault; score: number; chain: string[] }>;
+  }): void => {
     const isEmptyQuery = data.query === '';
-    const isNothingFound = data.items.length === 0;
-
-    // Cast data.items to PopoverItemDefault[] since we know that's what filterItems passes
-    const matchingItems = data.items as unknown as PopoverItemDefault[];
+    const matchingTopLevel = data.topLevelItems as unknown as PopoverItemDefault[];
+    const isNothingFound = matchingTopLevel.length === 0 && data.promotedItems.length === 0;
 
     /**
      * When nothing is found, disable transitions so items hide instantly.
-     * The "Nothing found" message fade-in provides the visual transition;
-     * animating the last items' collapse simultaneously causes a jarring
-     * height bounce in the popover container.
      */
     if (isNothingFound) {
       this.items.forEach(item => {
@@ -800,48 +1018,92 @@ export class PopoverDesktop extends PopoverAbstract {
         const isDefaultItem = item instanceof PopoverItemDefault;
         const isSeparatorOrHtml = item instanceof PopoverItemSeparator || item instanceof PopoverItemHtml;
         const isHidden = isDefaultItem
-          ? !matchingItems.includes(item) || (item.name !== undefined && this.isNamePermanentlyHidden(item.name))
+          ? !matchingTopLevel.includes(item) || (item.name !== undefined && this.isNamePermanentlyHidden(item.name))
           : isSeparatorOrHtml && (isNothingFound || !isEmptyQuery);
 
         item.toggleHidden(isHidden);
       });
 
     if (isNothingFound) {
-      // Force reflow so the instant hide takes effect, then restore transitions
       this.nodes.popoverContainer.offsetHeight;
       this.items.forEach(item => {
         item.getElement()?.style.removeProperty('transition-duration');
       });
     }
 
-    // Reorder DOM elements to reflect ranking
-    if (!isEmptyQuery && matchingItems.length > 0) {
-      this.reorderItemsByRank(matchingItems);
+    // Reorder top-level DOM elements to reflect ranking
+    if (!isEmptyQuery && matchingTopLevel.length > 0) {
+      this.reorderItemsByRank(matchingTopLevel);
     } else if (isEmptyQuery && this.originalItemOrder !== undefined) {
       this.restoreOriginalItemOrder();
     }
 
+    // Detach previous promoted elements from DOM (don't destroy cache)
+    for (const separator of this.promotedSeparators) {
+      separator.remove();
+    }
+    this.promotedSeparators = [];
+
+    if (this.promotedItemCache !== null) {
+      for (const item of this.promotedItemCache.items) {
+        item.getElement()?.remove();
+      }
+    }
+
+    // Render promoted items grouped by parent chain
+    if (data.promotedItems.length > 0) {
+      const groups = new Map<string, Array<{ item: PopoverItemDefault; score: number }>>();
+
+      for (const entry of data.promotedItems) {
+        const label = entry.chain.join(' \u203A ');
+        const existing = groups.get(label);
+
+        if (existing !== undefined) {
+          existing.push({ item: entry.item, score: entry.score });
+        } else {
+          groups.set(label, [{ item: entry.item, score: entry.score }]);
+        }
+      }
+
+      // Sort groups by best score in each group
+      const sortedGroups = [...groups.entries()].sort((a, b) => {
+        const bestA = Math.max(...a[1].map(e => e.score));
+        const bestB = Math.max(...b[1].map(e => e.score));
+
+        return bestB - bestA;
+      });
+
+      for (const [label, groupItems] of sortedGroups) {
+        const separator = this.createGroupSeparator(label);
+
+        this.promotedSeparators.push(separator);
+        this.nodes.items?.appendChild(separator);
+
+        this.appendPromotedGroupElements(groupItems);
+      }
+    }
+
     this.toggleNothingFoundMessage(isNothingFound);
 
-    /** List of elements available for keyboard navigation considering search query applied */
-    const flippableElements = isEmptyQuery ? this.flippableElements : data.items.map(item => (item as PopoverItem).getElement());
+    // Build flippable elements list: top-level matches + promoted items
+    const topLevelFlippable = isEmptyQuery
+      ? this.flippableElements
+      : matchingTopLevel.map(item => item.getElement());
+
+    const promotedFlippable = data.promotedItems.map(({ item }) => item.getElement());
+
+    const flippableElements = [
+      ...topLevelFlippable,
+      ...promotedFlippable,
+    ].filter((el): el is HTMLElement => el !== null);
 
     if (!this.flipper?.isActivated) {
       return;
     }
 
-    /** Update flipper items with only visible */
     this.flipper.deactivate();
-    this.flipper.activate(flippableElements as HTMLElement[]);
+    this.flipper.activate(flippableElements);
 
-    /**
-     * Focus first item after filtering.
-     * Always skip the first Tab press so it just "enters" the menu rather than
-     * advancing to second item. This applies regardless of whether the query is
-     * empty (initial "/" open) or non-empty (user is typing to filter), because
-     * the user's keyboard focus is still in the search input - pressing Tab
-     * should enter the list at item 0, not advance from 0 to 1.
-     */
     if (flippableElements.length > 0) {
       this.flipper.focusItem(0, { skipNextTab: true });
     }

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

@@ -240,6 +240,14 @@ export class PopoverInline extends PopoverDesktop {
     return;
   }
 
+  /**
+   * Disable mouse-leave event handling.
+   * Inline toolbar uses click-to-toggle for nested popovers, not hover.
+   */
+  protected override handleMouseLeave(): void {
+    return;
+  }
+
   /**
    * Sets CSS variable with position of item near which nested popover should be displayed.
    * Is used to position nested popover right below clicked item

package/src/styles/main.css

@@ -37,9 +37,11 @@
     `all: initial !important` — main editor wrapper (outermost boundary).
     Resets every property to its CSS initial value with !important priority,
     blocking even `!important` host-page styles from cascading in.
-    Blok's own Tailwind utility classes (applied to the same elements or
-    descendants) override this because they have equal or higher specificity
-    and appear later in the cascade.
+    However, `!important` declarations always beat normal declarations
+    regardless of specificity or source order, so Tailwind utility classes
+    applied to the wrapper element itself (e.g. `relative`, `z-1`) are
+    overridden. Properties that the wrapper needs must be explicitly
+    re-applied with `!important` below (same pattern as font-family/color).
 
   [data-blok-popover]:not([data-blok-popover-inline])
     Inherited-properties-only reset — toolbox/settings popovers, appended
@@ -72,6 +74,27 @@
 */
 [data-blok-interface=blok] {
   all: initial !important;
+
+  /*
+    Re-apply layout properties that `all: initial` resets.
+    The wrapper must be a positioned containing block so that
+    absolutely-positioned children (inline toolbar, main toolbar)
+    resolve against it rather than the document root. Without this,
+    the inline toolbar renders off-screen when the page is scrolled.
+  */
+  position: relative !important;
+  box-sizing: border-box !important;
+  display: block !important;
+  z-index: 1 !important;
+}
+
+/*
+  RTL direction is set conditionally via JS (ui.ts) using the
+  data-blok-rtl attribute. `all: initial` resets direction to `ltr`,
+  so we must re-apply it with !important when the attribute is present.
+*/
+[data-blok-interface=blok][data-blok-rtl=true] {
+  direction: rtl !important;
 }
 
 /* Font family — user-configurable via config.style.fontFamily */
@@ -327,8 +350,9 @@
   resize: vertical;
 }
 
-/* Remove inner padding in Chrome and Safari on macOS. */
-:where([data-blok-interface], [data-blok-popover]) ::-webkit-search-decoration {
+/* Remove inner padding and native cancel button in Chrome and Safari on macOS. */
+:where([data-blok-interface], [data-blok-popover]) ::-webkit-search-decoration,
+:where([data-blok-interface], [data-blok-popover]) ::-webkit-search-cancel-button {
   -webkit-appearance: none;
 }
 
@@ -394,10 +418,13 @@
   outline: none;
 }
 
-/* Never show a focus outline on contenteditable blocks — the text cursor
-   is sufficient affordance regardless of how focus was triggered. */
-[data-blok-interface] [contenteditable]:focus-visible,
-[data-blok-popover] [contenteditable]:focus-visible {
+/* Never show a focus outline on text-entry elements — the text cursor
+   is sufficient affordance regardless of how focus was triggered.
+   Browsers always match :focus-visible on these elements even on mouse
+   click (per CSS Selectors L4), so the :focus-visible restore rule below
+   would otherwise override element-level outline-hidden utilities. */
+[data-blok-interface] :is([contenteditable], input, textarea):focus-visible,
+[data-blok-popover] :is([contenteditable], input, textarea):focus-visible {
   outline: none;
 }
 
@@ -952,8 +979,9 @@
  * When the user types "/" to open the toolbox, the contenteditable
  * transforms to look like a search input with a placeholder.
  */
-[data-blok-slash-search] {
-  @apply bg-search-input-bg rounded-lg transition-colors duration-150 max-w-[240px];
+[data-blok-slash-search],
+[data-blok-slash-search]:focus-visible {
+  @apply bg-search-input-bg rounded-[4px] transition-colors duration-150 max-w-[240px];
 }
 
 [data-blok-slash-search]::after {

package/src/tools/paragraph/index.ts

@@ -346,11 +346,9 @@ export class Paragraph implements BlockTool {
 
     this._data = data;
 
-    queueMicrotask(() => {
-      if (this._element) {
-        this._element.innerHTML = this._data.text || '';
-      }
-    });
+    if (this._element) {
+      this._element.innerHTML = this._data.text || '';
+    }
   }
 
   /**

package/src/tools/table/index.ts

@@ -1395,6 +1395,20 @@ export class Table implements BlockTool {
       return;
     }
 
+    /**
+     * Single-cell (1×1) payloads should insert content inline at the caret
+     * position rather than replacing the entire target cell. This matches user
+     * expectations: copying one cell and pasting into another cell (or the same
+     * cell) appends/inserts the text instead of overwriting.
+     */
+    if (payload.rows === 1 && payload.cols === 1) {
+      e.preventDefault();
+      e.stopPropagation();
+      this.insertSingleCellPayloadInline(payload.cells[0][0]);
+
+      return;
+    }
+
     e.preventDefault();
     e.stopPropagation();
 
@@ -1406,6 +1420,62 @@ export class Table implements BlockTool {
     this.pastePayloadIntoCells(gridEl, payload, targetRowIndex, targetColIndex);
   }
 
+  /**
+   * Insert the content of a single clipboard cell at the current caret position.
+   * Extracts text from each block and joins with line breaks.
+   */
+  private insertSingleCellPayloadInline(cell: { blocks: ClipboardBlockData[] }): void {
+    const html = cell.blocks
+      .map((block) => {
+        if (typeof block.data.text === 'string') {
+          return block.data.text;
+        }
+
+        return '';
+      })
+      .filter(Boolean)
+      .join('<br>');
+
+    if (!html) {
+      return;
+    }
+
+    const selection = window.getSelection();
+
+    if (!selection || selection.rangeCount === 0) {
+      return;
+    }
+
+    const range = selection.getRangeAt(0);
+
+    range.deleteContents();
+
+    const fragment = document.createDocumentFragment();
+    const wrapper = document.createElement('div');
+
+    wrapper.innerHTML = html;
+
+    Array.from(wrapper.childNodes).forEach((child) => fragment.appendChild(child));
+
+    if (fragment.childNodes.length === 0) {
+      fragment.appendChild(new Text());
+    }
+
+    const lastChild = fragment.lastChild as ChildNode;
+
+    range.insertNode(fragment);
+
+    const newRange = document.createRange();
+    const nodeToSetCaret = lastChild.nodeType === Node.TEXT_NODE ? lastChild : lastChild.firstChild;
+
+    if (nodeToSetCaret !== null && nodeToSetCaret.textContent !== null) {
+      newRange.setStart(nodeToSetCaret, nodeToSetCaret.textContent.length);
+    }
+
+    selection.removeAllRanges();
+    selection.addRange(newRange);
+  }
+
   private pastePayloadIntoCells(
     gridEl: HTMLElement,
     payload: TableCellsClipboard,

package/src/tools/table/table-cell-blocks.ts

@@ -144,8 +144,8 @@ export class TableCellBlocks {
       return;
     }
 
-    // ArrowDown at last row -> exit table
-    if (event.key === 'ArrowDown' && position.row === this.getRowCount() - 1) {
+    // ArrowDown at last row -> exit table (skip if already handled by block-level navigation)
+    if (event.key === 'ArrowDown' && !event.defaultPrevented && position.row === this.getRowCount() - 1) {
       event.preventDefault();
       this.exitTableForward();
     }
@@ -492,7 +492,19 @@ export class TableCellBlocks {
       return;
     }
 
-    container.appendChild(block.holder);
+    // Insert at the correct DOM position based on the flat array order,
+    // so that pressing Enter on a non-last paragraph inserts the new block
+    // right after the current one instead of always at the end of the cell.
+    const blocksCount = this.api.blocks.getBlocksCount();
+    const nextSiblingHolder = Array.from(
+      { length: blocksCount - index - 1 },
+      (_, offset) => this.api.blocks.getBlockByIndex(index + 1 + offset)
+    ).find(
+      candidate => candidate?.holder.parentElement === container
+    )?.holder ?? null;
+
+    // insertBefore(el, null) is equivalent to appendChild
+    container.insertBefore(block.holder, nextSiblingHolder);
     this.api.blocks.setBlockParent(blockId, this.tableBlockId);
     this.stripPlaceholders(container);
   }