@jackuait/blok 0.7.0-beta.4 → 0.7.0

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

@@ -6,14 +6,17 @@
  */
 
 import { DATA_ATTR } from '../../components/constants';
+import { PLACEHOLDER_ACTIVE_CLASSES, PLACEHOLDER_EMPTY_EDITOR_CLASSES } from '../../components/utils/placeholder';
 import { twMerge } from '../../components/utils/tw';
 
 import {
   ARROW_ICON,
   ARROW_STYLES,
   BASE_STYLES,
+  BODY_PLACEHOLDER_STYLES,
   CONTENT_STYLES,
   TOGGLE_ATTR,
+  TOGGLE_CHILDREN_STYLES,
   TOGGLE_WRAPPER_STYLES,
   TOOL_NAME,
 } from './constants';
@@ -31,8 +34,14 @@ export interface ToggleDOMBuilderContext {
   isOpen: boolean;
   /** Optional keydown event handler */
   keydownHandler: ((event: KeyboardEvent) => void) | null;
-  /** Callback when the arrow is clicked */
-  onArrowClick: () => void;
+  /** Callback when the arrow is clicked. Null/undefined disables interaction (read-only mode). */
+  onArrowClick: (() => void) | null | undefined;
+  /** Callback when the body placeholder is clicked */
+  onBodyPlaceholderClick: (() => void) | null;
+  /** Translated text for the body placeholder */
+  bodyPlaceholderText: string;
+  /** Translated aria labels for the toggle arrow */
+  ariaLabels: { collapse: string; expand: string };
 }
 
 /**
@@ -45,6 +54,10 @@ export interface ToggleBuildResult {
   arrowElement: HTMLElement;
   /** The content element for text input */
   contentElement: HTMLElement;
