@jackuait/blok 0.6.0-beta.9 → 0.7.0-beta.1

package/src/tools/toggle/index.ts

@@ -0,0 +1,280 @@
+/**
+ * Toggle Tool for the Blok Editor
+ * Provides collapsible toggle blocks with an arrow indicator.
+ *
+ * @license MIT
+ */
+
+import type {
+  API,
+  BlockTool,
+  BlockToolConstructorOptions,
+  ToolboxConfig,
+  ConversionConfig,
+  ToolSanitizerConfig,
+  PasteConfig,
+} from '../../../types';
+import type { MenuConfig } from '../../../types/tools/menu-config';
+
+import {
+  saveToggleItem,
+  mergeToggleItemData,
+  setToggleItemData,
+  parseHTML,
+} from './block-operations';
+import { PLACEHOLDER_KEY, TOOL_NAME } from './constants';
+import { IconToggleList } from '../../components/icons';
+import { renderToggleItem, updateArrowState, updateChildrenVisibility } from './toggle-lifecycle';
+import { handleToggleEnter, handleToggleBackspace } from './toggle-keyboard';
+import type { ToggleItemData, ToggleItemConfig } from './types';
+
+export class ToggleItem implements BlockTool {
+  private api: API;
+  private readOnly: boolean;
+  private _settings: ToggleItemConfig;
+  private _data: ToggleItemData;
+  private _element: HTMLElement | null = null;
+  private _contentElement: HTMLElement | null = null;
+  private _arrowElement: HTMLElement | null = null;
+  private _isOpen: boolean = false;
+
+  private blockId?: string;
+
+  constructor({ data, config, api, readOnly, block }: BlockToolConstructorOptions<ToggleItemData, ToggleItemConfig>) {
+    this.api = api;
+    this.readOnly = readOnly;
+    this._settings = config || {};
+    this._data = this.normalizeData(data);
+
+    if (block) {
+      this.blockId = block.id;
+    }
+  }
+
+  private normalizeData(data: ToggleItemData | Record<string, never>): ToggleItemData {
+    if (typeof data === 'object' && data !== null && 'text' in data) {
+      return {
+        text: typeof data.text === 'string' ? data.text : '',
+      };
+    }
+
+    return { text: '' };
+  }
+
+  private get placeholder(): string {
+    if (this._settings.placeholder) {
+      return this._settings.placeholder;
+    }
+
+    const translated = this.api.i18n.t(PLACEHOLDER_KEY);
+
+    if (translated !== PLACEHOLDER_KEY) {
+      return translated;
+    }
+
+    return 'Toggle';
+  }
+
+  public render(): HTMLElement {
+    const result = renderToggleItem({
+      data: this._data,
+      readOnly: this.readOnly,
+      isOpen: this._isOpen,
+      placeholder: this.placeholder,
+      keydownHandler: this.readOnly ? null : this.handleKeyDown.bind(this),
+      onArrowClick: () => this.toggleOpen(),
+    });
+
+    this._element = result.wrapper;
+    this._contentElement = result.contentElement;
+    this._arrowElement = result.arrowElement;
+
+    return this._element;
+  }
+
+  public rendered(): void {
+    this.updateChildrenVisibility();
+  }
+
+  public save(): ToggleItemData {
+    return saveToggleItem(this._data, this._element, this.getContentElement.bind(this));
+  }
+
+  public validate(_blockData: ToggleItemData): boolean {
+    return true;
+  }
+
+  public merge(data: ToggleItemData): void {
+    mergeToggleItemData(
+      {
+        data: this._data,
+        getContentElement: this.getContentElement.bind(this),
+        parseHTML,
+      },
+      data
+    );
+  }
+
+  public setData(newData: ToggleItemData): boolean {
+    const result = setToggleItemData(
+      this._data,
+      newData,
+      this.getContentElement.bind(this)
+    );
+
+    this._data = result.newData;
+
+    return result.inPlace;
+  }
+
+  public renderSettings(): MenuConfig {
+    return [];
+  }
+
+  /**
+   * Expand the toggle (no-op if already expanded).
+   * Can be called externally via block.call('expand').
+   */
+  public expand(): void {
+    if (this._isOpen) {
+      return;
+    }
+
+    this.setOpenState(true);
+  }
+
+  /**
+   * Collapse the toggle (no-op if already collapsed).
+   * Can be called externally via block.call('collapse').
+   */
+  public collapse(): void {
+    if (!this._isOpen) {
+      return;
+    }
+
+    this.setOpenState(false);
+  }
+
+  private getContentElement(): HTMLElement | null {
+    return this._contentElement;
+  }
+
+  private setOpenState(open: boolean): void {
+    this._isOpen = open;
+
+    if (this._arrowElement && this._element) {
+      updateArrowState(this._arrowElement, this._element, this._isOpen);
+    }
+
+    this.updateChildrenVisibility();
+  }
+
+  private toggleOpen(): void {
+    this.setOpenState(!this._isOpen);
+  }
+
+  private updateChildrenVisibility(): void {
+    if (this.blockId === undefined) {
+      return;
+    }
+
+    updateChildrenVisibility(this.api, this.blockId, this._isOpen);
+  }
+
+  private handleKeyDown(event: KeyboardEvent): void {
+    if (event.key === 'Enter' && !event.shiftKey) {
+      event.preventDefault();
+      void this.handleEnter();
+
+      return;
+    }
+
+    if (event.key === 'Backspace') {
+      void this.handleBackspace(event);
+    }
+  }
+
+  private createKeyboardContext(): Parameters<typeof handleToggleEnter>[0] {
+    return {
+      api: this.api,
+      blockId: this.blockId,
+      data: this._data,
+      element: this._element,
+      getContentElement: this.getContentElement.bind(this),
+      syncContentFromDOM: this.syncContentFromDOM.bind(this),
+      isOpen: this._isOpen,
+      setOpen: (open: boolean) => {
+        this._isOpen = open;
+      },
+    };
+  }
+
+  private async handleEnter(): Promise<void> {
+    await handleToggleEnter(this.createKeyboardContext());
+  }
+
+  private async handleBackspace(event: KeyboardEvent): Promise<void> {
+    await handleToggleBackspace(this.createKeyboardContext(), event);
+  }
+
+  private syncContentFromDOM(): void {
+    const contentEl = this.getContentElement();
+
+    if (contentEl) {
+      this._data.text = contentEl.innerHTML;
+    }
+  }
+
+  public static get shortcut(): string {
+    return 'CMD+ALT+7';
+  }
+
+  public static get toolbox(): ToolboxConfig {
+    return {
+      icon: IconToggleList,
+      title: 'Toggle list',
+      titleKey: 'toggleList',
+      name: TOOL_NAME,
+      searchTerms: ['toggle', 'collapse', 'expand', 'accordion'],
+    };
+  }
+
+  public static get conversionConfig(): ConversionConfig {
+    return {
+      export: 'text',
+      import: 'text',
+    };
+  }
+
+  public static get sanitize(): ToolSanitizerConfig {
+    return {
+      text: {
+        br: true,
+        a: {
+          href: true,
+          target: '_blank',
+          rel: 'nofollow',
+        },
+        b: true,
+        i: true,
+        mark: {
+          class: true,
+          style: true,
+        },
+        code: true,
+      },
+    };
+  }
+
+  public static get pasteConfig(): PasteConfig {
+    return {
+      tags: ['DETAILS'],
+    };
+  }
+
+  public static get isReadOnlySupported(): boolean {
+    return true;
+  }
+}
+
+export type { ToggleItemConfig, ToggleItemData };

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

