@jackuait/blok 0.4.1-beta.11 → 0.4.1-beta.13

package/src/components/modules/ui.ts

@@ -468,7 +468,7 @@ export class UI extends Module<UINodes> {
     };
 
     const handleBlockHovered = (event: Event): void => {
-      if (!(event instanceof MouseEvent)) {
+      if (typeof MouseEvent === 'undefined' || !(event instanceof MouseEvent)) {
         return;
       }
 
@@ -789,6 +789,16 @@ export class UI extends Module<UINodes> {
       return;
     }
 
+    /**
+     * Close BlockSettings first if it's open, regardless of selection state.
+     * This prevents navigation mode from being enabled when the user closes block tunes with Escape.
+     */
+    if (this.Blok.BlockSettings.opened) {
+      this.Blok.BlockSettings.close();
+
+      return;
+    }
+
     /**
      * Clear blocks selection by ESC (but not when entering navigation mode)
      */
@@ -806,12 +816,6 @@ export class UI extends Module<UINodes> {
       return;
     }
 
-    if (this.Blok.BlockSettings.opened) {
-      this.Blok.BlockSettings.close();
-
-      return;
-    }
-
     /**
      * If a nested popover is open (like convert-to dropdown),
      * close only the nested popover, not the entire inline toolbar.

package/src/components/ui/toolbox.ts

@@ -145,6 +145,12 @@ export class Toolbox extends EventsDispatcher<ToolboxEventMap> {
    */
   private currentBlockForSearch: HTMLElement | null = null;
 
+  /**
+   * Cached contentEditable element for the current block being searched.
+   * Avoids repeated DOM queries on each input event.
+   */
+  private currentContentEditable: Element | null = null;
+
   /**
    * Toolbox constructor
    * @param options - available parameters
@@ -383,6 +389,9 @@ export class Toolbox extends EventsDispatcher<ToolboxEventMap> {
       const userSearchTerms = tool.searchTerms ?? [];
       const mergedSearchTerms = [...new Set([...librarySearchTerms, ...userSearchTerms])];
 
+      // Use entry-level shortcut if available, otherwise fall back to tool-level shortcut (for first entry only)
+      const shortcut = toolboxItem.shortcut ?? (displaySecondaryLabel ? tool.shortcut : undefined);
+
       return {
         icon: toolboxItem.icon,
         title: translateToolTitle(this.i18n, toolboxItem, capitalize(tool.name)),
@@ -390,7 +399,7 @@ export class Toolbox extends EventsDispatcher<ToolboxEventMap> {
         onActivate: (): void => {
           void this.toolButtonActivated(tool.name, toolboxItem.data);
         },
-        secondaryLabel: (tool.shortcut && displaySecondaryLabel) ? beautifyShortcut(tool.shortcut) : '',
+        secondaryLabel: shortcut ? beautifyShortcut(shortcut) : '',
         englishTitle,
         searchTerms: mergedSearchTerms,
       };
@@ -545,6 +554,7 @@ export class Toolbox extends EventsDispatcher<ToolboxEventMap> {
     }
 
     this.currentBlockForSearch = currentBlock.holder;
+    this.currentContentEditable = this.currentBlockForSearch.querySelector('[contenteditable="true"]');
     this.listeners.on(this.currentBlockForSearch, 'input', this.handleBlockInput);
   }
 
@@ -555,6 +565,7 @@ export class Toolbox extends EventsDispatcher<ToolboxEventMap> {
     if (this.currentBlockForSearch !== null) {
       this.listeners.off(this.currentBlockForSearch, 'input', this.handleBlockInput);
       this.currentBlockForSearch = null;
+      this.currentContentEditable = null;
     }
 
     this.popover?.filterItems('');
@@ -565,13 +576,11 @@ export class Toolbox extends EventsDispatcher<ToolboxEventMap> {
    * Extracts text after "/" and applies it as a filter query.
    */
   private handleBlockInput = (): void => {
-    if (this.currentBlockForSearch === null) {
+    if (this.currentContentEditable === null) {
       return;
     }
 
-    // Get text from the contenteditable element inside the block
-    const contentEditable = this.currentBlockForSearch.querySelector('[contenteditable="true"]');
-    const text = contentEditable?.textContent || '';
+    const text = this.currentContentEditable.textContent || '';
     const slashIndex = text.lastIndexOf('/');
 
     if (slashIndex === -1) {

package/src/components/utils/data-model-transform.ts

@@ -109,37 +109,49 @@ const expandListItems = (
 
     childIds.push(itemId);
 
-    // Recursively expand nested items first to get their IDs
-    const nestedChildIds = item.items && item.items.length > 0
-      ? expandListItems(item.items, itemId, depth + 1, style, undefined, tunes, blocks)
-      : [];
-
     // Determine if we should include start (only for first root item of ordered lists)
     const includeStart = style === 'ordered' && depth === 0 && index === 0 && start !== undefined && start !== 1;
 
-    // Create the list_item block
+    // Check if there are nested items (we'll get their IDs after pushing the parent)
+    const hasNestedItems = item.items && item.items.length > 0;
+
+    // Create the list block (flat model - each item is a separate 'list' block)
+    // We'll update with content IDs after processing children
     const itemBlock: OutputBlockData = {
       id: itemId,
-      type: 'list_item',
+      type: 'list',
       data: {
         text: item.content,
         checked: item.checked,
         style,
+        ...(depth > 0 ? { depth } : {}),
         ...(includeStart ? { start } : {}),
       },
       ...(tunes !== undefined ? { tunes } : {}),
       ...(parentId !== undefined ? { parent: parentId } : {}),
-      ...(nestedChildIds.length > 0 ? { content: nestedChildIds } : {}),
     };
 
+    // Push parent block first to maintain correct order (parent before children)
     blocks.push(itemBlock);
+
+    // Now recursively expand nested items (they will be added after the parent)
+    if (!hasNestedItems) {
+      return;
+    }
+
+    const nestedChildIds = expandListItems(item.items!, itemId, depth + 1, style, undefined, tunes, blocks);
+
+    // Update the parent block with content IDs (only if children exist)
+    if (nestedChildIds.length > 0) {
+      itemBlock.content = nestedChildIds;
+    }
   });
 
   return childIds;
 };
 
 /**
- * Expand a List block with nested items into flat list_item blocks
+ * Expand a List block with nested items into flat list blocks
  */
 const expandListToHierarchical = (
   listData: LegacyListData,
@@ -217,7 +229,7 @@ const collectChildItems = (
 
   for (const childId of contentIds) {
     const childBlock = blockMap.get(childId);
-    const isListItem = childBlock && childBlock.type === 'list_item';
+    const isListItem = childBlock && childBlock.type === 'list';
 
     if (isListItem) {
       const items = collectListItems(childBlock, blockMap, processedIds);
@@ -269,7 +281,7 @@ const collectListItems = (
 };
 
 /**
- * Process a root list_item block and convert to a legacy List block
+ * Process a root list block (flat model) and convert to a legacy List block
  */
 const processRootListItem = (
   block: OutputBlockData,
@@ -294,6 +306,13 @@ const processRootListItem = (
   return listBlock;
 };
 
+/**
+ * Check if a block is a flat-model list block (has 'text' field instead of 'items')
+ */
+const isFlatModelListBlock = (block: OutputBlockData): boolean => {
+  return block.type === 'list' && block.data?.text !== undefined && block.data?.items === undefined;
+};
+
 /**
  * Collapse hierarchical flat-with-references format back to legacy nested format
  * @param blocks - array of flat blocks with parent/content references
@@ -302,24 +321,21 @@ const processRootListItem = (
 export const collapseToLegacy = (blocks: OutputBlockData[]): OutputBlockData[] => {
   // Build a map of blocks by ID for quick lookup
   const blockMap = new Map<BlockId, OutputBlockData>();
-  const listItemBlocks: OutputBlockData[] = [];
 
   for (const block of blocks) {
     if (block.id) {
       blockMap.set(block.id, block);
     }
-
-    if (block.type === 'list_item') {
-      listItemBlocks.push(block);
-    }
   }
 
-  // If no list_item blocks, just strip hierarchy fields and return
-  if (listItemBlocks.length === 0) {
+  // If no flat-model list blocks, just strip hierarchy fields and return
+  const hasFlatListBlocks = blocks.some(isFlatModelListBlock);
+
+  if (!hasFlatListBlocks) {
     return blocks.map(stripHierarchyFields);
   }
 
-  // Process blocks, converting root list_items to List blocks
+  // Process blocks, converting root flat-model list blocks to legacy List blocks
   const result: OutputBlockData[] = [];
   const processedIds = new Set<BlockId>();
 
@@ -330,8 +346,9 @@ export const collapseToLegacy = (blocks: OutputBlockData[]): OutputBlockData[] =
       continue;
     }
 
-    const isRootListItem = block.type === 'list_item' && !block.parent;
-    const isNonListItem = block.type !== 'list_item';
+    const isFlatListBlock = isFlatModelListBlock(block);
+    const isRootListItem = isFlatListBlock && !block.parent;
+    const isNonListItem = !isFlatListBlock;
 
     if (isRootListItem) {
       const listBlock = processRootListItem(block, blockMap, processedIds);

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

@@ -265,7 +265,7 @@ export class PopoverItemDefault extends PopoverItem {
     if (params.secondaryLabel) {
       const secondaryEl = document.createElement('div');
 
-      secondaryEl.className = 'whitespace-nowrap pr-1.5 text-xs -tracking-widest text-text-secondary opacity-60';
+      secondaryEl.className = 'whitespace-nowrap pr-1.5 text-xs font-light tracking-[0.25px] text-text-secondary opacity-60';
       secondaryEl.setAttribute(DATA_ATTR.popoverItemSecondaryTitle, '');
       secondaryEl.setAttribute('data-blok-testid', 'popover-item-secondary-title');
       secondaryEl.textContent = params.secondaryLabel;

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

@@ -158,6 +158,17 @@ export abstract class PopoverItem {
     return this.params !== undefined && 'children' in this.params && this.params.children?.searchable === true;
   }
 
+  /**
+   * Returns the width for children popover, if specified
+   */
+  public get childrenWidth(): string | undefined {
+    if (this.params === undefined || !('children' in this.params)) {
+      return undefined;
+    }
+
+    return this.params.children?.width;
+  }
+
   /**
    * True if popover should close once item is activated
    */

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

@@ -399,7 +399,7 @@ export abstract class PopoverAbstract<Nodes extends PopoverNodes = PopoverNodes>
     popover.setAttribute('data-blok-testid', 'popover');
 
     // Set CSS variables
-    popover.style.setProperty('--width', '200px');
+    popover.style.setProperty('--width', this.params.width ?? '280px');
     popover.style.setProperty('--item-padding', '3px');
     popover.style.setProperty('--item-height', 'calc(1.25rem + 2 * var(--item-padding))');
     popover.style.setProperty('--popover-top', 'calc(100% + 0.5rem)');

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

@@ -401,6 +401,7 @@ export class PopoverDesktop extends PopoverAbstract {
       flippable: item.isChildrenFlippable,
       messages: this.messages,
       onNavigateBack: this.destroyNestedPopoverIfExists.bind(this),
+      width: item.childrenWidth,
     });
 
     item.onChildrenOpen();
@@ -452,14 +453,19 @@ export class PopoverDesktop extends PopoverAbstract {
     // Apply position: absolute for nested container
     nestedContainer.style.position = 'absolute';
 
+    // Get parent width - use computed width if --width is 'auto'
+    const parentWidth = this.params.width === 'auto'
+      ? `${this.nodes.popoverContainer.offsetWidth}px`
+      : 'var(--width)';
+
     // Calculate --popover-left based on nesting level and parent open direction
     // Set on the actual popover element to override its default value
     if (isParentOpenLeft) {
       // Position to the left
-      actualPopoverEl.style.setProperty(CSSVariables.PopoverLeft, 'calc(-1 * (var(--nesting-level) + 1) * var(--width) + 100%)');
+      actualPopoverEl.style.setProperty(CSSVariables.PopoverLeft, `calc(-1 * (var(--nesting-level) + 1) * ${parentWidth} + 100%)`);
     } else {
       // Position to the right
-      actualPopoverEl.style.setProperty(CSSVariables.PopoverLeft, 'calc(var(--nesting-level) * (var(--width) - var(--nested-popover-overlap)))');
+      actualPopoverEl.style.setProperty(CSSVariables.PopoverLeft, `calc(var(--nesting-level) * (${parentWidth} - var(--nested-popover-overlap)))`);
     }
 
     // Calculate top position based on parent open direction

package/src/stories/Popover.stories.ts

@@ -21,7 +21,6 @@ const POPOVER_ITEM_TESTID = '[data-blok-testid="popover-item"]';
 const POPOVER_OPENED_SELECTOR = '[data-blok-popover-opened="true"]';
 const ITEM_FOCUSED_SELECTOR = '[data-blok-focused=\"true\"]';
 const CONFIRMATION_SELECTOR = '[data-blok-popover-item-confirmation="true"]';
-const NOTHING_FOUND_SELECTOR = '[data-blok-nothing-found-displayed="true"]';
 const DELETE_BUTTON_SELECTOR = '[data-blok-item-name="delete"]';
 const CONVERT_TO_SELECTOR = '[data-blok-item-name="convert-to"]';
 const NESTED_POPOVER_SELECTOR = '[data-blok-nested="true"]';
@@ -451,90 +450,6 @@ export const SearchFiltering: Story = {
   },
 };
 
-/**
- * Popover nothing found message (in block settings).
- */
-export const NothingFoundMessage: Story = {
-  args: {
-    data: sampleData,
-  },
-  play: async ({ canvasElement, step }) => {
-    await step('Wait for editor and toolbar to initialize', async () => {
-      await waitFor(
-        () => {
-          const block = canvasElement.querySelector(BLOCK_TESTID);
-
-          expect(block).toBeInTheDocument();
-        },
-        TIMEOUT_INIT
-      );
-      // Wait for toolbar to be created (happens in requestIdleCallback)
-      await waitForToolbar(canvasElement);
-    });
-
-    await step('Click block to show toolbar', async () => {
-      const block = canvasElement.querySelector(BLOCK_TESTID);
-
-      if (block) {
-        simulateClick(block);
-      }
-
-      await waitFor(
-        () => {
-          const toolbar = canvasElement.querySelector(TOOLBAR_TESTID);
-
-          expect(toolbar).toHaveAttribute('data-blok-opened', 'true');
-        },
-        TIMEOUT_ACTION
-      );
-    });
-
-    await step('Open block settings', async () => {
-      const settingsButton = canvasElement.querySelector(SETTINGS_BUTTON_TESTID);
-
-      if (settingsButton) {
-        await userEvent.click(settingsButton);
-      }
-
-      await waitFor(
-        () => {
-          // Block tunes popover is appended to document.body
-          const blockTunesPopover = document.querySelector(BLOCK_TUNES_POPOVER_TESTID);
-
-          expect(blockTunesPopover).toBeInTheDocument();
-        },
-        TIMEOUT_ACTION
-      );
-    });
-
-    await step('Search for non-existent item', async () => {
-      // Wait for popover to be fully rendered and search input to be available
-      await new Promise((resolve) => setTimeout(resolve, 100));
-
-      // Find and focus the search input inside the popover
-      const searchInput = document.querySelector('[data-blok-testid="popover-search-input"]') as HTMLInputElement;
-
-      if (searchInput) {
-        searchInput.focus();
-        // Type directly into the input
-        searchInput.value = 'xyznonexistent';
-        // Trigger input event to notify the search handler
-        searchInput.dispatchEvent(new Event('input', { bubbles: true }));
-      }
-
-      await waitFor(
-        () => {
-          // Nothing found message is inside the popover which is in document.body
-          const nothingFound = document.querySelector(NOTHING_FOUND_SELECTOR);
-
-          expect(nothingFound).toBeInTheDocument();
-        },
-        TIMEOUT_ACTION
-      );
-    });
-  },
-};
-
 /**
  * Popover item in disabled state.
  */

package/src/styles/main.css

@@ -84,17 +84,20 @@
 }
 
 [data-drop-indicator]::before {
-  @apply content-[''] absolute -translate-x-1/2 w-full max-w-content h-1.5 rounded-sm bg-[#d4e3fc] pointer-events-none z-10;
-  left: calc(50% + var(--drop-indicator-depth, 0) * 12px);
+  @apply content-[''] absolute w-full max-w-content h-1.5 rounded-sm bg-[#d4e3fc] pointer-events-none z-10;
+  left: 50%;
+  margin-left: calc(var(--drop-indicator-depth, 0) * 12px);
   max-width: calc(650px - var(--drop-indicator-depth, 0) * 24px);
 }
 
 [data-drop-indicator="bottom"]::before {
-  @apply translate-y-1/2 bottom-0;
+  @apply bottom-0;
+  transform: translateX(-50%) translateY(50%);
 }
 
 [data-drop-indicator="top"]::before {
-  @apply -translate-y-1/2 top-0;
+  @apply top-0;
+  transform: translateX(-50%) translateY(-50%);
 }
 
 /**

package/src/tools/header/index.ts

@@ -641,6 +641,7 @@ export class Header implements BlockTool {
       name: `header-${level.number}`,
       data: { level: level.number },
       searchTerms: [`h${level.number}`, 'title', 'header', 'heading'],
+      shortcut: '#'.repeat(level.number),
     }));
   }
 }

package/src/tools/list/index.ts

@@ -17,7 +17,7 @@ import type {
   PasteEvent,
   ToolboxConfig,
   ConversionConfig,
-  SanitizerConfig,
+  ToolSanitizerConfig,
   PasteConfig,
 } from '../../../types';
 import type { MenuConfig } from '../../../types/tools/menu-config';
@@ -183,7 +183,14 @@ export class ListItem implements BlockTool {
    */
   private static pendingMarkerUpdate = false;
 
-  sanitize?: SanitizerConfig | undefined;
+  sanitize?: ToolSanitizerConfig | undefined;
+
+  /**
+   * Legacy list item structure for backward compatibility
+   */
+  private static isLegacyFormat(data: unknown): data is { items: Array<{ content: string; checked?: boolean }>, style?: ListItemStyle, start?: number } {
+    return typeof data === 'object' && data !== null && 'items' in data && Array.isArray((data as { items: unknown }).items);
+  }
 
   private normalizeData(data: ListItemData | Record<string, never>): ListItemData {
     const defaultStyle = this._settings.defaultStyle || 'unordered';
@@ -197,6 +204,22 @@ export class ListItem implements BlockTool {
       };
     }
 
+    // Handle legacy format with items[] array - extract first item's content
+    // This provides backward compatibility when legacy data is passed directly to the tool
+    if (ListItem.isLegacyFormat(data)) {
+      const firstItem = data.items[0];
+      const text = firstItem?.content || '';
+      const checked = firstItem?.checked || false;
+
+      return {
+        text,
+        style: data.style || defaultStyle,
+        checked: Boolean(checked),
+        depth: 0,
+        ...(data.start !== undefined && data.start !== 1 ? { start: data.start } : {}),
+      };
+    }
+
     return {
       text: data.text || '',
       style: data.style || defaultStyle,
@@ -1665,11 +1688,15 @@ export class ListItem implements BlockTool {
     };
   }
 
-  public static get sanitize(): SanitizerConfig {
+  public static get sanitize(): ToolSanitizerConfig {
     return {
       text: {
         br: true,
-        a: true,
+        a: {
+          href: true,
+          target: '_blank',
+          rel: 'nofollow',
+        },
         b: true,
         i: true,
         mark: true,
@@ -1797,6 +1824,7 @@ export class ListItem implements BlockTool {
         data: { style: 'unordered' },
         name: 'bulleted-list',
         searchTerms: ['ul', 'bullet', 'unordered', 'list'],
+        shortcut: '-',
       },
       {
         icon: IconListNumbered,
@@ -1805,6 +1833,7 @@ export class ListItem implements BlockTool {
         data: { style: 'ordered' },
         name: 'numbered-list',
         searchTerms: ['ol', 'ordered', 'number', 'list'],
+        shortcut: '1.',
       },
       {
         icon: IconListChecklist,
@@ -1813,6 +1842,7 @@ export class ListItem implements BlockTool {
         data: { style: 'checklist' },
         name: 'check-list',
         searchTerms: ['checkbox', 'task', 'todo', 'check', 'list'],
+        shortcut: '[]',
       },
     ];
   }

package/types/configs/sanitizer-config.d.ts

@@ -4,7 +4,7 @@
  */
 export type TagConfig = boolean | { [attr: string]: boolean | string };
 
-export type SanitizerRule = TagConfig | ((el: Element) => TagConfig)
+export type SanitizerRule = TagConfig | ((el: Element) => TagConfig);
 
 export interface SanitizerConfig {
   /**
@@ -41,3 +41,27 @@ export interface SanitizerConfig {
    */
   [key: string]: SanitizerRule;
 }
+
+/**
+ * Sanitizer config for Block Tools that supports field-specific tag rules.
+ * Use this when your tool's data has multiple fields that each need different sanitization.
+ *
+ * @example Field-specific sanitization
+ * ```typescript
+ * static get sanitize(): ToolSanitizerConfig {
+ *   return {
+ *     text: {
+ *       br: true,
+ *       a: { href: true, target: '_blank', rel: 'nofollow' }
+ *     },
+ *     caption: {
+ *       b: true,
+ *       i: true
+ *     }
+ *   };
+ * }
+ * ```
+ */
+export interface ToolSanitizerConfig {
+  [key: string]: SanitizerRule | SanitizerConfig;
+}

package/types/index.d.ts

@@ -72,6 +72,7 @@ export {
   BlokConfig,
   SanitizerConfig,
   SanitizerRule,
+  ToolSanitizerConfig,
   PasteConfig,
   LogLevels,
   ConversionConfig,

package/types/tools/block-tool.d.ts

@@ -1,4 +1,4 @@
-import { ConversionConfig, PasteConfig, SanitizerConfig } from '../configs';
+import { ConversionConfig, PasteConfig, ToolSanitizerConfig } from '../configs';
 import { BlockToolData } from './block-tool-data';
 import { BaseTool, BaseToolConstructable, BaseToolConstructorOptions } from './tool';
 import { ToolConfig } from './tool-config';
@@ -15,7 +15,7 @@ export interface BlockTool extends BaseTool {
   /**
    * Sanitizer rules description
    */
-  sanitize?: SanitizerConfig;
+  sanitize?: ToolSanitizerConfig;
 
   /**
    * Process Tool's element in DOM and return raw data

package/types/tools/tool-settings.d.ts

@@ -52,6 +52,13 @@ export interface ToolboxConfigEntry {
    * Terms are matched case-insensitively.
    */
   searchTerms?: string[];
+
+  /**
+   * Shortcut hint to display in the toolbox (e.g., '#', '##', '-', '1.', '[]').
+   * This is displayed as a secondary label next to the tool title.
+   * Unlike tool-level shortcuts, these are per-entry hints for tools with multiple variants.
+   */
+  shortcut?: string;
 }
 
 /**

package/types/utils/popover/popover-item.d.ts

@@ -45,6 +45,12 @@ export interface PopoverItemChildren {
    * Useful for items like link tool that render custom content instead of a dropdown list.
    */
   hideChevron?: boolean;
+
+  /**
+   * Width of the nested popover. Defaults to '280px'.
+   * Use 'auto' to fit content width.
+   */
+  width?: string;
 }
 
 /**

package/types/utils/popover/popover.d.ts

@@ -65,6 +65,12 @@ export interface PopoverParams {
    * Used to close nested popover and return focus to parent.
    */
   onNavigateBack?: () => void;
+
+  /**
+   * Width of the popover. Defaults to '280px'.
+   * Use 'auto' to fit content width.
+   */
+  width?: string;
 }