@jackuait/blok 0.10.0-beta.9 → 0.10.0

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

@@ -0,0 +1,422 @@
+/**
+ * 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.
+    unwrapBareDivs(aside);
+
+    // Strip trailing <br> inside paragraphs — the paste handler splits
+    // content at <br> boundaries, so a trailing one creates an empty block.
+    stripTrailingBrInParagraphs(aside);
+
+    div.replaceWith(aside);
+  }
+}
+
+/**
+ * Repeatedly unwrap non-semantic `<div>` wrappers (no style or class) that are
+ * direct children of the given element, replacing them with their child nodes.
+ */
+function unwrapBareDivs(parent: HTMLElement): void {
+  for (;;) {
+    const bareDivs = Array.from(parent.querySelectorAll<HTMLElement>(':scope > div'))
+      .filter((d) => !d.getAttribute('style') && !d.getAttribute('class'));
+
+    if (bareDivs.length === 0) {
+      break;
+    }
+
+    for (const child of bareDivs) {
+      child.replaceWith(...Array.from(child.childNodes));
+    }
+  }
+}
+
+/**
+ * Remove trailing `<br>` elements from paragraphs inside the given element.
+ */
+function stripTrailingBrInParagraphs(parent: HTMLElement): void {
+  for (const p of Array.from(parent.querySelectorAll('p'))) {
+    const lastChild = p.lastElementChild;
+
+    if (lastChild?.tagName === 'BR') {
+      lastChild.remove();
+    }
+  }
+}
+
+/**
+ * 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)) {
+      continue;
+    }
+
+    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 {
+  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)) {
+      replaceParagraphWithBr(p);
+    }
+
+    stripTrailingBreaks(cell);
+  }
+}
+
+/**
+ * Replace a `<p>` element with its child nodes followed by a `<br>`,
+ * or remove it entirely if it is empty / nbsp-only.
+ */
+function replaceParagraphWithBr(p: HTMLParagraphElement): void {
+  if (p.innerHTML.trim() === '' || p.innerHTML.trim() === '&nbsp;') {
+    p.remove();
+
+    return;
+  }
+
+  const doc = p.ownerDocument;
+  const fragment = doc.createDocumentFragment();
+
+  fragment.append(...Array.from(p.childNodes));
+  fragment.append(doc.createElement('br'));
+  p.replaceWith(fragment);
+}
+
+/**
+ * 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;
+
+  // Collect runs of consecutive bullet paragraphs. Each run is a group
+  // that will become a single <ul>.
+  const groups = collectBulletGroups(wrapper);
+
+  for (const group of groups) {
+    const ul = doc.createElement('ul');
+
+    group[0].before(ul);
+
+    for (const p of group) {
+      convertBulletParagraphToListItem(p, ul);
+    }
+  }
+}
+
+/**
+ * Strip the bullet prefix from a paragraph and append its content as
+ * a `<li>` to the given list.
+ */
+function convertBulletParagraphToListItem(p: HTMLParagraphElement, ul: HTMLUListElement): void {
+  const li = p.ownerDocument.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(p);
+
+  if (firstTextNode) {
+    firstTextNode.textContent = (firstTextNode.textContent ?? '').replace(BULLET_PREFIX, '');
+  }
+
+  li.append(...Array.from(p.childNodes));
+  ul.appendChild(li);
+  p.remove();
+}
+
+/**
+ * Walk direct children of an element and return groups of consecutive `<p>`
+ * elements whose text starts with a bullet character.
+ */
+function collectBulletGroups(wrapper: HTMLElement): HTMLParagraphElement[][] {
+  const groups: HTMLParagraphElement[][] = [];
+  const children = Array.from(wrapper.childNodes);
+
+  for (const child of children) {
+    if (child.nodeType !== Node.ELEMENT_NODE) {
+      continue;
+    }
+
+    const el = child as HTMLElement;
+    const isBulletParagraph = el.tagName === 'P' && BULLET_PREFIX.test(el.textContent ?? '');
+
+    if (!isBulletParagraph) {
+      continue;
+    }
+
+    const lastGroup = groups[groups.length - 1];
+    const previousSibling = findPreviousElementSibling(el);
+    const belongsToCurrentGroup = lastGroup
+      && previousSibling !== null
+      && lastGroup[lastGroup.length - 1] === previousSibling;
+
+    if (belongsToCurrentGroup) {
+      lastGroup.push(el as HTMLParagraphElement);
+    } else {
+      groups.push([el as HTMLParagraphElement]);
+    }
+  }
+
+  return groups;
+}
+
+/**
+ * Find the previous sibling that is an element, skipping non-element nodes.
+ */
+function findPreviousElementSibling(el: HTMLElement): Element | null {
+  const prev = el.previousSibling;
+
+  if (!prev) {
+    return null;
+  }
+
+  if (prev.nodeType === Node.ELEMENT_NODE) {
+    return prev as Element;
+  }
+
+  return null;
+}
+
+/**
+ * Remove trailing `<br>` elements and whitespace-only text nodes from the end
+ * of an element.
+ */
+function stripTrailingBreaks(element: Element): void {
+  for (;;) {
+    const node = element.lastChild;
+
+    if (!node) {
+      break;
+    }
+
+    const isBr = node.nodeType === Node.ELEMENT_NODE && (node as Element).tagName === 'BR';
+    const isBlankText = node.nodeType === Node.TEXT_NODE && node.textContent?.trim() === '';
+
+    if (!isBr && !isBlankText) {
+      break;
+    }
+
+    node.remove();
+  }
+}
+
+/**
+ * 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,93 @@
+/**
+ * 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);
+}
+
+/**
+ * Unwrap a disallowed element: move its children before it, remove it,
+ * and return any element children so they can be re-queued for processing.
+ */
+function unwrapElement(el: HTMLElement): ChildNode[] {
+  const grandchildren = Array.from(el.childNodes);
+
+  for (const gc of grandchildren) {
+    el.before(gc);
+  }
+  el.remove();
+
+  return grandchildren.filter((gc) => gc.nodeType === gc.ELEMENT_NODE);
+}
+
+/**
+ * Strip attributes from an element that are not in the allowed set.
+ * When `allowedAttrs` is `true`, all attributes are removed.
+ */
+function stripAttributes(el: HTMLElement, allowedAttrs: Set<string> | true): void {
+  for (const attr of Array.from(el.attributes)) {
+    if (allowedAttrs === true || !allowedAttrs.has(attr.name)) {
+      el.removeAttribute(attr.name);
+    }
+  }
+}
+
+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 allowedAttrs = ALLOWED[el.tagName];
+
+    if (allowedAttrs === undefined) {
+      // Unwrap disallowed tag and re-queue its element children.
+      queue.push(...unwrapElement(el));
+      continue;
+    }
+
+    stripAttributes(el, allowedAttrs);
+    sanitizeNode(el);
+  }
+}

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,23 @@
 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)