@@ -0,0 +1,139 @@
+/**
+ * Toggle Keyboard - Handles keyboard interactions for toggle items.
+ *
+ * Extracted from ToggleItem to reduce file size.
+ */
+
+import type { API } from '../../../types';
+
+import { isCaretAtStartOfInput } from '../../components/utils/caret';
+
+import { TOOL_NAME } from './constants';
+import type { ToggleItemData } from './types';
+
+/**
+ * Context for toggle keyboard operations
+ */
+export interface ToggleKeyboardContext {
+  api: API;
+  blockId: string | undefined;
+  data: ToggleItemData;
+  element: HTMLElement | null;
+  getContentElement: () => HTMLElement | null;
+  syncContentFromDOM: () => void;
+  isOpen: boolean;
+  setOpen: (open: boolean) => void;
+}
+
+/**
+ * Handle Enter key - sync content from DOM and split the block at the caret position.
+ *
+ * @param context - The toggle keyboard context
+ */
+export const handleToggleEnter = async (context: ToggleKeyboardContext): Promise<void> => {
+  const { api, blockId, data, getContentElement, syncContentFromDOM } = context;
+
+  syncContentFromDOM();
+
+  if (blockId === undefined) {
+    return;
+  }
+
+  const contentEl = getContentElement();
+  const selection = window.getSelection();
+
+  if (!contentEl || !selection || selection.rangeCount === 0) {
+    return;
+  }
+
+  const range = selection.getRangeAt(0);
+  const { beforeContent, afterContent } = splitContentAtRange(contentEl, range);
+
+  const currentBlockIndex = api.blocks.getBlockIndex(blockId) ?? api.blocks.getCurrentBlockIndex();
+
+  api.blocks.splitBlock(
+    blockId,
+    { text: beforeContent },
+    TOOL_NAME,
+    { text: afterContent },
+    currentBlockIndex + 1
+  );
+
+  data.text = beforeContent;
+};
+
+/**
+ * Handle Backspace key - convert to paragraph when content is empty and caret is at start.
+ *
+ * When the caret is at the very start of the content element AND the content is empty,
+ * converts the toggle to a paragraph block. If the caret is NOT at start, lets the
+ * browser handle it (does nothing).
+ *
+ * @param context - The toggle keyboard context
+ * @param event - The keyboard event
+ */
+export const handleToggleBackspace = async (
+  context: ToggleKeyboardContext,
+  event: KeyboardEvent
+): Promise<void> => {
+  const { api, blockId, data, getContentElement } = context;
+
+  if (blockId === undefined) {
+    return;
+  }
+
+  const contentEl = getContentElement();
+
+  if (!contentEl) {
+    return;
+  }
+
+  if (!isCaretAtStartOfInput(contentEl)) {
+    return;
+  }
+
+  const text = data.text;
+
+  if (text !== '') {
+    return;
+  }
+
+  event.preventDefault();
+
+  await api.blocks.convert(blockId, 'paragraph', { text });
+};
+
+/**
+ * Split content element's HTML at the given range position.
+ *
+ * @param contentEl - The contenteditable element containing text
+ * @param range - The current selection range
+ * @returns Object with before/after HTML content
+ */
+const splitContentAtRange = (
+  contentEl: HTMLElement,
+  range: Range
+): { beforeContent: string; afterContent: string } => {
+  if (!contentEl.lastChild) {
+    return { beforeContent: '', afterContent: '' };
+  }
+
+  const beforeRange = document.createRange();
+  beforeRange.setStart(contentEl, 0);
+  beforeRange.setEnd(range.startContainer, range.startOffset);
+
+  const afterRange = document.createRange();
+  afterRange.setStart(range.endContainer, range.endOffset);
+  afterRange.setEndAfter(contentEl.lastChild);
+
+  const beforeDiv = document.createElement('div');
+  beforeDiv.appendChild(beforeRange.cloneContents());
+
+  const afterDiv = document.createElement('div');
+  afterDiv.appendChild(afterRange.cloneContents());
+
+  return {
+    beforeContent: beforeDiv.innerHTML,
+    afterContent: afterDiv.innerHTML,
+  };
+};

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

