@jackuait/blok 0.7.0-beta.3 → 0.7.0

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

@@ -6,9 +6,10 @@ import type { PopoverItem, PopoverItemRenderParamsMap } from './components/popov
 import { PopoverItemSeparator, css as popoverItemCls , PopoverItemDefault } from './components/popover-item';
 import { PopoverItemHtml } from './components/popover-item/popover-item-html/popover-item-html';
 import type { SearchableItem } from './components/search-input';
-import { SearchInput, SearchInputEvent, matchesSearchQuery } from './components/search-input';
+import { SearchInput, SearchInputEvent, scoreSearchMatch } from './components/search-input';
 import { PopoverAbstract } from './popover-abstract';
-import { CSSVariables } from './popover.const';
+import { CSSVariables, css as popoverCss } from './popover.const';
+import { twMerge } from '../tw';
 
 import type { PopoverParams } from '@/types/utils/popover/popover';
 import { PopoverEvent } from '@/types/utils/popover/popover-event';
@@ -71,6 +72,12 @@ export class PopoverDesktop extends PopoverAbstract {
    */
   private _size: { height: number; width: number } | undefined;
 
+  /**
+   * Original order of item elements in the popover container.
+   * Cached on first search so we can restore order when query is cleared.
+   */
+  private originalItemOrder: Element[] | undefined;
+
   /**
    * Construct the instance
    * @param params - popover params
@@ -102,6 +109,7 @@ export class PopoverDesktop extends PopoverAbstract {
 
     if (this.nodes.popoverContainer !== null) {
       this.listeners.on(this.nodes.popoverContainer, 'mouseover', (event: Event) => this.handleHover(event));
+      this.listeners.on(this.nodes.popoverContainer, 'mouseleave', (event: Event) => this.handleMouseLeave(event));
     }
 
     if (params.searchable) {
@@ -225,15 +233,16 @@ export class PopoverDesktop extends PopoverAbstract {
     this.flipper?.activate(this.flippableElements);
 
     // Focus the first item: search field if present, otherwise first menu item
-    requestAnimationFrame(() => {
+    queueMicrotask(() => {
       this.focusInitialElement();
     });
   }
 
   /**
    * Focuses the initial element when popover is shown.
-   * Focuses search field if present, otherwise first menu item.
-   * Skips the first Tab press so it just "enters" the menu rather than advancing.
+   * When a search field is present, it receives focus so the user can type immediately.
+   * When autoFocusFirstItem is false, no item is pre-focused — focus only appears
+   * after the user begins keyboard navigation.
    */
   private focusInitialElement(): void {
     if (this.search) {
@@ -242,6 +251,10 @@ export class PopoverDesktop extends PopoverAbstract {
       return;
     }
 
+    if (this.params.autoFocusFirstItem === false) {
+      return;
+    }
+
     this.flipper?.focusItem(0, { skipNextTab: true });
   }
 
@@ -363,7 +376,20 @@ export class PopoverDesktop extends PopoverAbstract {
       return;
     }
 
-    this.destroyNestedPopoverIfExists();
+    /**
+     * If the pointer moved into the nested popover (e.g. user is about to click
+     * an item in the sub-menu), do not destroy it.
+     */
+    if (
+      this.nestedPopover !== undefined &&
+      this.nestedPopover !== null &&
+      event.target instanceof Node &&
+      this.nestedPopover.hasNode(event.target)
+    ) {
+      return;
+    }
+
+    this.destroyNestedPopoverIfExists(false);
 
     this.previouslyHoveredItem = item;
 
@@ -374,6 +400,28 @@ export class PopoverDesktop extends PopoverAbstract {
     this.showNestedPopoverForItem(item);
   }
 
+  /**
+   * Handles mouse leaving the popover container.
+   * Destroys nested popover unless the mouse moved into it.
+   * @param event - mouseleave event
+   */
+  private handleMouseLeave(event: Event): void {
+    const mouseEvent = event as MouseEvent;
+    const relatedTarget = mouseEvent.relatedTarget;
+
+    if (
+      relatedTarget instanceof Node &&
+      this.nestedPopover !== undefined &&
+      this.nestedPopover !== null &&
+      this.nestedPopover.hasNode(relatedTarget)
+    ) {
+      return;
+    }
+
+    this.destroyNestedPopoverIfExists(false);
+    this.previouslyHoveredItem = null;
+  }
+
   /**
    * Sets CSS variable with position of item near which nested popover should be displayed.
    * Is used for correct positioning of the nested popover
@@ -393,8 +441,11 @@ export class PopoverDesktop extends PopoverAbstract {
 
   /**
    * Destroys existing nested popover
+   * @param restoreFocus - whether to restore keyboard focus to the trigger item after closing.
+   * Should be true for keyboard-driven closes (e.g. ArrowLeft/Escape), false for mouse-driven closes
+   * to avoid leaving a stale focus highlight on the trigger item.
    */
-  protected destroyNestedPopoverIfExists(): void {
+  protected destroyNestedPopoverIfExists(restoreFocus = true): void {
     if (this.nestedPopover === undefined || this.nestedPopover === null) {
       return;
     }
@@ -408,8 +459,11 @@ export class PopoverDesktop extends PopoverAbstract {
     elementToRemove.remove();
     this.nestedPopover = null;
     this.flipper?.activate(this.flippableElements);
-    // Focus the trigger item synchronously to ensure keyboard events work immediately
-    this.focusAfterNestedPopoverClose(triggerItemElement);
+
+    if (restoreFocus) {
+      // Focus the trigger item synchronously to ensure keyboard events work immediately
+      this.focusAfterNestedPopoverClose(triggerItemElement);
+    }
 
     this.nestedPopoverTriggerItem?.onChildrenClose();
     // Reset trigger item so clicking the same item again will open the nested popover
@@ -457,6 +511,7 @@ export class PopoverDesktop extends PopoverAbstract {
       onNavigateBack: this.destroyNestedPopoverIfExists.bind(this),
       width: item.childrenWidth,
       handleContentEditableNavigation: handleContentEditable,
+      autoFocusFirstItem: this.params.autoFocusFirstItem,
     });
 
     item.onChildrenOpen();
@@ -608,10 +663,13 @@ export class PopoverDesktop extends PopoverAbstract {
 
     popoverClone.setAttribute(DATA_ATTR.popoverOpened, 'true');
     popoverClone.querySelector(`[${DATA_ATTR.nested}]`)?.remove();
-    document.body.appendChild(popoverClone);
 
     const container = popoverClone.querySelector(`[${DATA_ATTR.popoverContainer}]`) as HTMLElement;
 
+    container.className = twMerge(container.className, popoverCss.popoverContainerOpened);
+
+    document.body.appendChild(popoverClone);
+
     size.height = container.offsetHeight;
     size.width = container.offsetWidth;
     popoverClone.remove();
@@ -690,7 +748,21 @@ export class PopoverDesktop extends PopoverAbstract {
    * @param query - search query text
    */
   public override filterItems(query: string): void {
-    const matchingItems = this.itemsDefault.filter(item => matchesSearchQuery(item, query));
+    if (query === '') {
+      this.onSearch({
+        query,
+        items: this.itemsDefault as unknown as SearchableItem[],
+      });
+
+      return;
+    }
+
+    const scoredItems = 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);
 
     this.onSearch({
       query,
@@ -742,6 +814,13 @@ export class PopoverDesktop extends PopoverAbstract {
       });
     }
 
+    // Reorder DOM elements to reflect ranking
+    if (!isEmptyQuery && matchingItems.length > 0) {
+      this.reorderItemsByRank(matchingItems);
+    } else if (isEmptyQuery && this.originalItemOrder !== undefined) {
+      this.restoreOriginalItemOrder();
+    }
+
     this.toggleNothingFoundMessage(isNothingFound);
 
     /** List of elements available for keyboard navigation considering search query applied */
@@ -767,4 +846,47 @@ export class PopoverDesktop extends PopoverAbstract {
       this.flipper.focusItem(0, { skipNextTab: true });
     }
   };
+
+  /**
+   * Reorders DOM children of the items container to match the ranked order.
+   * Caches the original order on first call so it can be restored later.
+   * @param rankedItems - items sorted by search relevance (best first)
+   */
+  private reorderItemsByRank(rankedItems: PopoverItemDefault[]): void {
+    if (this.originalItemOrder === undefined && this.nodes.items !== null) {
+      this.originalItemOrder = Array.from(this.nodes.items.children);
+    }
+
+    const itemsContainer = this.nodes.items;
+
+    if (itemsContainer === null) {
+      return;
+    }
+
+    for (const item of rankedItems) {
+      const el = item.getElement();
+
+      if (el !== null) {
+        itemsContainer.appendChild(el);
+      }
+    }
+  }
+
+  /**
+   * Restores the original DOM order of items container children.
+   * Called when the search query is cleared.
+   */
+  private restoreOriginalItemOrder(): void {
+    const itemsContainer = this.nodes.items;
+
+    if (itemsContainer === null || this.originalItemOrder === undefined) {
+      return;
+    }
+
+    for (const el of this.originalItemOrder) {
+      itemsContainer.appendChild(el);
+    }
+
+    this.originalItemOrder = undefined;
+  }
 }

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

@@ -226,7 +226,7 @@ export class PopoverInline extends PopoverDesktop {
       this.nodes.popover.style.height = heightPx;
     }
 
-    requestAnimationFrame(() => {
+    queueMicrotask(() => {
       this.flipper?.deactivate();
       this.flipper?.activate(this.flippableElements);
     });

package/src/components/utils/popover/popover.const.ts

@@ -5,19 +5,19 @@
  */
 export const css = {
   // Popover container - base styles
-  popoverContainer: 'absolute flex flex-col overflow-hidden box-border opacity-0 pointer-events-none p-0 border-none z-4 max-h-0 min-w-(--width) w-(--width) rounded-xl shadow-[0_4px_20px_-4px_var(--color-popover-shadow),0_0_0_0.5px_rgba(0,0,0,0.06)] left-(--popover-left) top-(--popover-top) bg-popover-bg',
+  popoverContainer: 'absolute flex flex-col overflow-hidden box-border opacity-0 pointer-events-none p-0 border-none z-4 max-h-0 min-w-(--width) w-(--width) rounded-xl text-sm left-(--popover-left) top-(--popover-top) bg-popover-bg',
 
   // Popover container - mobile styles (applied conditionally)
   // Reset left/top from base class since inset shorthand may not properly override them in twMerge
   popoverContainerMobile: 'fixed max-w-none rounded-[10px] min-w-[calc(100%-var(--offset)*2)] left-auto top-auto inset-[auto_var(--offset)_calc(var(--offset)+env(safe-area-inset-bottom))_var(--offset)]',
 
   // Popover container - opened state
-  popoverContainerOpened: 'opacity-100 pointer-events-auto p-1.5 max-h-(--max-height) border border-popover-border animate-[panelShowing_100ms_ease]',
+  popoverContainerOpened: 'opacity-100 pointer-events-auto p-1.5 max-h-(--max-height) border-none animate-panel-showing',
 
   // Popover overlay
   popoverOverlay: 'hidden bg-dark',
 
-  items: 'overflow-y-auto overscroll-contain [scrollbar-gutter:stable] pr-1',
+  items: 'overflow-y-auto overscroll-contain',
 };
 
 /**

package/src/components/utils/shortcut.ts

@@ -57,6 +57,8 @@ const KEY_CODES: Record<string, string> = {
   'INSERT': 'Insert',
   'DELETE': 'Delete',
   '.': 'Period',
+  '[': 'BracketLeft',
+  ']': 'BracketRight',
 };
 
 type ModifierKey = keyof typeof SUPPORTED_COMMANDS;

package/src/components/utils/tooltip.ts

@@ -360,7 +360,17 @@ class Tooltip {
     const shownClass = Array.isArray(this.CSS.tooltipShown) ? this.CSS.tooltipShown[0] : this.CSS.tooltipShown;
     const isShown = this.nodes.wrapper.classList.contains(shownClass);
 
-    this.nodes.wrapper.style.setProperty(VISIBILITY_PROPERTY, isShown ? VISIBILITY_VISIBLE : VISIBILITY_HIDDEN);
+    /**
+     * Use `!important` priority when hiding so the inline style wins over the
+     * author stylesheet's `all: initial !important` rule (which sets visibility
+     * to `visible`). Inline `!important` > author `!important` in the cascade.
+     * When showing, normal priority is sufficient (no competing rule sets visible).
+     */
+    this.nodes.wrapper.style.setProperty(
+      VISIBILITY_PROPERTY,
+      isShown ? VISIBILITY_VISIBLE : VISIBILITY_HIDDEN,
+      isShown ? '' : 'important'
+    );
     this.nodes.wrapper.setAttribute(ARIA_HIDDEN_ATTRIBUTE, isShown ? ARIA_HIDDEN_FALSE : ARIA_HIDDEN_TRUE);
     this.nodes.wrapper.setAttribute('data-blok-shown', isShown ? 'true' : 'false');
   }

package/src/react/BlokContent.tsx

@@ -0,0 +1,46 @@
+import { useEffect, useRef, forwardRef } from 'react';
+import { getHolder } from './holder-map';
+import type { BlokContentProps } from './types';
+
+/**
+ * Component that provides the DOM mount point for a Blok editor.
+ * Renders a <div> and adopts the editor's detached holder DOM into it.
+ * When editor is null, renders an empty div (for layout stability).
+ * Passes through all standard HTML div attributes (className, style, etc.).
+ */
+export const BlokContent = forwardRef<HTMLDivElement, BlokContentProps>(
+  function BlokContent({ editor, ...divProps }, ref) {
+    const containerRef = useRef<HTMLDivElement | null>(null);
+
+    const setRefs = (node: HTMLDivElement | null): void => {
+      containerRef.current = node;
+      if (typeof ref === 'function') {
+        ref(node);
+      } else if (ref !== null && ref !== undefined) {
+        const mutableRef = ref;
+
+        mutableRef.current = node;
+      }
+    };
+
+    useEffect(() => {
+      if (editor === null || containerRef.current === null) {
+        return;
+      }
+
+      const holder = getHolder(editor);
+
+      if (holder === undefined) {
+        return;
+      }
+
+      containerRef.current.appendChild(holder);
+
+      return (): void => {
+        holder.remove();
+      };
+    }, [editor]);
+
+    return <div ref={setRefs} {...divProps} />;
+  }
+);

package/src/react/holder-map.ts

@@ -0,0 +1,17 @@
+/**
+ * Module-level WeakMap associating editor instances with their detached holder divs.
+ * WeakMap ensures no memory leaks — when the editor is garbage collected, the holder reference is released.
+ */
+const holders = new WeakMap<WeakKey, HTMLDivElement>();
+
+export function setHolder(editor: WeakKey, holder: HTMLDivElement): void {
+  holders.set(editor, holder);
+}
+
+export function getHolder(editor: WeakKey): HTMLDivElement | undefined {
+  return holders.get(editor);
+}
+
+export function removeHolder(editor: WeakKey): void {
+  holders.delete(editor);
+}

package/src/react/index.ts

@@ -0,0 +1,3 @@
+export { useBlok } from './useBlok';
+export { BlokContent } from './BlokContent';
+export type { UseBlokConfig, BlokContentProps } from './types';

package/src/react/types.ts

@@ -0,0 +1,16 @@
+import type { BlokConfig, Blok } from '@/types';
+
+/**
+ * Configuration for useBlok hook.
+ * Same as BlokConfig but without `holder` — the holder is managed by BlokContent.
+ */
+export interface UseBlokConfig extends Omit<BlokConfig, 'holder'> {}
+
+/**
+ * Props for the BlokContent component.
+ * Extends standard div HTML attributes so className, style, id, etc. pass through.
+ */
+export interface BlokContentProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** The Blok editor instance returned by useBlok. Pass null if editor is not ready yet. */
+  editor: Blok | null;
+}

package/src/react/useBlok.ts

@@ -0,0 +1,173 @@
+import { useState, useEffect, useRef, useMemo, type DependencyList } from 'react';
+import { Blok as BlokRuntime } from '../blok';
+import { setHolder, removeHolder } from './holder-map';
+import type { Blok } from '@/types';
+import type { UseBlokConfig } from './types';
+
+interface EditorInstanceState {
+  editor: Blok | null;
+  holder: HTMLDivElement | null;
+  destroyTimeout: ReturnType<typeof setTimeout> | null;
+  isDestroyed: boolean;
+  /** Opaque token identifying which deps cycle created this editor */
+  depsToken: Record<string, unknown> | null;
+}
+
+/**
+ * React hook that manages a Blok editor instance lifecycle.
+ *
+ * Creates a detached holder div, instantiates Blok, and returns the instance
+ * once `isReady` resolves. Handles StrictMode double-mount by deferring
+ * destroy via `setTimeout(0)` and cancelling on remount.
+ *
+ * @param config - Blok configuration without `holder` (managed internally)
+ * @param deps - Optional dependency array; when values change, the editor is recreated
+ * @returns The Blok instance once ready, or null during initialization / SSR
+ */
+export function useBlok(config: UseBlokConfig, deps?: DependencyList): Blok | null {
+  const [editor, setEditor] = useState<Blok | null>(null);
+  const configRef = useRef(config);
+  configRef.current = config;
+
+  const stateRef = useRef<EditorInstanceState>({
+    editor: null,
+    holder: null,
+    destroyTimeout: null,
+    isDestroyed: false,
+    depsToken: null,
+  });
+
+  // A new token is created only when deps change (useMemo compares deps).
+  // StrictMode re-runs see the SAME token. Deps changes produce a NEW token.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const depsToken = useMemo(() => ({}), deps ?? []);
+
+  // Main lifecycle effect
+  useEffect(() => {
+    if (typeof window === 'undefined') {
+      return;
+    }
+
+    const state = stateRef.current;
+
+    // Cancel pending deferred destroy (StrictMode remount)
+    if (state.destroyTimeout !== null) {
+      clearTimeout(state.destroyTimeout);
+      state.destroyTimeout = null;
+    }
+
+    // Reuse editor on StrictMode remount (same deps cycle)
+    if (state.editor !== null && !state.isDestroyed && state.depsToken === depsToken) {
+      setEditor(state.editor);
+
+      return (): void => {
+        deferDestroy(state, setEditor);
+      };
+    }
+
+    // Destroy leftover editor from a previous deps cycle
+    if (state.editor !== null && !state.isDestroyed) {
+      removeHolder(state.editor);
+      try {
+        state.editor.destroy();
+      } catch {
+        // destroy may throw — still clean up state
+      }
+      state.editor = null;
+      state.holder = null;
+      state.isDestroyed = true;
+      setEditor(null);
+    }
+
+    // Create detached holder
+    const holder = document.createElement('div');
+    state.holder = holder;
+    state.isDestroyed = false;
+    state.depsToken = depsToken;
+
+    // Wrap callbacks via ref so they never go stale
+    const currentConfig = configRef.current;
+    const blokConfig = {
+      ...currentConfig,
+      holder,
+      onReady: (): void => {
+        configRef.current.onReady?.();
+      },
+      onChange: (...args: Parameters<NonNullable<UseBlokConfig['onChange']>>): void => {
+        configRef.current.onChange?.(...args);
+      },
+    };
+
+    const blok = new BlokRuntime(blokConfig) as unknown as Blok;
+    state.editor = blok;
+    setHolder(blok, holder);
+
+    void blok.isReady
+      .then(() => {
+        if (state.editor === blok && !state.isDestroyed) {
+          setEditor(blok);
+        }
+      })
+      .catch(() => {
+        if (state.editor === blok && !state.isDestroyed) {
+          removeHolder(blok);
+          try {
+            blok.destroy();
+          } catch {
+            // destroy may also throw — still clean up state
+          }
+          state.editor = null;
+          state.holder = null;
+          state.isDestroyed = true;
+          setEditor(null);
+        }
+      });
+
+    return (): void => {
+      deferDestroy(state, setEditor);
+    };
+  }, [depsToken]);
+
+  // Reactive: readOnly
+  const { readOnly } = config;
+  useEffect(() => {
+    if (editor === null) {
+      return;
+    }
+    void editor.readOnly.set(readOnly ?? false);
+  }, [editor, readOnly]);
+
+  // Reactive: autofocus
+  const { autofocus } = config;
+  useEffect(() => {
+    if (editor === null || !autofocus) {
+      return;
+    }
+    editor.focus();
+  }, [editor, autofocus]);
+
+  return editor;
+}
+
+function deferDestroy(
+  state: EditorInstanceState,
+  setEditorState: React.Dispatch<React.SetStateAction<Blok | null>>
+): void {
+  /* eslint-disable no-param-reassign -- intentional mutation of shared state ref */
+  state.destroyTimeout = setTimeout(() => {
+    if (state.editor !== null) {
+      removeHolder(state.editor);
+      try {
+        state.editor.destroy();
+      } catch {
+        // destroy may throw — still clean up state
+      }
+      state.editor = null;
+      state.holder = null;
+      state.isDestroyed = true;
+      state.destroyTimeout = null;
+      setEditorState(null);
+    }
+  }, 0);
+  /* eslint-enable no-param-reassign */
+}

package/src/stories/Placeholder.stories.ts

@@ -148,65 +148,6 @@ export const PlaceholderHiddenWithContent: Story = {
   },
 };
 
-/**
- * Typing hides placeholder, clearing restores it.
- */
-export const TypeAndClearPlaceholder: Story = {
-  args: {
-    placeholder: DEFAULT_PLACEHOLDER,
-    data: undefined,
-  },
-  parameters: {
-    chromatic: { delay: 500 },
-  },
-  play: async ({ canvasElement, step }) => {
-    await step('Wait for editor to initialize', async () => {
-      await waitFor(
-        () => {
-          const block = canvasElement.querySelector(BLOCK_TESTID);
-
-          expect(block).toBeInTheDocument();
-        },
-        TIMEOUT_INIT
-      );
-    });
-
-    await step('Focus and type to hide placeholder', async () => {
-      const block = canvasElement.querySelector(BLOCK_TESTID);
-      const contentEditable = block?.querySelector(CONTENTEDITABLE_SELECTOR);
-
-      if (contentEditable) {
-        await userEvent.click(contentEditable);
-        await userEvent.keyboard('Hello world');
-      }
-
-      await waitFor(
-        () => {
-          expect(contentEditable?.textContent).toContain('Hello world');
-        },
-        TIMEOUT_ACTION
-      );
-    });
-
-    await step('Clear content to restore placeholder', async () => {
-      const block = canvasElement.querySelector(BLOCK_TESTID);
-      const contentEditable = block?.querySelector(CONTENTEDITABLE_SELECTOR);
-
-      if (contentEditable) {
-        await userEvent.tripleClick(contentEditable);
-        await userEvent.keyboard('{Backspace}');
-      }
-
-      await waitFor(
-        () => {
-          expect(contentEditable?.textContent?.trim()).toBe('');
-        },
-        TIMEOUT_ACTION
-      );
-    });
-  },
-};
-
 /**
  * Multiple blocks - only first empty block shows placeholder.
  */