@jackuait/blok 0.10.0-beta.13 → 0.10.0-beta.15

package/src/cli/commands/convert-html/preprocessor.ts

@@ -0,0 +1,348 @@
+/**
+ * Preprocess old knowledgebase HTML before block conversion.
+ *
+ * Fixes issues from the old KB's Summernote editor:
+ * 1. `<div style="background: rgb(...)">` callout-like blocks → `<aside>`
+ * 2. White/transparent `background-color` on inline elements → stripped
+ * 3. Multiple `<p>` inside table cells → `<br>`-separated content
+ * 4. `<p>&nbsp;</p>` visual spacers → removed
+ * 5. `<del>`/`<strike>` → `<s>` (Blok only recognises `<s>`)
+ * 6. `<p>• text</p>` pseudo-lists → `<ul><li>text</li></ul>`
+ *
+ * Adapted from the knowledgebase frontend's preprocessKnowledgebaseHtml
+ * for use with jsdom's DOM API in a Node.js CLI tool.
+ */
+export function preprocess(wrapper: HTMLElement): void {
+  convertBackgroundDivsToCallouts(wrapper);
+  stripSpuriousBackgroundColors(wrapper);
+  convertTableCellParagraphs(wrapper);
+  stripNbspOnlyParagraphs(wrapper);
+  convertStrikethroughTags(wrapper);
+  convertBulletParagraphsToLists(wrapper);
+}
+
+/**
+ * Convert block-level `<div>` elements with background colors to `<aside>`.
+ *
+ * Skips divs inside tables and those with white/transparent backgrounds.
+ * Unwraps non-semantic inner `<div>` wrappers and strips trailing `<br>`
+ * inside paragraphs.
+ */
+function convertBackgroundDivsToCallouts(wrapper: HTMLElement): void {
+  const doc = wrapper.ownerDocument;
+
+  for (const div of Array.from(wrapper.querySelectorAll<HTMLElement>('div[style]'))) {
+    if (div.closest('table')) {
+      continue;
+    }
+
+    const bgColor = getBackgroundColor(div);
+
+    if (!bgColor || isSpuriousBackgroundColor(bgColor)) {
+      continue;
+    }
+
+    const aside = doc.createElement('aside');
+
+    aside.style.backgroundColor = bgColor;
+    aside.append(...Array.from(div.childNodes));
+
+    // Unwrap non-semantic <div> wrappers so the aside's direct children are
+    // the content elements (<p>, <a>, etc.), not intermediate <div> shells.
+    let bareDivs: HTMLElement[];
+
+    while ((bareDivs = Array.from(aside.querySelectorAll<HTMLElement>(':scope > div'))
+      .filter((d) => !d.getAttribute('style') && !d.getAttribute('class'))).length > 0) {
+      for (const child of bareDivs) {
+        child.replaceWith(...Array.from(child.childNodes));
+      }
+    }
+
+    // Strip trailing <br> inside paragraphs — the paste handler splits
+    // content at <br> boundaries, so a trailing one creates an empty block.
+    for (const p of Array.from(aside.querySelectorAll('p'))) {
+      const lastChild = p.lastElementChild;
+
+      if (lastChild?.tagName === 'BR') {
+        lastChild.remove();
+      }
+    }
+
+    div.replaceWith(aside);
+  }
+}
+
+/**
+ * Minimum channel brightness for a colour to be considered "near-white".
+ *
+ * Any `rgb(r, g, b)` where all three channels are >= this value is stripped.
+ */
+const NEAR_WHITE_MIN_CHANNEL = 250;
+
+/**
+ * Remove white/transparent `background-color` from inline elements.
+ *
+ * After stripping the property, empty wrapper elements (no remaining styles
+ * and no text) are unwrapped.
+ */
+function stripSpuriousBackgroundColors(wrapper: HTMLElement): void {
+  const candidates = wrapper.querySelectorAll<HTMLElement>('[style*="background-color"]');
+
+  for (const el of Array.from(candidates)) {
+    if (isSpuriousBackgroundColor(el.style.backgroundColor)) {
+      el.style.removeProperty('background-color');
+
+      if (el.getAttribute('style')?.trim() === '') {
+        el.removeAttribute('style');
+      }
+
+      if (isEmptyWrapper(el)) {
+        el.replaceWith(...Array.from(el.childNodes));
+      }
+    }
+  }
+}
+
+/**
+ * Check whether a computed `background-color` value is visually invisible
+ * (white, near-white, or transparent).
+ */
+function isSpuriousBackgroundColor(value: string): boolean {
+  if (!value) {
+    return false;
+  }
+
+  const normalised = value.replace(/\s/g, '').toLowerCase();
+
+  if (normalised === 'transparent') {
+    return true;
+  }
+
+  const rgbaMatch = normalised.match(/^rgba?\((\d+),(\d+),(\d+)(?:,([^)]+))?\)$/);
+
+  if (!rgbaMatch) {
+    return false;
+  }
+
+  const alpha = rgbaMatch[4] !== undefined ? parseFloat(rgbaMatch[4]) : 1;
+
+  if (alpha === 0) {
+    return true;
+  }
+
+  const r = parseInt(rgbaMatch[1], 10);
+  const g = parseInt(rgbaMatch[2], 10);
+  const b = parseInt(rgbaMatch[3], 10);
+
+  return r >= NEAR_WHITE_MIN_CHANNEL && g >= NEAR_WHITE_MIN_CHANNEL && b >= NEAR_WHITE_MIN_CHANNEL;
+}
+
+/**
+ * Check whether an element is a pure wrapper with no semantic value
+ * (no attributes and no text content, or just whitespace).
+ */
+function isEmptyWrapper(el: HTMLElement): boolean {
+  if (el.attributes.length > 0) {
+    return false;
+  }
+
+  const text = (el.textContent ?? '').replace(/[\s\u00A0]/g, '');
+
+  return text.length === 0;
+}
+
+/**
+ * Extract `background-color` from an element's style attribute.
+ *
+ * Handles both `background-color:` and `background:` (shorthand) properties.
+ * Uses the element's computed style property first, falling back to manual
+ * parsing of the style attribute for shorthand notation.
+ */
+function getBackgroundColor(el: HTMLElement): string {
+  // Try the direct property first
+  if (el.style.backgroundColor) {
+    return el.style.backgroundColor;
+  }
+
+  // Fall back to parsing the style attribute for shorthand `background:`
+  const styleAttr = el.getAttribute('style') ?? '';
+  const match = styleAttr.match(/background:\s*([^;]+)/i);
+
+  if (match) {
+    const value = match[1].trim();
+    // Only return color values, not url() or other background sub-properties
+    const colorMatch = value.match(/^(rgb[a]?\([^)]+\)|#[0-9a-fA-F]{3,8}|[a-z]+)$/i);
+
+    if (colorMatch) {
+      return colorMatch[1];
+    }
+  }
+
+  return '';
+}
+
+/**
+ * Convert `<p>` boundaries to `<br>` line breaks inside table cells.
+ *
+ * Only targets `<td>` and `<th>` — top-level `<p>` tags are left intact.
+ */
+function convertTableCellParagraphs(wrapper: HTMLElement): void {
+  const doc = wrapper.ownerDocument;
+
+  for (const cell of Array.from(wrapper.querySelectorAll('td, th'))) {
+    const paragraphs = cell.querySelectorAll('p');
+
+    if (paragraphs.length === 0) {
+      continue;
+    }
+
+    for (const p of Array.from(paragraphs)) {
+      if (p.innerHTML.trim() === '' || p.innerHTML.trim() === '&nbsp;') {
+        p.remove();
+        continue;
+      }
+
+      const fragment = doc.createDocumentFragment();
+
+      fragment.append(...Array.from(p.childNodes));
+      fragment.append(doc.createElement('br'));
+      p.replaceWith(fragment);
+    }
+
+    stripTrailingBreaks(cell);
+  }
+}
+
+/**
+ * Remove paragraphs whose only content is non-breaking spaces or whitespace.
+ */
+function stripNbspOnlyParagraphs(wrapper: HTMLElement): void {
+  for (const p of Array.from(wrapper.querySelectorAll('p'))) {
+    // Skip paragraphs inside table cells — those are handled by convertTableCellParagraphs
+    if (p.closest('td') || p.closest('th')) {
+      continue;
+    }
+
+    const textContent = p.textContent ?? '';
+    const stripped = textContent.replace(/[\s\u00A0]/g, '');
+
+    if (stripped.length === 0) {
+      p.remove();
+    }
+  }
+}
+
+/**
+ * Convert `<del>` and `<strike>` elements to `<s>`.
+ */
+function convertStrikethroughTags(wrapper: HTMLElement): void {
+  const doc = wrapper.ownerDocument;
+
+  for (const el of Array.from(wrapper.querySelectorAll('del, strike'))) {
+    const replacement = doc.createElement('s');
+
+    replacement.append(...Array.from(el.childNodes));
+    el.replaceWith(replacement);
+  }
+}
+
+/**
+ * Bullet characters that indicate a pseudo-list paragraph.
+ *
+ * Matches: `\u2022` (bullet), `\u00B7` (middle dot), or `- ` (hyphen + space).
+ */
+const BULLET_PREFIX = /^[\u2022\u00B7][\s\u00A0]*|^-\s/;
+
+/**
+ * Convert `<p>• text</p>` pseudo-lists into proper `<ul><li>` markup.
+ *
+ * Groups consecutive bullet paragraphs into a single `<ul>` and strips
+ * the bullet prefix. Only processes direct children of the wrapper.
+ */
+function convertBulletParagraphsToLists(wrapper: HTMLElement): void {
+  const doc = wrapper.ownerDocument;
+  const children = Array.from(wrapper.childNodes);
+  let currentList: HTMLUListElement | null = null;
+
+  for (const child of children) {
+    if (child.nodeType !== Node.ELEMENT_NODE) {
+      continue;
+    }
+
+    const el = child as HTMLElement;
+
+    if (el.tagName !== 'P') {
+      currentList = null;
+      continue;
+    }
+
+    const textContent = el.textContent ?? '';
+
+    if (!BULLET_PREFIX.test(textContent)) {
+      currentList = null;
+      continue;
+    }
+
+    if (!currentList) {
+      currentList = doc.createElement('ul');
+      el.before(currentList);
+    }
+
+    const li = doc.createElement('li');
+
+    // Strip the bullet character and any leading nbsp/whitespace from
+    // the first text node, preserving any inline HTML that follows.
+    const firstTextNode = findFirstTextNode(el);
+
+    if (firstTextNode) {
+      firstTextNode.textContent = (firstTextNode.textContent ?? '').replace(BULLET_PREFIX, '');
+    }
+
+    li.append(...Array.from(el.childNodes));
+    currentList.appendChild(li);
+    el.remove();
+  }
+}
+
+/**
+ * Remove trailing `<br>` elements and whitespace-only text nodes from the end
+ * of an element.
+ */
+function stripTrailingBreaks(element: Element): void {
+  let node = element.lastChild;
+
+  while (node) {
+    if (node.nodeType === Node.ELEMENT_NODE && (node as Element).tagName === 'BR') {
+      const prev = node.previousSibling;
+
+      node.remove();
+      node = prev;
+    } else if (node.nodeType === Node.TEXT_NODE && node.textContent?.trim() === '') {
+      const prev = node.previousSibling;
+
+      node.remove();
+      node = prev;
+    } else {
+      break;
+    }
+  }
+}
+
+/**
+ * Walk the DOM tree depth-first to find the first Text node.
+ */
+function findFirstTextNode(node: Node): Text | null {
+  if (node.nodeType === Node.TEXT_NODE) {
+    return node as Text;
+  }
+
+  for (const child of Array.from(node.childNodes)) {
+    const found = findFirstTextNode(child);
+
+    if (found) {
+      return found;
+    }
+  }
+
+  return null;
+}

package/src/cli/commands/convert-html/sanitizer.ts

@@ -0,0 +1,94 @@
+/**
+ * Whitelist of allowed tags and their allowed attributes.
+ * Tags not in this list are unwrapped (children preserved, tag removed).
+ */
+const ALLOWED: Record<string, Set<string> | true> = {
+  // Inline
+  B: true,
+  STRONG: true,
+  I: true,
+  EM: true,
+  A: new Set(['href']),
+  S: true,
+  U: true,
+  CODE: true,
+  MARK: new Set(['style']),
+  BR: true,
+  // Block
+  P: true,
+  H1: true, H2: true, H3: true, H4: true, H5: true, H6: true,
+  UL: true,
+  OL: true,
+  LI: new Set(['aria-level']),
+  TABLE: true, THEAD: true, TBODY: true, TR: true,
+  TD: new Set(['style']),
+  TH: new Set(['style']),
+  BLOCKQUOTE: true,
+  PRE: true,
+  HR: true,
+  ASIDE: new Set(['style']),
+  DETAILS: true,
+  SUMMARY: true,
+  IMG: new Set(['src', 'style']),
+};
+
+/**
+ * Sanitize DOM tree in place. Removes disallowed tags (unwrapping children)
+ * and strips disallowed attributes from allowed tags.
+ */
+export function sanitize(wrapper: HTMLElement): void {
+  sanitizeNode(wrapper);
+}
+
+function sanitizeNode(node: Node): void {
+  // Use a live-like approach: collect children, then process each.
+  // When a child is unwrapped its grandchildren are inserted in place and
+  // must themselves be processed as children of the same parent.
+  const queue = Array.from(node.childNodes);
+
+  for (const child of queue) {
+    if (child.nodeType !== child.ELEMENT_NODE) {
+      continue;
+    }
+
+    const el = child as HTMLElement;
+    const tag = el.tagName;
+    const allowedAttrs = ALLOWED[tag];
+
+    if (allowedAttrs === undefined) {
+      // Unwrap: move children to the parent, then remove this element.
+      const grandchildren = Array.from(el.childNodes);
+
+      for (const gc of grandchildren) {
+        el.before(gc);
+      }
+
+      el.remove();
+
+      // Push the moved grandchildren onto the queue so they are evaluated
+      // for unwrapping / attribute-stripping in the same parent context.
+      for (const gc of grandchildren) {
+        if (gc.nodeType === gc.ELEMENT_NODE) {
+          queue.push(gc);
+        }
+      }
+    } else {
+      // Strip disallowed attributes.
+      if (allowedAttrs !== true) {
+        for (const attr of Array.from(el.attributes)) {
+          if (!allowedAttrs.has(attr.name)) {
+            el.removeAttribute(attr.name);
+          }
+        }
+      } else {
+        // true means no attributes allowed — strip all.
+        for (const attr of Array.from(el.attributes)) {
+          el.removeAttribute(attr.name);
+        }
+      }
+
+      // Recurse into children.
+      sanitizeNode(el);
+    }
+  }
+}

package/src/cli/commands/convert-html/standalone.ts

@@ -0,0 +1,20 @@
+import * as fs from 'node:fs';
+import { JSDOM } from 'jsdom';
+
+// Provide DOM globals for convertHtml and block-builder
+const dom = new JSDOM('');
+globalThis.DOMParser = dom.window.DOMParser;
+globalThis.Node = dom.window.Node;
+
+async function main(): Promise<void> {
+  const { convertHtml } = await import('./index');
+  const html = fs.readFileSync('/dev/stdin', 'utf-8');
+  const json = convertHtml(html);
+
+  process.stdout.write(json);
+}
+
+main().catch((err) => {
+  process.stderr.write(`Error: ${(err as Error).message}\n`);
+  process.exitCode = 1;
+});

package/src/cli/commands/convert-html/types.ts

@@ -0,0 +1,15 @@
+export interface OutputBlockData {
+  id: string;
+  type: string;
+  data: Record<string, unknown>;
+  parent?: string;
+  content?: string[];
+  stretched?: number | null;
+  key?: string | null;
+  width?: number | null;
+}
+
+export interface OutputData {
+  version: string;
+  blocks: OutputBlockData[];
+}

package/src/cli/index.ts

@@ -1,17 +1,20 @@
 import { getMigrationDoc } from './commands/migration';
 import { writeOutput } from './utils/output';
 
-const HELP_TEXT = `Usage: blok [options]
+const HELP_TEXT = `Usage: blok-cli [options]
 
 Options:
+  --convert-html       Convert legacy HTML from stdin to Blok JSON (stdout)
   --migration          Output the EditorJS to Blok migration guide (LLM-friendly)
   --output <file>      Write output to a file instead of stdout
   --help               Show this help message
 
 Examples:
-  npx @jackuait/blok --migration
-  npx @jackuait/blok --migration | pbcopy
-  npx @jackuait/blok --migration --output migration-guide.md
+  npx @jackuait/blok-cli --convert-html < article.html
+  npx @jackuait/blok-cli --convert-html < article.html --output article.json
+  npx @jackuait/blok-cli --migration
+  npx @jackuait/blok-cli --migration | pbcopy
+  npx @jackuait/blok-cli --migration --output migration-guide.md
 `;
 
 const parseArgs = (argv: string[]): { command: string | null; output?: string } => {
@@ -19,6 +22,13 @@ const parseArgs = (argv: string[]): { command: string | null; output?: string }
     return { command: 'help' };
   }
 
+  if (argv.includes('--convert-html')) {
+    const outputIndex = argv.indexOf('--output');
+    const output = outputIndex !== -1 ? argv[outputIndex + 1] : undefined;
+
+    return { command: 'convert-html', output };
+  }
+
   if (argv.includes('--migration')) {
     const outputIndex = argv.indexOf('--output');
     const output = outputIndex !== -1 ? argv[outputIndex + 1] : undefined;
@@ -29,10 +39,25 @@ const parseArgs = (argv: string[]): { command: string | null; output?: string }
   return { command: null };
 };
 
-export const run = (argv: string[], version: string): void => {
+export const run = async (argv: string[], version: string): Promise<void> => {
   const { command, output } = parseArgs(argv);
 
   switch (command) {
+    case 'convert-html': {
+      const jsdom = await import('jsdom') as { JSDOM: new (html: string) => { window: typeof globalThis } };
+      const dom = new jsdom.JSDOM('');
+
+      globalThis.DOMParser = dom.window.DOMParser;
+      globalThis.Node = dom.window.Node;
+
+      const { convertHtml } = await import('./commands/convert-html/index');
+      const fs = await import('node:fs');
+      const html = fs.readFileSync('/dev/stdin', 'utf-8');
+      const json = convertHtml(html);
+
+      writeOutput(json, output);
+      break;
+    }
     case 'migration': {
       const content = getMigrationDoc(version);
 

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

@@ -505,6 +505,22 @@ export class Toolbar extends Module<ToolbarNodes> {
 
     this.open();
 
+    /**
+     * For blocks with interactive elements at the left edge (toggle arrows,
+     * callout emoji buttons), disable pointer-events on the actions
+     * container so clicks pass through to the block content.
+     * Must run after open() which sets pointer-events: auto on actions.
+     */
+    const isToggleHeader = targetBlock.name === 'header'
+      && targetBlock.holder.querySelector('[data-blok-toggle-arrow]') !== null;
+    const hasLeftEdgeInteraction = targetBlock.name === 'callout'
+      || targetBlock.name === 'toggle'
+      || isToggleHeader;
+
+    if (hasLeftEdgeInteraction && this.nodes.actions) {
+      this.nodes.actions.style.pointerEvents = 'none';
+    }
+
     /**
      * Sync toolbar content wrapper's margin with the block content element
      * so toolbar buttons align with the block content edge, even when
@@ -514,8 +530,9 @@ export class Toolbar extends Module<ToolbarNodes> {
      */
     if (blockContentElement && this.nodes.content) {
       const blockMarginLeft = parseFloat(getComputedStyle(blockContentElement).marginLeft) || 0;
+      const actionsWidth = this.nodes.actions?.offsetWidth ?? 0;
 
-      this.nodes.content.style.marginLeft = `${blockMarginLeft}px`;
+      this.nodes.content.style.marginLeft = `${Math.max(blockMarginLeft, actionsWidth)}px`;
     }
   }
 
@@ -641,8 +658,9 @@ export class Toolbar extends Module<ToolbarNodes> {
      */
     if (blockContentElement && this.nodes.content) {
       const blockMarginLeft = parseFloat(getComputedStyle(blockContentElement).marginLeft) || 0;
+      const actionsWidth = this.nodes.actions?.offsetWidth ?? 0;
 
-      this.nodes.content.style.marginLeft = `${blockMarginLeft}px`;
+      this.nodes.content.style.marginLeft = `${Math.max(blockMarginLeft, actionsWidth)}px`;
     }
   }
 

package/src/components/modules/uiControllers/controllers/blockHover.ts

@@ -34,6 +34,13 @@ export class BlockHoverController extends Controller {
    */
   private static readonly HOVER_COOLDOWN_MS = 50;
 
+  /**
+   * Maximum horizontal distance from content edges for extended hover zone.
+   * When cursor is within this distance of the content area, nearest-block
+   * detection activates. Beyond this distance, no hover event is emitted.
+   */
+  private static readonly HOVER_ZONE_SIZE = 100;
+
   constructor(options: {
     config: Controller['config'];
     eventsDispatcher: Controller['eventsDispatcher'];
@@ -104,9 +111,10 @@ export class BlockHoverController extends Controller {
 
       /**
        * If no block element found directly, find the nearest block by Y distance
+       * but only if the cursor is within the extended hover zone (100px from content edges).
        */
       if (!hoveredBlockElement) {
-        this.emitNearestBlockHovered(event.clientY);
+        this.emitNearestBlockHoveredInZone(event.clientX, event.clientY);
 
         return;
       }
@@ -169,6 +177,41 @@ export class BlockHoverController extends Controller {
     });
   }
 
+  /**
+   * Emits a BlockHovered event for the nearest block, but only if the cursor
+   * is within the extended hover zone (HOVER_ZONE_SIZE px from content edges).
+   * @param clientX - Cursor X position
+   * @param clientY - Cursor Y position
+   */
+  private emitNearestBlockHoveredInZone(clientX: number, clientY: number): void {
+    const blocks = this.Blok.BlockManager.blocks;
+    const topLevelBlocks = blocks.filter(block =>
+      block.holder.closest('[data-blok-table-cell-blocks], [data-blok-toggle-children]') === null
+    );
+
+    if (topLevelBlocks.length === 0) {
+      return;
+    }
+
+    const contentEl = topLevelBlocks[0].holder.querySelector<HTMLElement>('[data-blok-element-content]');
+
+    if (!contentEl) {
+      this.emitNearestBlockHovered(clientY);
+
+      return;
+    }
+
+    const contentRect = contentEl.getBoundingClientRect();
+    const distLeft = Math.abs(clientX - contentRect.left);
+    const distRight = Math.abs(clientX - contentRect.right);
+    const withinZone = distLeft <= BlockHoverController.HOVER_ZONE_SIZE
+      || distRight <= BlockHoverController.HOVER_ZONE_SIZE;
+
+    if (withinZone) {
+      this.emitNearestBlockHovered(clientY);
+    }
+  }
+
   /**
    * Finds the nearest block by vertical distance to cursor position.
    * Returns the block whose vertical center is closest to the cursor Y position.