@@ -0,0 +1,80 @@
+/**
+ * Toggle Lifecycle - Lifecycle methods for ToggleItem (render, state updates).
+ *
+ * Extracted from ToggleItem to reduce file size.
+ */
+
+import type { API } from '../../../types';
+
+import { setupPlaceholder } from '../../components/utils/placeholder';
+
+import { TOGGLE_ATTR } from './constants';
+import { buildToggleItem } from './dom-builder';
+import type { ToggleDOMBuilderContext } from './dom-builder';
+
+/**
+ * Context for rendering a toggle item
+ */
+export interface ToggleRenderContext extends ToggleDOMBuilderContext {
+  placeholder: string;
+}
+
+/**
+ * Result of rendering a toggle item
+ */
+export interface ToggleRenderResult {
+  wrapper: HTMLElement;
+  contentElement: HTMLElement;
+  arrowElement: HTMLElement;
+}
+
+/**
+ * Render a toggle item with placeholder support.
+ *
+ * @param context - The render context
+ * @returns Object containing the wrapper, content, and arrow elements
+ */
+export const renderToggleItem = (context: ToggleRenderContext): ToggleRenderResult => {
+  const result = buildToggleItem(context);
+
+  if (result.contentElement) {
+    setupPlaceholder(result.contentElement, context.placeholder);
+  }
+
+  return result;
+};
+
+/**
+ * Update the arrow rotation and wrapper's open state attribute.
+ *
+ * @param arrowEl - The arrow element to rotate
+ * @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;
+
+  style.transform = isOpen ? 'rotate(90deg)' : '';
+  arrowEl.setAttribute('aria-label', isOpen ? 'Collapse' : 'Expand');
+  wrapper.setAttribute(TOGGLE_ATTR.toggleOpen, String(isOpen));
+};
+
+/**
+ * Show or hide child block holders based on the toggle's open state.
+ * Children are hidden via the 'hidden' CSS class (display: none), not removed from the DOM.
+ *
+ * @param api - Blok API instance
+ * @param blockId - The toggle block's id
+ * @param isOpen - Whether the toggle is currently open (expanded)
+ */
+export const updateChildrenVisibility = (api: API, blockId: string, isOpen: boolean): void => {
+  const children = api.blocks.getChildren(blockId);
+
+  for (const child of children) {
+    if (isOpen) {
+      child.holder.classList.remove('hidden');
+    } else {
+      child.holder.classList.add('hidden');
+    }
+  }
+};

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