+  --convert-gdocs      Convert Google Docs 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 --convert-gdocs < gdocs-export.html
+  npx @jackuait/blok-cli --convert-gdocs < gdocs-export.html --output doc.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 +25,20 @@ 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('--convert-gdocs')) {
+    const outputIndex = argv.indexOf('--output');
+    const output = outputIndex !== -1 ? argv[outputIndex + 1] : undefined;
+
+    return { command: 'convert-gdocs', output };
+  }
+
   if (argv.includes('--migration')) {
     const outputIndex = argv.indexOf('--output');
     const output = outputIndex !== -1 ? argv[outputIndex + 1] : undefined;
@@ -29,10 +49,41 @@ 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');
+      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 'convert-gdocs': {
+      const jsdom = await import('jsdom');
+      const dom = new jsdom.JSDOM('');
+
+      globalThis.DOMParser = dom.window.DOMParser;
+      globalThis.Node = dom.window.Node;
+      (globalThis as Record<string, unknown>).document = dom.window.document;
+
+      const { convertGdocs } = await import('./commands/convert-gdocs/index');
+      const fs = await import('node:fs');
+      const html = fs.readFileSync('/dev/stdin', 'utf-8');
+      const json = convertGdocs(html);
+
+      writeOutput(json, output);
+      break;
+    }
     case 'migration': {
       const content = getMigrationDoc(version);
 

package/src/components/block/index.ts

@@ -202,6 +202,11 @@ export class Block extends EventsDispatcher<BlockEvents> {
    */
   private readonly blockAPI: BlockAPIInterface;
 
+  /**
+   * Current read-only state of the block
+   */
+  private readOnly: boolean;
+
   /**
    * Cleanup function for draggable behavior
    */
@@ -261,6 +266,7 @@ export class Block extends EventsDispatcher<BlockEvents> {
     this.blokEventBus = eventBus || null;
     this.blockAPI = new BlockAPI(this);
 
+    this.readOnly = readOnly;
     this.tool = tool;
     this.toolInstance = tool.create(data, this.blockAPI, readOnly);
     this.tunes = tool.tunes;
@@ -324,18 +330,21 @@ export class Block extends EventsDispatcher<BlockEvents> {
     );
 
     // Bind block mutation watchers and input events
+    // - Skip entirely when block is in read-only mode (no mutations to track, no input events)
     // - Immediately if bindMutationWatchersImmediately is true (for user-created blocks)
     // - Deferred via requestIdleCallback otherwise (for initial load optimization)
-    const bindEvents = (): void => {
-      this.mutationHandler.watch();
-      this.inputManager.addInputEvents();
-      this.toggleInputsEmptyMark();
-    };
-
-    if (bindMutationWatchersImmediately) {
-      bindEvents();
-    } else {
-      window.requestIdleCallback(bindEvents);
+    if (!readOnly) {
+      const bindEvents = (): void => {
+        this.mutationHandler.watch();
+        this.inputManager.addInputEvents();
+        this.toggleInputsEmptyMark();
+      };
+
+      if (bindMutationWatchersImmediately) {
+        bindEvents();
+      } else {
+        window.requestIdleCallback(bindEvents);
+      }
     }
   }
 
@@ -507,6 +516,31 @@ export class Block extends EventsDispatcher<BlockEvents> {
     }
   }
 
+  /**
+   * Toggle read-only mode in place without destroying the block.
+   * Updates internal managers and notifies the tool if it supports in-place toggle.
+   * @param state - new read-only state
+   */
+  public setReadOnly(state: boolean): void {
+    if (this.readOnly === state) {
+      return;
+    }
+
+    this.readOnly = state;
+
+    if (state) {
+      this.inputManager.removeInputEvents();
+      this.mutationHandler.unwatch();
+    } else {
+      this.inputManager.addInputEvents();
+      this.mutationHandler.watch();
+    }
+
+    if (typeof (this.toolInstance as unknown as { setReadOnly?: unknown }).setReadOnly === 'function') {
+      (this.toolInstance as unknown as { setReadOnly: (s: boolean) => void }).setReadOnly(state);
+    }
+  }
+
   /**
    * Tool could specify several entries to be displayed at the Toolbox (for example, "Heading 1", "Heading 2", "Heading 3")
    * This method returns the entry that is related to the Block (depended on the Block data)