@jackuait/blok 0.6.0 → 0.7.0-beta.2

package/src/tools/toggle/index.ts

@@ -0,0 +1,302 @@
+/**
+ * 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,
+  PasteEvent,
+} 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 onPaste(event: PasteEvent): void {
+    const detail = event.detail;
+
+    if (!('data' in detail)) {
+      return;
+    }
+
+    const content = detail.data as HTMLElement;
+    const summary = content.querySelector('summary');
+    const text = summary !== null ? summary.innerHTML : content.innerHTML;
+
+    this._data = { text };
+
+    const contentEl = this.getContentElement();
+
+    if (contentEl !== null) {
+      contentEl.innerHTML = text;
+    }
+  }
+
+  public setData(newData: ToggleItemData): boolean {
+    const result = setToggleItemData(
+      this._data,
+      newData,
+      this.getContentElement.bind(this)
+    );
+
+    this._data = result.newData;
+
+    this.updateChildrenVisibility();
+
+    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);
+
+      return;
+    }
+  }
+
+  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 toolbox(): ToolboxConfig {
+    return {
+      icon: IconToggleList,
+      title: 'Toggle list',
+      titleKey: 'toggleList',
+      name: TOOL_NAME,
+      searchTerms: ['toggle', 'collapse', 'expand', 'accordion'],
+      shortcut: '>',
+    };
+  }
+
+  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,156 @@
+/**
+ * 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.
+ *
+ * When the toggle is open and the caret is at the end of the content,
+ * creates a child paragraph inside the toggle instead of splitting.
+ *
+ * @param context - The toggle keyboard context
+ */
+export const handleToggleEnter = async (context: ToggleKeyboardContext): Promise<void> => {
+  const { api, blockId, data, getContentElement, syncContentFromDOM, isOpen } = 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();
+
+  /**
+   * 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.
+   */
+  if (isOpen && afterContent === '') {
+    const newBlock = api.blocks.insert('paragraph', { text: '' }, {}, currentBlockIndex + 1, true);
+
+    api.blocks.setBlockParent(newBlock.id, blockId);
+
+    return;
+  }
+
+  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, syncContentFromDOM } = context;
+
+  syncContentFromDOM();
+
+  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,81 @@
+/**
+ * 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');
+  arrowEl.setAttribute('aria-expanded', String(isOpen));
+  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,113 @@
+/**
+ * Toggle Shortcuts - Manages the collapse/expand-all keyboard shortcut (CMD+ALT+T).
+ *
+ * Iterates all blocks in the editor and toggles all collapsible blocks
+ * (toggle blocks and toggle headings):
+ * - If any collapsible block is collapsed, expands all
+ * - If all collapsible blocks are expanded, collapses all
+ */
+
+import type { API } from '../../../types';
+
+import { Shortcuts } from '../../components/utils/shortcuts';
+
+import { TOGGLE_ATTR } 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 collapsible blocks (toggle blocks and toggle headings).
+   * If any 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) {
+        continue;
+      }
+
+      const toggleWrapper = block.holder.querySelector(`[${TOGGLE_ATTR.toggleOpen}]`);
+
+      if (toggleWrapper === null) {
+        continue;
+      }
+
+      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/types/full.d.ts

@@ -17,6 +17,7 @@ export {
   Bold,
   Italic,
   Link,
+  Marker,
   Convert,
   Delete,
   defaultBlockTools,
@@ -76,5 +77,6 @@ export const allTools: {
   readonly bold: { readonly class: InlineToolConstructable };
   readonly italic: { readonly class: InlineToolConstructable };
   readonly link: { readonly class: InlineToolConstructable };
+  readonly marker: { readonly class: InlineToolConstructable };
   readonly convertTo: { readonly class: InlineToolConstructable };
 };

package/types/tools-entry.d.ts

@@ -28,6 +28,7 @@ export const Bold: InlineToolConstructable;
 export const Italic: InlineToolConstructable;
 export const Link: InlineToolConstructable;
 export const Convert: InlineToolConstructable;
+export const Marker: InlineToolConstructable;
 
 // Block tunes
 export const Delete: BlockTuneConstructable;
@@ -49,5 +50,5 @@ export const defaultInlineTools: {
   readonly bold: {};
   readonly italic: {};
   readonly link: {};
-  readonly convertTo: {};
+  readonly marker: {};
 };