@@ -0,0 +1,107 @@
+/**
+ * Toggle Shortcuts - Manages the collapse/expand-all keyboard shortcut (CMD+ALT+T).
+ *
+ * Iterates all blocks in the editor and toggles all toggle blocks:
+ * - If any toggle is collapsed, expands all
+ * - If all toggles are expanded, collapses all
+ */
+
+import type { API } from '../../../types';
+
+import { Shortcuts } from '../../components/utils/shortcuts';
+
+import { TOGGLE_ATTR, TOOL_NAME } from './constants';
+
+const COLLAPSE_EXPAND_ALL_SHORTCUT = 'CMD+ALT+T';
+
+/**
+ * Manages the collapse/expand-all shortcut for toggle blocks.
+ */
+export class ToggleShortcuts {
+  private readonly api: API;
+  private readonly wrapper: HTMLElement;
+  private registered = false;
+
+  constructor(api: API, wrapper: HTMLElement) {
+    this.api = api;
+    this.wrapper = wrapper;
+  }
+
+  /**
+   * Register the CMD+ALT+T shortcut on the document.
+   */
+  public register(): void {
+    if (this.registered) {
+      return;
+    }
+
+    Shortcuts.add({
+      name: COLLAPSE_EXPAND_ALL_SHORTCUT,
+      on: document,
+      handler: (event: KeyboardEvent) => {
+        if (!this.shouldHandle(event)) {
+          return;
+        }
+
+        event.preventDefault();
+        this.toggleAll();
+      },
+    });
+
+    this.registered = true;
+  }
+
+  /**
+   * Unregister the shortcut.
+   */
+  public unregister(): void {
+    if (!this.registered) {
+      return;
+    }
+
+    Shortcuts.remove(document, COLLAPSE_EXPAND_ALL_SHORTCUT);
+    this.registered = false;
+  }
+
+  /**
+   * Only handle the shortcut if the event target is within the editor wrapper.
+   */
+  private shouldHandle(event: KeyboardEvent): boolean {
+    const target = event.target;
+
+    return target instanceof HTMLElement && this.wrapper.contains(target);
+  }
+
+  /**
+   * Toggle all toggle blocks.
+   * If any toggle is collapsed, expand all. If all are expanded, collapse all.
+   */
+  private toggleAll(): void {
+    const blockCount = this.api.blocks.getBlocksCount();
+    const toggleBlocks: { call: (method: string) => void; isOpen: boolean }[] = [];
+
+    for (const i of Array.from({ length: blockCount }, (_, idx) => idx)) {
+      const block = this.api.blocks.getBlockByIndex(i);
+
+      if (block === undefined || block.name !== TOOL_NAME) {
+        continue;
+      }
+
+      const toggleWrapper = block.holder.querySelector(`[${TOGGLE_ATTR.toggleOpen}]`);
+      const isOpen = toggleWrapper?.getAttribute(TOGGLE_ATTR.toggleOpen) === 'true';
+
+      toggleBlocks.push({ call: (method: string) => block.call(method), isOpen });
+    }
+
+    if (toggleBlocks.length === 0) {
+      return;
+    }
+
+    const anyCollapsed = toggleBlocks.some((b) => !b.isOpen);
+    const method = anyCollapsed ? 'expand' : 'collapse';
+
+    for (const block of toggleBlocks) {
+      block.call(method);
+    }
+  }
+}

