Blocks API

import { Blocks } from '@yoopta/editor';

// Use with editor instance
Blocks.insertBlock(editor, 'Paragraph', { at: 0 });

// Or via editor methods
editor.insertBlock('Paragraph', { at: 0 });

function insertBlock(
  editor: YooEditor,
  type: string,
  options?: InsertBlockOptions
): string

// Insert paragraph at current position
const blockId = editor.insertBlock('Paragraph');

// Insert heading at specific position with focus
const headingId = editor.insertBlock('HeadingOne', {
  at: 0,
  focus: true
});

// Insert accordion with custom structure
const accordionId = editor.insertBlock('Accordion', {
  elements: editor.y('accordion-list', {
    children: [
      editor.y('accordion-list-item', {
        props: { isExpanded: false },
        children: [
          editor.y('accordion-list-item-heading'),
          editor.y('accordion-list-item-content')
        ]
      })
    ]
  })
});

function duplicateBlock(
  editor: YooEditor,
  options?: DuplicateBlockOptions
): string | undefined

// Duplicate current block
const newId = editor.duplicateBlock();

// Duplicate specific block by ID
const newId = editor.duplicateBlock({ blockId: 'block-123' });

// Duplicate and insert at specific position
const newId = editor.duplicateBlock({ at: 3, insertAt: 0 });

function buildBlockData(
  block?: BuildBlockDataOptions
): YooptaBlockData

// Build default paragraph block
const block = Blocks.buildBlockData();

// Build custom block
const block = Blocks.buildBlockData({
  type: 'HeadingOne',
  meta: { order: 0, depth: 0, align: 'center' }
});

function updateBlock(
  editor: YooEditor,
  blockId: string,
  newData: Omit<Partial<YooptaBlockData>, 'id' | 'type'>
): void

// Update block alignment
editor.updateBlock('block-123', {
  meta: { align: 'center' }
});

// Update block depth
editor.updateBlock('block-123', {
  meta: { depth: 1 }
});

// Update block value
editor.updateBlock('block-123', {
  value: [newSlateElement]
});

function toggleBlock(
  editor: YooEditor,
  type: string,
  options?: ToggleBlockOptions
): string

// Transform paragraph to heading
editor.toggleBlock('HeadingOne', { preserveContent: true });

// Toggle back to paragraph (if already HeadingOne)
editor.toggleBlock('HeadingOne'); // Becomes Paragraph

// Insert element in current leaf
editor.toggleBlock('Paragraph', {
  scope: 'element',
  preserveContent: false
});

// With custom structure
editor.toggleBlock('Accordion', {
  elements: editor.y('accordion-list', { /* ... */ })
});

function moveBlock(
  editor: YooEditor,
  draggedBlockId: string,
  newPath: number
): void

// Move block to position 0
editor.moveBlock('block-123', 0);

// Move block to end
const blockCount = Object.keys(editor.children).length;
editor.moveBlock('block-123', blockCount - 1);

function increaseBlockDepth(
  editor: YooEditor,
  options?: BlockDepthOptions
): void

// Increase depth of current block
editor.increaseBlockDepth();

// Increase depth of specific block
editor.increaseBlockDepth({ blockId: 'block-123' });

function decreaseBlockDepth(
  editor: YooEditor,
  options?: BlockDepthOptions
): void

// Decrease depth of current block
editor.decreaseBlockDepth();

// Decrease depth of specific block
editor.decreaseBlockDepth({ at: 3 });

function deleteBlock(
  editor: YooEditor,
  options?: DeleteBlockOptions
): void

// Delete current block
editor.deleteBlock();

// Delete specific block by path
editor.deleteBlock({ at: 3 });

// Delete by ID without focusing
editor.deleteBlock({ blockId: 'block-123', focus: false });

// Delete and focus next block
editor.deleteBlock({ at: 3, focusTarget: 'next' });

function splitBlock(
  editor: YooEditor,
  options?: SplitBlockOptions
): string | undefined

// Split current block at selection
const newBlockId = editor.splitBlock();

// Split specific block
const newBlockId = editor.splitBlock({ at: 3 });

// Split and focus original block
const newBlockId = editor.splitBlock({ focusTarget: 'original' });

function mergeBlock(
  editor: YooEditor,
  options?: MergeBlockOptions
): void

// Merge current block into previous (default)
editor.mergeBlock();

// Merge specific block into previous
editor.mergeBlock({ at: 5 });

// Merge block at index 5 into block at index 3
editor.mergeBlock({ at: 5, targetAt: 3 });

// Merge without focusing
editor.mergeBlock({ focus: false });

function focusBlock(
  editor: YooEditor,
  blockId: string,
  options?: FocusBlockOptions
): void

// Focus block
editor.focusBlock('block-123');

// Focus at end of block
const lastPoint = Paths.getLastNodePoint(slate);
editor.focusBlock('block-123', { focusAt: lastPoint });

// Focus immediately without waiting
editor.focusBlock('block-123', { waitExecution: false });

function getBlock(
  editor: YooEditor,
  options: GetBlockOptions
): YooptaBlockData | null

// Get block by ID
const block = editor.getBlock({ id: 'block-123' });

// Get block by position
const block = editor.getBlock({ at: 0 });

if (block) {
  console.log(block.type, block.meta.order);
}

function getBlockSlate(
  editor: YooEditor,
  options: GetBlockSlateOptions
): SlateEditor | null

// Get slate editor by block ID
const slate = Blocks.getBlockSlate(editor, { id: 'block-123' });

// Get slate editor by position
const slate = Blocks.getBlockSlate(editor, { at: 0 });

if (slate) {
  // Perform Slate operations
  const selection = slate.selection;
}

type YooptaBlockData = {
  id: string;
  type: string;           // PascalCase: "Paragraph", "HeadingOne"
  value: SlateElement[];  // Slate elements
  meta: YooptaBlockBaseMeta;
};

type YooptaBlockBaseMeta = {
  order: number;          // Block position
  depth: number;          // Nesting depth
  align?: 'left' | 'center' | 'right';
};

type SlateElement = {
  id: string;
  type: string;           // kebab-case: "paragraph", "heading-one"
  children: Descendant[];
  props?: Record<string, unknown>;
};