+  /** The body placeholder element */
+  bodyPlaceholderElement: HTMLElement;
+  /** The child container element */
+  childContainerElement: HTMLElement;
 }
 
 /**
@@ -54,20 +67,40 @@ export interface ToggleBuildResult {
  * @returns Object containing the created elements
  */
 export const buildToggleItem = (context: ToggleDOMBuilderContext): ToggleBuildResult => {
-  const { data, readOnly, isOpen, keydownHandler, onArrowClick } = context;
+  const { data, readOnly, isOpen, keydownHandler, onArrowClick, onBodyPlaceholderClick } = context;
 
   const wrapper = document.createElement('div');
-  wrapper.className = twMerge(BASE_STYLES, TOGGLE_WRAPPER_STYLES);
+  wrapper.className = BASE_STYLES;
   wrapper.setAttribute(DATA_ATTR.tool, TOOL_NAME);
   wrapper.setAttribute(TOGGLE_ATTR.toggleOpen, String(isOpen));
 
-  const arrowElement = buildArrow(isOpen, onArrowClick);
+  const headerRow = document.createElement('div');
+  headerRow.className = TOGGLE_WRAPPER_STYLES;
+
+  const arrowElement = buildArrow(isOpen, onArrowClick, {}, context.ariaLabels);
   const contentElement = buildContent(data, readOnly, keydownHandler);
 
-  wrapper.appendChild(arrowElement);
-  wrapper.appendChild(contentElement);
+  headerRow.appendChild(arrowElement);
+  headerRow.appendChild(contentElement);
+
+  const bodyPlaceholderElement = buildBodyPlaceholder(onBodyPlaceholderClick, context.bodyPlaceholderText);
+
+  const childContainerElement = document.createElement('div');
+  childContainerElement.className = TOGGLE_CHILDREN_STYLES;
+  childContainerElement.setAttribute(TOGGLE_ATTR.toggleChildren, '');
+  // Block DOM mutations inside the children container from triggering the toggle tool's
+  // didMutated → syncBlockDataToYjs path. Child block insertions/removals are tracked
+  // via the block hierarchy (parentId / contentIds) and must not create spurious Yjs
+  // undo entries that split "insert child" into two CMD+Z steps.
+  childContainerElement.setAttribute('data-blok-mutation-free', 'true');
+  childContainerElement.id = `toggle-children-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  arrowElement.setAttribute('aria-controls', childContainerElement.id);
 
-  return { wrapper, arrowElement, contentElement };
+  wrapper.appendChild(headerRow);
+  wrapper.appendChild(bodyPlaceholderElement);
+  wrapper.appendChild(childContainerElement);
+
+  return { wrapper, arrowElement, contentElement, bodyPlaceholderElement, childContainerElement };
 };
 
 /**
@@ -82,14 +115,15 @@ export interface BuildArrowOptions {
  * Build the arrow element for toggling open/closed state.
  *
  * @param isOpen - Whether the toggle is currently open
- * @param onArrowClick - Callback when arrow is clicked
+ * @param onArrowClick - Callback when arrow is clicked. Pass null/undefined to disable click interaction (e.g. read-only mode).
  * @param options - Optional configuration
  * @returns The arrow element
  */
 export const buildArrow = (
   isOpen: boolean,
-  onArrowClick: () => void,
-  options: BuildArrowOptions = {}
+  onArrowClick: (() => void) | null | undefined,
+  options: BuildArrowOptions = {},
+  ariaLabels: { collapse: string; expand: string } = { collapse: 'Collapse', expand: 'Expand' }
 ): HTMLElement => {
   const arrow = document.createElement('span');
   arrow.className = ARROW_STYLES;
@@ -97,7 +131,7 @@ export const buildArrow = (
   arrow.setAttribute(DATA_ATTR.mutationFree, 'true');
   arrow.setAttribute('role', 'button');
   arrow.setAttribute('tabindex', '0');
-  arrow.setAttribute('aria-label', isOpen ? 'Collapse' : 'Expand');
+  arrow.setAttribute('aria-label', isOpen ? ariaLabels.collapse : ariaLabels.expand);
   arrow.setAttribute('aria-expanded', String(isOpen));
 
   if (options.contentEditableFalse === true) {
@@ -106,26 +140,57 @@ export const buildArrow = (
 
   arrow.innerHTML = ARROW_ICON;
 
-  if (isOpen) {
-    arrow.style.transform = 'rotate(90deg)';
-  }
+  const svg = arrow.querySelector('svg');
 
-  arrow.addEventListener('click', (event: MouseEvent) => {
-    event.stopPropagation();
-    onArrowClick();
-  });
+  if (svg) {
+    svg.style.transition = 'transform 200ms ease-in-out';
 
-  arrow.addEventListener('keydown', (event: KeyboardEvent) => {
-    if (event.key === 'Enter' || event.key === ' ') {
-      event.preventDefault();
+    if (isOpen) {
+      svg.style.transform = 'rotate(90deg)';
+    }
+  }
+
+  if (onArrowClick) {
+    arrow.addEventListener('click', (event: MouseEvent) => {
       event.stopPropagation();
       onArrowClick();
-    }
-  });
+    });
+
+    arrow.addEventListener('keydown', (event: KeyboardEvent) => {
+      if (event.key === 'Enter' || event.key === ' ') {
+        event.preventDefault();
+        event.stopPropagation();
+        onArrowClick();
+      }
+    });
+  }
 
   return arrow;
 };
 
+/**
+ * Build the body placeholder element shown when the toggle has no children.
+ *
+ * @param onClick - Optional click handler (creates a child block)
+ * @returns The body placeholder element
+ */
+const buildBodyPlaceholder = (onClick: (() => void) | null, text: string): HTMLElement => {
+  const placeholder = document.createElement('div');
+  placeholder.className = BODY_PLACEHOLDER_STYLES;
+  placeholder.setAttribute(TOGGLE_ATTR.toggleBodyPlaceholder, '');
+  // Class changes on the body placeholder (show/hide) must not trigger didMutated →
+  // syncBlockDataToYjs, which would create a spurious Yjs undo entry when a child
+  // block is inserted via Enter. The placeholder holds no user-editable content.
+  placeholder.setAttribute('data-blok-mutation-free', 'true');
+  placeholder.textContent = text;
+
+  if (onClick) {
+    placeholder.addEventListener('click', onClick);
+  }
+
+  return placeholder;
+};
+
 /**
  * Build the content element for text input.
  *
@@ -140,7 +205,7 @@ const buildContent = (
   keydownHandler: ((event: KeyboardEvent) => void) | null
 ): HTMLElement => {
   const content = document.createElement('div');
-  content.className = CONTENT_STYLES;
+  content.className = twMerge(CONTENT_STYLES, PLACEHOLDER_ACTIVE_CLASSES, PLACEHOLDER_EMPTY_EDITOR_CLASSES);
   content.setAttribute(TOGGLE_ATTR.toggleContent, '');
   content.contentEditable = readOnly ? 'false' : 'true';
   content.innerHTML = data.text;

package/src/tools/toggle/index.ts

@@ -11,6 +11,7 @@ import type {
   BlockToolConstructorOptions,
   ToolboxConfig,
   ConversionConfig,
+  SanitizerConfig,
   ToolSanitizerConfig,
   PasteConfig,
   PasteEvent,
@@ -23,9 +24,10 @@ import {
   setToggleItemData,
   parseHTML,
 } from './block-operations';
-import { PLACEHOLDER_KEY, TOOL_NAME } from './constants';
+import { clean } from '../../components/utils/sanitizer';
+import { ARIA_LABEL_COLLAPSE_KEY, ARIA_LABEL_EXPAND_KEY, BODY_PLACEHOLDER_KEY, PLACEHOLDER_KEY, TOOL_NAME } from './constants';
 import { IconToggleList } from '../../components/icons';
-import { renderToggleItem, updateArrowState, updateChildrenVisibility } from './toggle-lifecycle';
+import { renderToggleItem, updateArrowState, updateChildrenVisibility, updateBodyPlaceholderVisibility } from './toggle-lifecycle';
 import { handleToggleEnter, handleToggleBackspace } from './toggle-keyboard';
 import type { ToggleItemData, ToggleItemConfig } from './types';
 
@@ -37,7 +39,9 @@ export class ToggleItem implements BlockTool {
   private _element: HTMLElement | null = null;
   private _contentElement: HTMLElement | null = null;
   private _arrowElement: HTMLElement | null = null;
-  private _isOpen: boolean = false;
+  private _bodyPlaceholderElement: HTMLElement | null = null;
+  private _childContainerElement: HTMLElement | null = null;
+  private _isOpen: boolean;
 
   private blockId?: string;
 
@@ -46,17 +50,28 @@ export class ToggleItem implements BlockTool {
     this.readOnly = readOnly;
     this._settings = config || {};
     this._data = this.normalizeData(data);
+    this._isOpen = this._data.isOpen ?? !readOnly;
 
     if (block) {
       this.blockId = block.id;
     }
+
+    if (!readOnly) {
+      this.api.events.on('block changed', this.handleBlockChanged);
+    }
   }
 
   private normalizeData(data: ToggleItemData | Record<string, never>): ToggleItemData {
     if (typeof data === 'object' && data !== null && 'text' in data) {
-      return {
+      const normalized: ToggleItemData = {
         text: typeof data.text === 'string' ? data.text : '',
       };
+
+      if (typeof (data as ToggleItemData).isOpen === 'boolean') {
+        normalized.isOpen = (data as ToggleItemData).isOpen;
+      }
+
+      return normalized;
     }
 
     return { text: '' };
@@ -83,22 +98,31 @@ export class ToggleItem implements BlockTool {
       isOpen: this._isOpen,
       placeholder: this.placeholder,
       keydownHandler: this.readOnly ? null : this.handleKeyDown.bind(this),
-      onArrowClick: () => this.toggleOpen(),
+      onArrowClick: this.readOnly ? null : () => this.toggleOpen(),
+      onBodyPlaceholderClick: this.readOnly ? null : () => this.handleBodyPlaceholderClick(),
+      bodyPlaceholderText: this.api.i18n.t(BODY_PLACEHOLDER_KEY),
+      ariaLabels: {
+        collapse: this.api.i18n.t(ARIA_LABEL_COLLAPSE_KEY),
+        expand: this.api.i18n.t(ARIA_LABEL_EXPAND_KEY),
+      },
     });
 
     this._element = result.wrapper;
     this._contentElement = result.contentElement;
     this._arrowElement = result.arrowElement;
+    this._bodyPlaceholderElement = result.bodyPlaceholderElement;
+    this._childContainerElement = result.childContainerElement;
 
     return this._element;
   }
 
   public rendered(): void {
     this.updateChildrenVisibility();
+    this.updateBodyPlaceholderVisibility();
   }
 
   public save(): ToggleItemData {
-    return saveToggleItem(this._data, this._element, this.getContentElement.bind(this));
+    return saveToggleItem(this._data, this._element, this.getContentElement.bind(this), this._isOpen);
   }
 
   public validate(_blockData: ToggleItemData): boolean {
@@ -125,7 +149,8 @@ export class ToggleItem implements BlockTool {
 
     const content = detail.data as HTMLElement;
     const summary = content.querySelector('summary');
-    const text = summary !== null ? summary.innerHTML : content.innerHTML;
+    const rawText = summary !== null ? summary.innerHTML : content.innerHTML;
+    const text = clean(rawText, ToggleItem.sanitize.text as SanitizerConfig);
 
     this._data = { text };
 
@@ -145,7 +170,19 @@ export class ToggleItem implements BlockTool {
 
     this._data = result.newData;
 
+    if (typeof this._data.isOpen === 'boolean') {
+      this._isOpen = this._data.isOpen;
+    }
+
+    if (this._arrowElement && this._element) {
+      updateArrowState(this._arrowElement, this._element, this._isOpen, {
+        collapse: this.api.i18n.t(ARIA_LABEL_COLLAPSE_KEY),
+        expand: this.api.i18n.t(ARIA_LABEL_EXPAND_KEY),
+      });
+    }
+
     this.updateChildrenVisibility();
+    this.updateBodyPlaceholderVisibility();
 
     return result.inPlace;
   }
@@ -178,6 +215,32 @@ export class ToggleItem implements BlockTool {
     this.setOpenState(false);
   }
 
+  public removed(): void {
+    this.api.events.off('block changed', this.handleBlockChanged);
+  }
+
+  private handleBlockChanged = (data: unknown): void => {
+    if (!this.isBlockChangedPayload(data)) {
+      return;
+    }
+
+    if (data.event.type === 'block-removed' || data.event.type === 'block-added') {
+      this.updateBodyPlaceholderVisibility();
+    }
+  };
+
+  private isBlockChangedPayload(data: unknown): data is { event: { type: string } } {
+    return (
+      typeof data === 'object' &&
+      data !== null &&
+      'event' in data &&
+      typeof (data as { event: unknown }).event === 'object' &&
+      (data as { event: unknown }).event !== null &&
+      'type' in (data as { event: { type: unknown } }).event &&
+      typeof (data as { event: { type: unknown } }).event.type === 'string'
+    );
+  }
+
   private getContentElement(): HTMLElement | null {
     return this._contentElement;
   }
@@ -186,10 +249,14 @@ export class ToggleItem implements BlockTool {
     this._isOpen = open;
 
     if (this._arrowElement && this._element) {
-      updateArrowState(this._arrowElement, this._element, this._isOpen);
+      updateArrowState(this._arrowElement, this._element, this._isOpen, {
+        collapse: this.api.i18n.t(ARIA_LABEL_COLLAPSE_KEY),
+        expand: this.api.i18n.t(ARIA_LABEL_EXPAND_KEY),
+      });
     }
 
     this.updateChildrenVisibility();
+    this.updateBodyPlaceholderVisibility();
   }
 
   private toggleOpen(): void {
@@ -201,7 +268,40 @@ export class ToggleItem implements BlockTool {
       return;
     }
 
-    updateChildrenVisibility(this.api, this.blockId, this._isOpen);
+    updateChildrenVisibility(this.api, this.blockId, this._isOpen, this._childContainerElement, this._arrowElement);
+  }
+
+  private updateBodyPlaceholderVisibility(): void {
+    if (this.blockId === undefined) {
+      return;
+    }
+
+    updateBodyPlaceholderVisibility(
+      this._bodyPlaceholderElement,
+      this.api,
+      this.blockId,
+      this._isOpen,
+      this.readOnly
+    );
+  }
+
+  private handleBodyPlaceholderClick(): void {
+    if (this.blockId === undefined) {
+      return;
+    }
+
+    const blockIndex = this.api.blocks.getBlockIndex(this.blockId);
+
+    if (blockIndex === undefined) {
+      return;
+    }
+
+    const newBlock = this.api.blocks.insertInsideParent(this.blockId, blockIndex + 1);
+
+    this.api.caret.setToBlock(newBlock.id, 'start');
+
+    // Hide the body placeholder now that a child exists
+    this._bodyPlaceholderElement?.classList.add('hidden');
   }
 
   private handleKeyDown(event: KeyboardEvent): void {
@@ -236,6 +336,9 @@ export class ToggleItem implements BlockTool {
 
   private async handleEnter(): Promise<void> {
     await handleToggleEnter(this.createKeyboardContext());
+
+    // After Enter may create a child, update body placeholder visibility
+    this.updateBodyPlaceholderVisibility();
   }
 
   private async handleBackspace(event: KeyboardEvent): Promise<void> {

package/src/tools/toggle/toggle-keyboard.ts

@@ -57,11 +57,13 @@ export const handleToggleEnter = async (context: ToggleKeyboardContext): Promise
   /**
    * When toggle is open and caret is at the end (no content after caret),
    * create a child paragraph inside the toggle rather than a sibling toggle.
+   * insertInsideParent() groups both block creation and parent assignment into
+   * a single Yjs undo entry, so one CMD+Z removes the new block completely.
    */
   if (isOpen && afterContent === '') {
-    const newBlock = api.blocks.insert('paragraph', { text: '' }, {}, currentBlockIndex + 1, true);
+    const newBlock = api.blocks.insertInsideParent(blockId, currentBlockIndex + 1);
 
-    api.blocks.setBlockParent(newBlock.id, blockId);
+    api.caret.setToBlock(newBlock.id, 'start');
 
     return;
   }
@@ -127,7 +129,7 @@ export const handleToggleBackspace = async (
  * @param range - The current selection range
  * @returns Object with before/after HTML content
  */
-const splitContentAtRange = (
+export const splitContentAtRange = (
   contentEl: HTMLElement,
   range: Range
 ): { beforeContent: string; afterContent: string } => {

package/src/tools/toggle/toggle-lifecycle.ts

@@ -26,19 +26,21 @@ export interface ToggleRenderResult {
   wrapper: HTMLElement;
   contentElement: HTMLElement;
   arrowElement: HTMLElement;
+  bodyPlaceholderElement: HTMLElement;
+  childContainerElement: HTMLElement;
 }
 
 /**
  * Render a toggle item with placeholder support.
  *
  * @param context - The render context
- * @returns Object containing the wrapper, content, and arrow elements
+ * @returns Object containing the wrapper, content, arrow, and body placeholder elements
  */
 export const renderToggleItem = (context: ToggleRenderContext): ToggleRenderResult => {
   const result = buildToggleItem(context);
 
   if (result.contentElement) {
-    setupPlaceholder(result.contentElement, context.placeholder);
+    setupPlaceholder(result.contentElement, context.placeholder, 'data-blok-placeholder-active');
   }
 
   return result;
@@ -51,11 +53,19 @@ export const renderToggleItem = (context: ToggleRenderContext): ToggleRenderResu
  * @param wrapper - The wrapper element to update the open attribute on
  * @param isOpen - Whether the toggle is open
  */
-export const updateArrowState = (arrowEl: HTMLElement, wrapper: HTMLElement, isOpen: boolean): void => {
-  const { style } = arrowEl;
+export const updateArrowState = (
+  arrowEl: HTMLElement,
+  wrapper: HTMLElement,
+  isOpen: boolean,
+  ariaLabels: { collapse: string; expand: string } = { collapse: 'Collapse', expand: 'Expand' }
+): void => {
+  const svg = arrowEl.querySelector('svg');
 
-  style.transform = isOpen ? 'rotate(90deg)' : '';
-  arrowEl.setAttribute('aria-label', isOpen ? 'Collapse' : 'Expand');
+  if (svg) {
+    svg.style.transform = isOpen ? 'rotate(90deg)' : '';
+  }
+
+  arrowEl.setAttribute('aria-label', isOpen ? ariaLabels.collapse : ariaLabels.expand);
   arrowEl.setAttribute('aria-expanded', String(isOpen));
   wrapper.setAttribute(TOGGLE_ATTR.toggleOpen, String(isOpen));
 };
@@ -67,15 +77,77 @@ export const updateArrowState = (arrowEl: HTMLElement, wrapper: HTMLElement, isO
  * @param api - Blok API instance
  * @param blockId - The toggle block's id
  * @param isOpen - Whether the toggle is currently open (expanded)
+ * @param childContainer - Optional child container element for aria-hidden management
+ * @param arrowElement - Optional arrow element to receive focus when collapsing with focus inside children
  */
-export const updateChildrenVisibility = (api: API, blockId: string, isOpen: boolean): void => {
+export const updateChildrenVisibility = (
+  api: API,
+  blockId: string,
+  isOpen: boolean,
+  childContainer?: HTMLElement | null,
+  arrowElement?: HTMLElement | null
+): void => {
   const children = api.blocks.getChildren(blockId);
 
+  // Before hiding, check if focus is inside the child container and move it to arrow
+  if (!isOpen && childContainer && arrowElement && childContainer.contains(document.activeElement)) {
+    arrowElement.focus();
+  }
+
   for (const child of children) {
+    if (childContainer && child.holder.parentElement !== childContainer) {
+      childContainer.appendChild(child.holder);
+    }
+
     if (isOpen) {
       child.holder.classList.remove('hidden');
     } else {
       child.holder.classList.add('hidden');
     }
   }
+
+  if (childContainer) {
+    if (isOpen) {
+      childContainer.removeAttribute('aria-hidden');
+    } else {
+      childContainer.setAttribute('aria-hidden', 'true');
+    }
+  }
+};
+
+/**
+ * Update visibility of the body placeholder based on toggle state and children.
+ * The placeholder is shown only when the toggle is open, has no children, and is not read-only.
+ *
+ * @param bodyPlaceholder - The body placeholder element
+ * @param api - Blok API instance
+ * @param blockId - The toggle block's id
+ * @param isOpen - Whether the toggle is currently open
+ * @param readOnly - Whether the editor is in read-only mode
+ */
+export const updateBodyPlaceholderVisibility = (
+  bodyPlaceholder: HTMLElement | null,
+  api: API,
+  blockId: string,
+  isOpen: boolean,
+  readOnly: boolean
+): void => {
+  if (bodyPlaceholder === null) {
+    return;
+  }
+
+  if (readOnly) {
+    bodyPlaceholder.classList.add('hidden');
+
+    return;
+  }
+
+  const children = api.blocks.getChildren(blockId);
+  const shouldShow = isOpen && children.length === 0;
+
+  if (shouldShow) {
+    bodyPlaceholder.classList.remove('hidden');
+  } else {
+    bodyPlaceholder.classList.add('hidden');
+  }
 };