package/src/tools/toggle/types.ts

@@ -0,0 +1,21 @@
+/**
+ * Type definitions for the Toggle tool
+ */
+
+import type { BlockToolData } from '../../../types';
+
+/**
+ * Tool's input and output data format
+ */
+export interface ToggleItemData extends BlockToolData {
+  /** Toggle item text content (can include HTML) */
+  text: string;
+}
+
+/**
+ * Tool's config from Editor
+ */
+export interface ToggleItemConfig {
+  /** Custom placeholder text for empty toggle items */
+  placeholder?: string;
+}

package/src/variants/blok-minimum.ts

@@ -59,6 +59,19 @@ class Blok {
   public exportAPI(blok: Core): void {
     const fieldsToExport = ['configuration'];
     const destroy = (): void => {
+      // Mark all modules as destroyed first so any in-flight async work stops gracefully
+      Object.values(blok.moduleInstances).forEach((moduleInstance) => {
+        if (moduleInstance === undefined || moduleInstance === null) {
+          return;
+        }
+
+        if (
+          isFunction((moduleInstance as { markDestroyed?: () => void }).markDestroyed)
+        ) {
+          (moduleInstance as { markDestroyed: () => void }).markDestroyed();
+        }
+      });
+
       Object.values(blok.moduleInstances).forEach((moduleInstance) => {
         if (moduleInstance === undefined || moduleInstance === null) {
           return;

package/types/api/block.d.ts

@@ -1,4 +1,5 @@
 import {BlockToolData, ToolConfig, ToolboxConfigEntry} from '../tools';
+import {BlockTuneData} from '../block-tunes/block-tune-data';
 import {SavedData} from '../data-formats';
 
 /**
@@ -35,6 +36,18 @@ export interface BlockAPI {
    */
   readonly selected: boolean;
 
+  /**
+   * Last successfully extracted block tool data (synchronous).
+   * Useful when async save() is not feasible, e.g. during clipboard operations.
+   */
+  readonly preservedData: BlockToolData;
+
+  /**
+   * Last successfully extracted tune data (synchronous).
+   * Useful when async save() is not feasible, e.g. during clipboard operations.
+   */
+  readonly preservedTunes: { [name: string]: BlockTuneData };
+
   /**
    * True if Block has inputs to be focused
    */

package/types/api/blocks.d.ts

@@ -7,6 +7,12 @@ import {BlockTuneData} from '../block-tunes/block-tune-data';
  * Describes methods to manipulate with Blok`s blocks
  */
 export interface Blocks {
+  /**
+   * Returns true when a Yjs sync operation (undo/redo) is in progress.
+   * Tools can use this to skip cleanup that would interfere with Yjs state management.
+   */
+  readonly isSyncingFromYjs: boolean;
+
   /**
    * Remove all blocks from Blok zone
    */
@@ -175,4 +181,14 @@ export interface Blocks {
     newBlockData: BlockToolData,
     insertIndex: number,
   ): BlockAPI;
+
+  /**
+   * Execute a function within a transaction.
+   * All block operations (insert, delete, move) within fn are grouped
+   * into a single undo entry. Prevents undo-group splitting that would
+   * make structural operations partially undoable.
+   *
+   * @param fn - The function containing block operations to group
+   */
+  transact?(fn: () => void): void;
 }