@jackuait/blok 0.11.1 → 0.12.1

package/src/components/modules/toolbar/settings-toggler.ts

@@ -3,6 +3,7 @@ import type { Block } from '../../block';
 import { DATA_ATTR } from '../../constants';
 import { Dom as $ } from '../../dom';
 import { IconMenu } from '../../icons';
+import { getUserOS } from '../../utils';
 import { hide, onHover } from '../../utils/tooltip';
 import { twJoin } from '../../utils/tw';
 
@@ -113,15 +114,15 @@ export class SettingsTogglerHandler {
     const settingsToggler = $.make('span', [
       twJoin(
         // Base toolbox-button styles
-        'text-text-secondary cursor-pointer w-[22px] h-6 rounded-[5px] inline-flex justify-center items-center select-none',
+        'text-text-secondary cursor-pointer w-[18px] h-6 rounded-[5px] inline-flex justify-center items-center select-none',
         // SVG sizing
-        '[&_svg]:h-[22px] [&_svg]:w-[22px]',
+        '[&_svg]:h-[22px] [&_svg]:w-[22px] [&_svg]:shrink-0',
         // Active state
         'active:cursor-grabbing',
         // Hover (can-hover)
         'can-hover:hover:bg-bg-light can-hover:hover:cursor-grab',
-        // When toolbox is opened, use pointer cursor on hover
-        'can-hover:hover:group-data-[blok-toolbox-opened=true]:cursor-pointer',
+        // Hide when the toolbox popover is open
+        'group-data-[blok-toolbox-opened=true]:hidden',
         // When block settings is opened, show hover background and pointer cursor
         'group-data-[blok-block-settings-opened=true]:bg-bg-light',
         'can-hover:hover:group-data-[blok-block-settings-opened=true]:cursor-pointer',
@@ -160,9 +161,19 @@ export class SettingsTogglerHandler {
     /**
      * Add events to show/hide tooltip for settings toggler
      */
+    const userOS = getUserOS();
+    const shortcut = userOS.win
+      ? blok.I18n.t('blockSettings.menuShortcutWin')
+      : blok.I18n.t('blockSettings.menuShortcutMac');
+
     const blockTunesTooltip = createTooltipContent([
       blok.I18n.t('blockSettings.dragToMove'),
-      blok.I18n.t('blockSettings.clickToOpenMenu'),
+      [
+        { text: 'Click', highlight: true },
+        { text: ' or ', highlight: false },
+        { text: shortcut, highlight: true },
+        { text: ' to open menu', highlight: false },
+      ],
     ]);
 
     onHover(settingsToggler, blockTunesTooltip, {

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

@@ -1,36 +1,80 @@
 import { Dom as $ } from '../../dom';
 
+/**
+ * A single text segment within a tooltip line.
+ * When `highlight` is true, the segment is rendered as a white-colored span.
+ */
+export interface TooltipSegment {
+  text: string;
+  highlight: boolean;
+}
+
+/**
+ * A tooltip line can be either:
+ * - a plain string (the first word is automatically highlighted in white), or
+ * - an array of TooltipSegment objects for precise per-token highlighting.
+ */
+export type TooltipLine = string | TooltipSegment[];
+
+/**
+ * Applies highlight styling (white color, semibold weight) to a span element.
+ */
+const applyHighlight = (span: HTMLElement): void => {
+  // eslint-disable-next-line no-param-reassign -- intentional styling helper
+  span.style.color = 'white';
+  // eslint-disable-next-line no-param-reassign -- intentional styling helper
+  span.style.fontWeight = '500';
+};
+
 /**
  * Creates a tooltip content element with multiple lines and consistent styling.
- * The first word of each line is styled in white to highlight keyboard shortcuts.
+ * The first word of each string line is styled in white to highlight keywords.
+ * Segment-based lines allow highlighting multiple specific tokens per line.
  *
- * @param lines - Array of text strings, each will be displayed on its own line
+ * @param lines - Array of lines; each line is a string or an array of TooltipSegment
  * @returns The tooltip container element
  */
-export const createTooltipContent = function(lines: string[]): HTMLElement {
+export const createTooltipContent = function(lines: TooltipLine[]): HTMLElement {
   const container = $.make('div');
 
   container.style.display = 'flex';
   container.style.flexDirection = 'column';
   container.style.gap = '4px';
+  container.style.color = 'rgba(255, 255, 255, 0.55)';
 
-  lines.forEach((text) => {
-    const line = $.make('div');
-    const spaceIndex = text.indexOf(' ');
+  lines.forEach((line) => {
+    const lineEl = $.make('div');
 
-    if (spaceIndex > 0) {
-      const firstWord = text.substring(0, spaceIndex);
-      const rest = text.substring(spaceIndex);
-      const styledWord = $.make('span', null, { textContent: firstWord });
+    if (Array.isArray(line)) {
+      // Segment-based line: render each segment as a span (highlighted) or text node
+      line.forEach((segment) => {
+        if (segment.highlight) {
+          const span = $.make('span', null, { textContent: segment.text });
 
-      styledWord.style.color = 'white';
-      line.appendChild(styledWord);
-      line.appendChild(document.createTextNode(rest));
+          applyHighlight(span);
+          lineEl.appendChild(span);
+        } else {
+          lineEl.appendChild(document.createTextNode(segment.text));
+        }
+      });
     } else {
-      line.appendChild(document.createTextNode(text));
+      // String-based line: highlight the first word
+      const spaceIndex = line.indexOf(' ');
+
+      if (spaceIndex > 0) {
+        const firstWord = line.substring(0, spaceIndex);
+        const rest = line.substring(spaceIndex);
+        const styledWord = $.make('span', null, { textContent: firstWord });
+
+        applyHighlight(styledWord);
+        lineEl.appendChild(styledWord);
+        lineEl.appendChild(document.createTextNode(rest));
+      } else {
+        lineEl.appendChild(document.createTextNode(line));
+      }
     }
 
-    container.appendChild(line);
+    container.appendChild(lineEl);
   });
 
   return container;

package/src/components/modules/ui.ts

@@ -529,14 +529,20 @@ export class UI extends Module<UINodes> {
   }
 
   /**
-   * Injects a font-family override stylesheet when config.style.fontFamily is set.
-   * Uses a separate <style> tag so it applies even when blok-styles already exists
-   * (multiple editor instances on the same page).
+   * Injects font-family override stylesheets when any config.style font field is set.
+   * Handles: --blok-font-family (legacy), --blok-font-sans, --blok-font-serif,
+   * --blok-font-mono, and --blok-font-handwriting.
    */
   private loadFontStyles(): void {
-    const fontFamily = this.config.style?.fontFamily;
-
-    if (!fontFamily) {
+    const style = this.config.style;
+    const hasAnyFont =
+      style?.fontFamily ||
+      style?.fontFamilySans ||
+      style?.fontFamilySerif ||
+      style?.fontFamilyMono ||
+      style?.fontFamilyHandwriting;
+
+    if (!hasAnyFont) {
       return;
     }
 
@@ -549,12 +555,21 @@ export class UI extends Module<UINodes> {
       return;
     }
 
+    const varLines: string[] = [];
+
+    if (style.fontFamily)            varLines.push(`  --blok-font-family: ${style.fontFamily};`);
+    if (style.fontFamilySans)        varLines.push(`  --blok-font-sans: ${style.fontFamilySans};`);
+    if (style.fontFamilySerif)       varLines.push(`  --blok-font-serif: ${style.fontFamilySerif};`);
+    if (style.fontFamilyMono)        varLines.push(`  --blok-font-mono: ${style.fontFamilyMono};`);
+    if (style.fontFamilyHandwriting) varLines.push(`  --blok-font-handwriting: ${style.fontFamilyHandwriting};`);
+
+    const vars = varLines.join('\n');
     const css = [
       `[data-blok-interface=blok], [data-blok-interface=tooltip] {`,
-      `  --blok-font-family: ${fontFamily};`,
+      vars,
       `}`,
       `[data-blok-popover]:not([data-blok-popover-inline]) {`,
-      `  --blok-font-family: ${fontFamily};`,
+      vars,
       `}`,
     ].join('\n');
 

package/src/components/ui/toolbox.ts

@@ -59,6 +59,73 @@ export interface ToolboxEventMap {
  */
 type ToolboxTextLabelsKeys = 'filter' | 'nothingFound' | 'slashSearchPlaceholder';
 
+/**
+ * Pick the DOMRect used to anchor the toolbox popover.
+ * - Slash open with a slash-search pill present: use the pill's own rect so
+ *   the popover sits below the pill's visual bottom — the same way plus-button
+ *   anchors at the block's bottom. This keeps the popover-to-field gap equal
+ *   between plus-search and slash-search.
+ * - Slash open without a pill (e.g., nested container where the pill was not
+ *   applied): use the caret rect directly.
+ * - Plus button (or slash with degenerate caret): build a composite rect from
+ *   the block's CONTENT element (horizontal bounds) and the block holder
+ *   (vertical bounds). Using the holder's horizontal bounds would snap the
+ *   popover to the editor's left viewport edge in layouts where the holder is
+ *   wider than the centered content column.
+ * @param params - anchor inputs
+ * @param params.caretRect - current selection rect, if any
+ * @param params.caretRectIsDegenerate - true when the caret rect is {0,0,0,0}
+ * @param params.blockRect - the current block holder rect
+ * @param params.contentElement - the current block's content element, if any
+ * @param params.slashSearchElement - the slash-search pill element, if any
+ */
+const resolveAnchorRect = (params: {
+  caretRect: DOMRect | undefined;
+  caretRectIsDegenerate: boolean;
+  blockRect: DOMRect | undefined;
+  contentElement: HTMLElement | null;
+  slashSearchElement: HTMLElement | null;
+}): DOMRect | undefined => {
+  const { caretRect, caretRectIsDegenerate, blockRect, contentElement, slashSearchElement } = params;
+
+  if (slashSearchElement !== null) {
+    const pillRect = slashSearchElement.getBoundingClientRect();
+
+    if (pillRect.width > 0 || pillRect.height > 0) {
+      /**
+       * Tighten the visual gap below the pill without changing the popover's
+       * own offset constant. The popover anchors at rect.bottom + 8; shrinking
+       * the anchor height by this inset pulls the popover a few pixels closer
+       * to the pill. Affects both slash-search and plus-search (same anchor).
+       */
+      const PILL_BOTTOM_INSET = 2;
+
+      return new DOMRect(
+        pillRect.left,
+        pillRect.top,
+        pillRect.width,
+        Math.max(0, pillRect.height - PILL_BOTTOM_INSET)
+      );
+    }
+  }
+
+  if (caretRect !== undefined && !caretRectIsDegenerate) {
+    return caretRect;
+  }
+
+  if (blockRect === undefined) {
+    return undefined;
+  }
+
+  const contentRect = contentElement?.getBoundingClientRect();
+
+  if (contentRect === undefined) {
+    return blockRect;
+  }
+
+  return new DOMRect(contentRect.left, blockRect.top, contentRect.width, blockRect.height);
+};
+
 /**
  * Toolbox
  * This UI element contains list of Block Tools available to be inserted
@@ -347,13 +414,25 @@ export class Toolbox extends EventsDispatcher<ToolboxEventMap> {
      *
      * - Slash open ("/"): anchor at the caret rect so the menu appears next to
      *   what the user is typing, in any block type at any nesting depth.
-     * - Plus button open: anchor at the current block's bounding rect so the
-     *   menu appears below the block regardless of trigger placement.
+     * - Plus button open: build a composite rect that uses the block's CONTENT
+     *   element for horizontal bounds (so the menu aligns with the visible
+     *   content column) and the block holder for vertical bounds (so the menu
+     *   sits below the block). Using the holder rect for horizontal bounds
+     *   snapped the menu to the editor's left viewport edge whenever the holder
+     *   was wider than the centered content column.
      *
      * Set the position BEFORE show() so the first paint is already correct —
      * popover.show() reads `params.position` via calculatePosition() and uses
      * it instead of the trigger rect when present.
      */
+    /**
+     * Attach the slash-search pill styling BEFORE computing the anchor rect so
+     * getBoundingClientRect reflects the pill's applied margin/padding — the
+     * popover gap is calculated from that rect and must not predate the class
+     * application.
+     */
+    this.startListeningToBlockInput();
+
     if (this.popover instanceof PopoverDesktop) {
       const blockRect = currentBlock?.holder.getBoundingClientRect();
       const caretRect = withSlash ? SelectionUtils.rect : undefined;
@@ -362,9 +441,16 @@ export class Toolbox extends EventsDispatcher<ToolboxEventMap> {
         && caretRect.height === 0
         && caretRect.x === 0
         && caretRect.y === 0;
-      // Fall back to the block rect when selection is lost or returns a
-      // degenerate {0,0,0,0} rect — never anchor the popover at the page origin.
-      const anchorRect = caretRect !== undefined && !caretRectIsDegenerate ? caretRect : blockRect;
+
+      const anchorRect = resolveAnchorRect({
+        caretRect,
+        caretRectIsDegenerate,
+        blockRect,
+        contentElement: currentBlock?.holder
+          .querySelector<HTMLElement>(`[${DATA_ATTR.elementContent}]`) ?? null,
+        slashSearchElement: currentBlock?.holder
+          .querySelector<HTMLElement>(`[${DATA_ATTR.slashSearch}]`) ?? null,
+      });
 
       if (anchorRect !== undefined) {
         this.popover.updatePosition(anchorRect);
@@ -376,7 +462,6 @@ export class Toolbox extends EventsDispatcher<ToolboxEventMap> {
     this.openedWithSlash = withSlash;
     this.opened = true;
     this.emit(ToolboxEvent.Opened);
-    this.startListeningToBlockInput();
   }
 
   /**
@@ -440,7 +525,7 @@ export class Toolbox extends EventsDispatcher<ToolboxEventMap> {
       },
       items: this.toolboxItemsToBeDisplayed,
       handleContentEditableNavigation: true,
-      minWidth: '250px',
+      minWidth: '220px',
     });
 
     this.popover.on(PopoverEvent.Closed, this.onPopoverClose);

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

@@ -231,6 +231,31 @@ const isLegacyCalloutBlock = (block: OutputBlockData): block is OutputBlockData<
   return typeof data === 'object' && data !== null && 'body' in data;
 };
 
+/**
+ * Check if a block is in legacy image format
+ * Legacy editor.js shape: { type: "image", data: { file: { url: "..." }, caption?, withBorder?, withBackground?, stretched? } }
+ * New shape: { type: "image", data: { url, caption?, ... } }
+ */
+const isLegacyImageBlock = (block: OutputBlockData): boolean => {
+  if (block.type !== 'image') {
+    return false;
+  }
+
+  const data = block.data as Record<string, unknown> | null | undefined;
+
+  if (typeof data !== 'object' || data === null) {
+    return false;
+  }
+
+  const file = (data as { file?: unknown }).file;
+
+  if (typeof file !== 'object' || file === null) {
+    return false;
+  }
+
+  return typeof (file as { url?: unknown }).url === 'string';
+};
+
 /**
  * Check if a block contains nested hierarchy in its items
  */
@@ -269,7 +294,10 @@ export const analyzeDataFormat = (blocks: OutputBlockData[]): DataFormatAnalysis
   // Check if any block uses legacy callout format (has body field)
   const foundLegacyCallout = blocks.some(isLegacyCalloutBlock);
 
-  const hasLegacyBlocks = foundLegacyList || foundLegacyToggle || foundLegacyCallout;
+  // Check if any block uses legacy image format (has data.file.url)
+  const foundLegacyImage = blocks.some(isLegacyImageBlock);
+
+  const hasLegacyBlocks = foundLegacyList || foundLegacyToggle || foundLegacyCallout || foundLegacyImage;
 
   if (foundHierarchicalRefs && !hasLegacyBlocks) {
     return { format: 'hierarchical', hasHierarchy: true };
@@ -527,6 +555,45 @@ const expandCalloutToHierarchical = (
   return blocks;
 };
 
+/**
+ * Expand a legacy image block (editor.js shape with `data.file.url`) into
+ * the new flat image shape understood by Blok's ImageTool (see
+ * types/tools/image.d.ts). Moves `data.file.url` to `data.url`, drops the
+ * `file` wrapper, and maps legacy editor.js flags to ImageData fields:
+ *
+ *   - `withBorder: true`  → `frame: 'border'` (false: drop, default is 'none')
+ *   - `withBackground`    → drop entirely (no Blok equivalent)
+ *   - `stretched: true`   → `size: 'full'`   (false: drop)
+ *
+ * All other unknown fields pass through untouched so future editor.js data
+ * can't silently lose information.
+ */
+const expandImageToHierarchical = (block: OutputBlockData): OutputBlockData => {
+  const rawData = (block.data ?? {}) as Record<string, unknown>;
+  const {
+    file,
+    withBorder,
+    withBackground: _withBackground,
+    stretched,
+    ...rest
+  } = rawData;
+  const fileUrl = typeof file === 'object' && file !== null
+    ? (file as { url?: unknown }).url
+    : undefined;
+  const url = typeof fileUrl === 'string' ? fileUrl : '';
+
+  return {
+    ...block,
+    id: block.id ?? generateBlockId(),
+    data: {
+      url,
+      ...rest,
+      ...(withBorder === true ? { frame: 'border' } : {}),
+      ...(stretched === true ? { size: 'full' } : {}),
+    },
+  };
+};
+
 /**
  * Expand legacy nested format to hierarchical flat-with-references format
  * @param blocks - array of blocks potentially containing nested structures
@@ -552,6 +619,9 @@ export const expandToHierarchical = (blocks: OutputBlockData[]): OutputBlockData
       const expanded = expandCalloutToHierarchical(block);
 
       expandedBlocks.push(...expanded);
+    } else if (isLegacyImageBlock(block)) {
+      // Expand legacy image (data.file.url → data.url) to new flat image shape
+      expandedBlocks.push(expandImageToHierarchical(block));
     } else {
       // Non-list blocks pass through unchanged (with guaranteed ID)
       expandedBlocks.push({

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

@@ -10,7 +10,7 @@ export const css = {
    * Note: noHover state is handled via [data-blok-popover-item-no-hover] which disables hover
    * Priority order: active < hover < focus (focus wins when navigating with keyboard)
    */
-  item: 'flex items-center select-none border-none bg-transparent rounded-lg px-2 py-1 text-text-primary mb-px outline-hidden max-h-9 overflow-hidden data-blok-popover-item-active:bg-icon-active-bg data-blok-popover-item-active:text-icon-active-text can-hover:hover:cursor-pointer can-hover:hover:bg-item-hover-bg data-blok-force-hover:cursor-pointer data-blok-force-hover:bg-item-hover-bg data-[blok-focused="true"]:bg-item-focus-bg data-blok-popover-item-no-hover:hover:bg-transparent data-blok-popover-item-no-hover:cursor-default can-hover:data-blok-popover-item-destructive:hover:text-item-destructive-text can-hover:data-blok-popover-item-destructive:hover:bg-item-destructive-hover-bg [&[data-blok-popover-item-destructive][data-blok-force-hover]]:text-item-destructive-text [&[data-blok-popover-item-destructive][data-blok-force-hover]]:bg-item-destructive-hover-bg [&[data-blok-popover-item-destructive][data-blok-focused="true"]]:text-item-destructive-text [&[data-blok-popover-item-destructive][data-blok-focused="true"]]:bg-item-destructive-hover-bg',
+  item: 'flex items-center select-none border-none bg-transparent rounded-lg px-2 py-1 text-text-primary mb-px outline-hidden max-h-8 overflow-hidden data-blok-popover-item-active:bg-icon-active-bg data-blok-popover-item-active:text-icon-active-text can-hover:hover:cursor-pointer can-hover:hover:bg-item-hover-bg data-blok-force-hover:cursor-pointer data-blok-force-hover:bg-item-hover-bg data-[blok-focused="true"]:bg-item-focus-bg data-blok-popover-item-no-hover:hover:bg-transparent data-blok-popover-item-no-hover:cursor-default can-hover:data-blok-popover-item-destructive:hover:text-item-destructive-text can-hover:data-blok-popover-item-destructive:hover:bg-item-destructive-hover-bg [&[data-blok-popover-item-destructive][data-blok-force-hover]]:text-item-destructive-text [&[data-blok-popover-item-destructive][data-blok-force-hover]]:bg-item-destructive-hover-bg [&[data-blok-popover-item-destructive][data-blok-focused="true"]]:text-item-destructive-text [&[data-blok-popover-item-destructive][data-blok-focused="true"]]:bg-item-destructive-hover-bg',
 
   /**
    * Item disabled state
@@ -21,7 +21,7 @@ export const css = {
   /**
    * Icon container styles
    */
-  icon: 'flex items-center justify-center w-7 h-7 shrink-0 rounded-lg bg-popover-icon-bg [&_svg]:w-icon [&_svg]:h-icon',
+  icon: 'flex items-center justify-center w-6 h-6 shrink-0 rounded-lg bg-popover-icon-bg [&_svg]:w-4 [&_svg]:h-4',
 
   /**
    * Focused state class for DomIterator/Flipper keyboard navigation.
@@ -37,8 +37,9 @@ export const cssInline = {
   /**
    * Item in inline context - more compact styling
    */
-  item: 'rounded-lg p-1',
-  itemIconOnly: 'aspect-square justify-center',
+  item: 'rounded-md px-1 py-1.5',
+  itemIconOnly: 'justify-center',
+  itemWithTitle: 'px-2',
 };
 
 /**

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

@@ -351,6 +351,7 @@ export class PopoverItemDefault extends PopoverItem {
       !isInline && !isNestedInline && 'pl-2 pr-3',
       isInline && cssInline.item,
       isInline && this.params.icon && cssInline.itemIconOnly,
+      isInline && this.params.title && cssInline.itemWithTitle,
       isNestedInline && cssNestedInline.item,
       this.params.isDisabled && css.itemDisabled
     );

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

@@ -2,7 +2,7 @@
  * Tailwind CSS classes for popover separator component
  */
 export const css = {
-  container: 'py-1.5 px-2 max-h-5 overflow-hidden',
+  container: 'py-1.5 max-h-5 overflow-hidden',
   containerHidden: 'opacity-0 max-h-0! py-0!',
   line: 'h-px w-full bg-popover-border/60',
 };

package/src/components/utils/popover/components/search-input/search-input.const.ts

@@ -2,7 +2,7 @@
  * CSS class names to be used in popover search input class
  */
 export const css = {
-  wrapper: 'bg-search-input-bg border border-search-input-border rounded-lg p-1 grid grid-cols-[auto_1fr] grid-rows-[auto] focus-within:border-search-input-focus-border focus-within:shadow-[0_0_0_2px_rgba(35,131,226,0.15)]',
-  icon: 'w-toolbox-btn h-toolbox-btn flex items-center justify-center mr-2 [&_svg]:w-icon [&_svg]:h-icon [&_svg]:text-gray-text',
-  input: "text-sm outline-hidden font-medium font-inherit border-0 bg-transparent m-0 p-0 leading-[22px] min-w-[calc(100%-(--spacing(6))-10px)] text-text-primary placeholder:text-gray-text/80 placeholder:font-normal",
+  wrapper: 'bg-search-input-bg border border-search-input-border rounded-lg px-2 py-0.5 grid grid-cols-[auto_1fr] grid-rows-[auto] focus-within:border-search-input-focus-border focus-within:shadow-[0_0_0_2px_rgba(35,131,226,0.15)]',
+  icon: 'w-6 h-6 flex items-center justify-center mr-1.5 [&_svg]:w-4 [&_svg]:h-4 [&_svg]:text-gray-text',
+  input: "text-sm outline-hidden font-medium font-inherit border-0 bg-transparent m-0 p-0 leading-[20px] min-w-[calc(100%-(--spacing(6))-6px)] text-text-primary placeholder:text-gray-text/80 placeholder:font-normal",
 };