@jackuait/blok 0.10.0-beta.9 → 0.10.1

package/src/tools/header/index.ts

@@ -111,6 +111,12 @@ export class Header implements BlockTool {
    */
   private readOnly: boolean;
 
+  /**
+   * Cleanup function for the placeholder, returned by setupPlaceholder().
+   * Stored so we can tear down the placeholder when entering read-only mode.
+   */
+  private placeholderCleanup: (() => void) | null = null;
+
   /**
    * Tool's settings passed from Editor
    */
@@ -302,6 +308,45 @@ export class Header implements BlockTool {
     this._element.removeEventListener('keydown', this.handleKeyDown);
   }
 
+  /**
+   * Toggle read-only mode in-place without re-rendering the DOM element.
+   * Manages contentEditable, keydown listener (for toggle headings),
+   * placeholder setup/teardown, and body placeholder click handler.
+   *
+   * @param state - true to enter read-only mode, false to exit
+   */
+  public setReadOnly(state: boolean): void {
+    if (!this._element) {
+      return;
+    }
+
+    this.readOnly = state;
+
+    if (state) {
+      this._element.contentEditable = 'false';
+
+      if (this._data.isToggleable) {
+        this._element.removeEventListener('keydown', this.handleKeyDown);
+      }
+
+      if (this.placeholderCleanup) {
+        this.placeholderCleanup();
+        this.placeholderCleanup = null;
+      }
+    } else {
+      this._element.contentEditable = 'true';
+
+      if (this._data.isToggleable) {
+        this._element.addEventListener('keydown', this.handleKeyDown);
+      }
+
+      const translatedName = this.api.i18n.t(this.currentLevel.nameKey);
+      const placeholderText = this.resolvePlaceholderText(translatedName);
+
+      this.placeholderCleanup = setupPlaceholder(this._element, placeholderText);
+    }
+  }
+
   /**
    * Expand the toggle heading (no-op if not toggleable or already expanded).
    * Can be called externally via block.call('expand').
@@ -679,7 +724,7 @@ export class Header implements BlockTool {
     const placeholderText = this.resolvePlaceholderText(translatedName);
 
     if (!this.readOnly) {
-      setupPlaceholder(tag, placeholderText);
+      this.placeholderCleanup = setupPlaceholder(tag, placeholderText);
     } else {
       tag.setAttribute('data-placeholder', placeholderText);
     }
@@ -750,6 +795,7 @@ export class Header implements BlockTool {
     // pl-8 (32px) matches the heading's left padding so children align with the title text start.
     childContainer.className = 'pl-8';
     childContainer.setAttribute(TOGGLE_ATTR.toggleChildren, '');
+    childContainer.setAttribute(DATA_ATTR.nestedBlocks, '');
     // Block DOM mutations inside the children container from triggering the header tool's
     // didMutated → syncBlockDataToYjs path (same rationale as the toggle list tool).
     childContainer.setAttribute('data-blok-mutation-free', 'true');

package/src/tools/list/dom-builder.ts

@@ -111,7 +111,9 @@ export const buildListItem = (context: DOMBuilderContext): BuildResult => {
   // Extract element references for the result
   const markerElement = itemContent.querySelector<HTMLElement>('[data-list-marker]');
   const checkboxElement = itemContent.querySelector<HTMLInputElement>('input[type="checkbox"]');
-  const contentElement = itemContent.querySelector<HTMLElement>('[contenteditable]');
+  const contentElement = data.style === 'checklist'
+    ? itemContent.querySelector<HTMLElement>(`[data-blok-testid="${LIST_TEST_IDS.checklistContent}"]`)
+    : itemContent.querySelector<HTMLElement>(`[data-blok-testid="${LIST_TEST_IDS.contentContainer}"]`);
 
   return {
     wrapper,

package/src/tools/list/index.ts

@@ -52,6 +52,8 @@ export class ListItem implements BlockTool {
   private depthValidator: ListDepthValidator;
   private markerCalculator: ListMarkerCalculator;
   private markerManager: OrderedMarkerManager | null;
+  private placeholderCleanup: (() => void) | null = null;
+  private boundHandleKeyDown: ((event: KeyboardEvent) => void) | null = null;
 
   private blockId?: string;
 
@@ -120,16 +122,24 @@ export class ListItem implements BlockTool {
     if (this.readOnly) {
       return;
     }
-    setupPlaceholder(element, this.placeholder);
+    this.placeholderCleanup = setupPlaceholder(element, this.placeholder);
   }
 
   public render(): HTMLElement {
+    if (this._element) {
+      return this._element;
+    }
+
     const blockIndex = this.blockId
       ? this.api.blocks.getBlockIndex(this.blockId) ?? this.api.blocks.getCurrentBlockIndex()
       : this.api.blocks.getCurrentBlockIndex();
     const depth = this._data.depth ?? 0;
     const markerDepth = this.markerCalculator.getVisualDepth(blockIndex, depth);
 
+    if (!this.boundHandleKeyDown) {
+      this.boundHandleKeyDown = this.handleKeyDown.bind(this);
+    }
+
     this._element = renderListItem({
       data: this._data,
       readOnly: this.readOnly,
@@ -145,12 +155,54 @@ export class ListItem implements BlockTool {
           content.classList.toggle('opacity-60', checked);
         }
       },
-      keydownHandler: this.readOnly ? undefined : this.handleKeyDown.bind(this),
+      keydownHandler: this.readOnly ? undefined : this.boundHandleKeyDown,
     });
 
     return this._element;
   }
 
+  public setReadOnly(state: boolean): void {
+    if (!this._element) {
+      return;
+    }
+
+    this.readOnly = state;
+
+    const content = this.getContentElement();
+
+    // Toggle contentEditable on content container
+    if (content) {
+      content.contentEditable = state ? 'false' : 'true';
+    }
+
+    // Toggle checkbox disabled state for checklists
+    const checkbox = this._element.querySelector<HTMLInputElement>('input[type="checkbox"]');
+
+    if (checkbox) {
+      checkbox.disabled = state;
+    }
+
+    // Toggle keydown handler and placeholder
+    if (state) {
+      if (this.boundHandleKeyDown) {
+        this._element.removeEventListener('keydown', this.boundHandleKeyDown);
+      }
+
+      if (this.placeholderCleanup) {
+        this.placeholderCleanup();
+        this.placeholderCleanup = null;
+      }
+    } else {
+      if (this.boundHandleKeyDown) {
+        this._element.addEventListener('keydown', this.boundHandleKeyDown);
+      }
+
+      if (content) {
+        this.placeholderCleanup = setupPlaceholder(content, this.placeholder);
+      }
+    }
+  }
+
   public rendered(): void {
     this.updateMarkersAfterPositionChange();
   }
@@ -408,7 +460,7 @@ export class ListItem implements BlockTool {
           content.classList.toggle('opacity-60', checked);
         }
       },
-      keydownHandler: this.readOnly ? undefined : this.handleKeyDown.bind(this),
+      keydownHandler: this.readOnly ? undefined : this.boundHandleKeyDown ?? undefined,
     });
 
     if (newElement) {

package/src/tools/list/list-helpers.ts

@@ -19,8 +19,8 @@ export const getContentElement = (
   if (!element) return null;
 
   if (style === 'checklist') {
-    const contentEditable = element.querySelector('[contenteditable]');
-    return contentEditable instanceof HTMLElement ? contentEditable : null;
+    const checklistContent = element.querySelector('[data-blok-testid="list-checklist-content"]');
+    return checklistContent instanceof HTMLElement ? checklistContent : null;
   }
 
   const contentContainer = element.querySelector('[data-blok-testid="list-content-container"]');

package/src/tools/nested-blocks.ts

@@ -0,0 +1,25 @@
+import { DATA_ATTR } from '../components/constants/data-attributes';
+
+/**
+ * Mount child block holders into a container, skipping children that are
+ * already in place or claimed by another nested-blocks container.
+ *
+ * Used by toggle, header, and callout tools to reconcile child holders
+ * during the `rendered()` lifecycle hook.
+ */
+export const mountChildBlocks = (
+  container: HTMLElement,
+  children: { holder: HTMLElement }[],
+): void => {
+  for (const child of children) {
+    if (child.holder.parentElement === container) {
+      continue;
+    }
+
+    if (child.holder.closest(`[${DATA_ATTR.nestedBlocks}]`)) {
+      continue;
+    }
+
+    container.appendChild(child.holder);
+  }
+};

package/src/tools/paragraph/index.ts

@@ -19,7 +19,7 @@ import type {
 import { DATA_ATTR } from '../../components/constants';
 import { IconText } from '../../components/icons';
 import { stripFakeBackgroundElements } from '../../components/utils';
-import { PLACEHOLDER_EMPTY_EDITOR_CLASSES, PLACEHOLDER_FOCUS_ONLY_CLASSES, setupPlaceholder } from '../../components/utils/placeholder';
+import { isContentEmpty, PLACEHOLDER_EMPTY_EDITOR_CLASSES, PLACEHOLDER_FOCUS_ONLY_CLASSES, setupPlaceholder } from '../../components/utils/placeholder';
 import { twMerge } from '../../components/utils/tw';
 
 /**
@@ -117,6 +117,11 @@ export class Paragraph implements BlockTool {
    */
   private readOnly: boolean;
 
+  /**
+   * Cleanup function for placeholder behavior, returned by setupPlaceholder
+   */
+  private placeholderCleanup: (() => void) | null = null;
+
   /**
    * Placeholder for Paragraph Tool
    */
@@ -157,9 +162,7 @@ export class Paragraph implements BlockTool {
     this.api = api;
     this.readOnly = readOnly;
 
-    if (!this.readOnly) {
-      this.onKeyUp = this.onKeyUp.bind(this);
-    }
+    this.onKeyUp = this.onKeyUp.bind(this);
 
     this._placeholder = config?.placeholder ?? Paragraph.DEFAULT_PLACEHOLDER;
     this._data = data ?? { text: '' };
@@ -263,7 +266,7 @@ export class Paragraph implements BlockTool {
     if (!this.readOnly) {
       div.contentEditable = 'true';
       div.addEventListener('keyup', this.onKeyUp);
-      setupPlaceholder(div, this.api.i18n.t(this._placeholder), 'data-blok-placeholder-active');
+      this.placeholderCleanup = setupPlaceholder(div, this.api.i18n.t(this._placeholder), 'data-blok-placeholder-active');
     }
 
     return div;
@@ -275,11 +278,49 @@ export class Paragraph implements BlockTool {
    * @returns HTMLDivElement
    */
   public render(): HTMLDivElement {
-    this._element = this.drawView();
+    if (!this._element) {
+      this._element = this.drawView();
+    }
 
     return this._element;
   }
 
+  /**
+   * Toggle read-only mode in-place without re-rendering the DOM element.
+   * Manages contentEditable, keyup listener, placeholder, and empty-content <br>.
+   *
+   * @param state - true to enter read-only mode, false to exit
+   */
+  public setReadOnly(state: boolean): void {
+    if (!this._element) {
+      return;
+    }
+
+    this.readOnly = state;
+
+    if (state) {
+      this._element.contentEditable = 'false';
+      this._element.removeEventListener('keyup', this.onKeyUp);
+
+      if (this.placeholderCleanup) {
+        this.placeholderCleanup();
+        this.placeholderCleanup = null;
+      }
+
+      if (isContentEmpty(this._element)) {
+        this._element.innerHTML = '<br>';
+      }
+    } else {
+      this._element.contentEditable = 'true';
+      this._element.addEventListener('keyup', this.onKeyUp);
+      this.placeholderCleanup = setupPlaceholder(this._element, this.api.i18n.t(this._placeholder), 'data-blok-placeholder-active');
+
+      if (this._element.innerHTML === '<br>') {
+        this._element.innerHTML = '';
+      }
+    }
+  }
+
   /**
    * Method that specified how to merge two Text blocks.
    * Called by Editor by backspace at the beginning of the Block

package/src/tools/quote/index.ts

@@ -13,7 +13,7 @@ import type { MenuConfig } from '../../../types/tools/menu-config';
 import { DATA_ATTR } from '../../components/constants';
 import { IconQuote } from '../../components/icons';
 import { stripFakeBackgroundElements } from '../../components/utils';
-import { PLACEHOLDER_FOCUS_ONLY_CLASSES, setupPlaceholder } from '../../components/utils/placeholder';
+import { isContentEmpty, PLACEHOLDER_FOCUS_ONLY_CLASSES, setupPlaceholder } from '../../components/utils/placeholder';
 import { twMerge } from '../../components/utils/tw';
 
 export interface QuoteData extends BlockToolData {
@@ -40,6 +40,7 @@ const LARGE_CLASS = 'text-[1.2em]';
 export class Quote implements BlockTool {
   private api: API;
   private readOnly: boolean;
+  private placeholderCleanup: (() => void) | null = null;
   private _data: QuoteData;
   private _element: HTMLQuoteElement | null = null;
 
@@ -51,9 +52,7 @@ export class Quote implements BlockTool {
       size: data?.size ?? 'default',
     };
 
-    if (!this.readOnly) {
-      this.onKeyUp = this.onKeyUp.bind(this);
-    }
+    this.onKeyUp = this.onKeyUp.bind(this);
   }
 
   public onKeyUp(e: KeyboardEvent): void {
@@ -70,7 +69,7 @@ export class Quote implements BlockTool {
     }
   }
 
-  public render(): HTMLQuoteElement {
+  private drawView(): HTMLQuoteElement {
     const el = document.createElement('blockquote');
 
     el.className = twMerge(
@@ -91,14 +90,50 @@ export class Quote implements BlockTool {
     if (!this.readOnly) {
       el.contentEditable = 'true';
       el.addEventListener('keyup', this.onKeyUp);
-      setupPlaceholder(el, this.api.i18n.t(DEFAULT_PLACEHOLDER), 'data-blok-placeholder-active');
+      this.placeholderCleanup = setupPlaceholder(el, this.api.i18n.t(DEFAULT_PLACEHOLDER), 'data-blok-placeholder-active');
     }
 
-    this._element = el;
-
     return el;
   }
 
+  public render(): HTMLQuoteElement {
+    if (!this._element) {
+      this._element = this.drawView();
+    }
+
+    return this._element;
+  }
+
+  public setReadOnly(state: boolean): void {
+    if (!this._element) {
+      return;
+    }
+
+    this.readOnly = state;
+
+    if (state) {
+      this._element.contentEditable = 'false';
+      this._element.removeEventListener('keyup', this.onKeyUp);
+
+      if (this.placeholderCleanup) {
+        this.placeholderCleanup();
+        this.placeholderCleanup = null;
+      }
+
+      if (isContentEmpty(this._element)) {
+        this._element.innerHTML = '<br>';
+      }
+    } else {
+      this._element.contentEditable = 'true';
+      this._element.addEventListener('keyup', this.onKeyUp);
+      this.placeholderCleanup = setupPlaceholder(this._element, this.api.i18n.t(DEFAULT_PLACEHOLDER), 'data-blok-placeholder-active');
+
+      if (this._element.innerHTML === '<br>') {
+        this._element.innerHTML = '';
+      }
+    }
+  }
+
   public save(blockContent: HTMLQuoteElement): QuoteData {
     return {
       text: stripFakeBackgroundElements(blockContent.innerHTML),

package/src/tools/stub/index.ts

@@ -73,6 +73,16 @@ export class Stub implements BlockTool {
     return this.savedData;
   }
 
+  /**
+   * Toggle read-only mode in-place.
+   * Stub has no interactive elements, so this is intentionally a no-op.
+   *
+   * @param _state - read-only state (unused)
+   */
+  public setReadOnly(_state: boolean): void {
+    // no-op: stub blocks have no editable content
+  }
+
   /**
    * Create Tool html markup
    * @returns {HTMLElement}