Block Management

/**
 * Remove all blocks from the editor
 */
clear(): Promise<void>;

/**
 * Render blocks from OutputData format
 * @param data - Saved block data to render
 */
render(data: OutputData): Promise<void>;

/**
 * Render blocks from HTML string
 * @param data - HTML string to convert to blocks
 */
renderFromHTML(data: string): Promise<void>;

// Clear all blocks
await editor.blocks.clear();

// Render saved data
await editor.blocks.render({
  blocks: [
    {
      type: "paragraph",
      data: { text: "Hello World" }
    }
  ]
});

// Render from HTML (requires appropriate tools)
await editor.blocks.renderFromHTML('<p>Hello World</p><h2>Heading</h2>');

/**
 * Insert new block and return its API
 * @param type - Tool name for the block
 * @param data - Initial data for the block
 * @param config - Tool configuration
 * @param index - Position to insert at (default: current position)
 * @param needToFocus - Whether to focus the new block
 * @param replace - Whether to replace existing block at index
 * @param id - Optional custom ID for the block
 * @returns BlockAPI instance for the inserted block
 */
insert(
  type?: string,
  data?: BlockToolData,
  config?: ToolConfig,
  index?: number,
  needToFocus?: boolean,
  replace?: boolean,
  id?: string
): BlockAPI;

/**
 * Insert multiple blocks at specified index
 * @param blocks - Array of block data to insert
 * @param index - Position to insert at (default: end)
 * @returns Array of BlockAPI instances
 */
insertMany(
  blocks: OutputBlockData[],
  index?: number
): BlockAPI[];

/**
 * Insert new initial block after current block (deprecated)
 */
insertNewBlock(): void;

// Insert paragraph at current position
const block = editor.blocks.insert('paragraph', {
  text: 'New paragraph content'
});

// Insert at specific index with focus
const headerBlock = editor.blocks.insert(
  'header',
  { text: 'New Header', level: 2 },
  {},
  1, // index
  true // focus
);

// Insert multiple blocks
const blocks = editor.blocks.insertMany([
  {
    type: 'paragraph',
    data: { text: 'First paragraph' }
  },
  {
    type: 'paragraph', 
    data: { text: 'Second paragraph' }
  }
], 2);

// Replace existing block
const replacement = editor.blocks.insert(
  'quote',
  { text: 'Inspirational quote' },
  {},
  0, // index
  false, // don't focus
  true // replace existing
);

/**
 * Get block API by index
 * @param index - Block index in the editor
 * @returns BlockAPI instance or undefined if not found
 */
getBlockByIndex(index: number): BlockAPI | undefined;

/**
 * Get block API by unique ID
 * @param id - Block ID
 * @returns BlockAPI instance or null if not found
 */
getById(id: string): BlockAPI | null;

/**
 * Get current active block index
 * @returns Index of currently focused block
 */
getCurrentBlockIndex(): number;

/**
 * Get block index by its ID
 * @param blockId - Block ID to search for
 * @returns Index of the block
 */
getBlockIndex(blockId: string): number;

/**
 * Get block API by HTML element
 * @param element - HTML element belonging to a block
 * @returns BlockAPI instance or undefined if not found
 */
getBlockByElement(element: HTMLElement): BlockAPI | undefined;

/**
 * Get total number of blocks in editor
 * @returns Count of blocks
 */
getBlocksCount(): number;

// Get first block
const firstBlock = editor.blocks.getBlockByIndex(0);
if (firstBlock) {
  console.log('First block type:', firstBlock.name);
}

// Get block by ID
const block = editor.blocks.getById('block-id-123');

// Get current block
const currentIndex = editor.blocks.getCurrentBlockIndex();
const currentBlock = editor.blocks.getBlockByIndex(currentIndex);

// Find block containing an element
const element = document.querySelector('.my-block-element');
const block = editor.blocks.getBlockByElement(element);

// Get total count
const totalBlocks = editor.blocks.getBlocksCount();
console.log(`Editor has ${totalBlocks} blocks`);

/**
 * Delete block by index
 * @param index - Block index to delete (default: current block)
 */
delete(index?: number): void;

/**
 * Move block to new position
 * @param toIndex - Target position
 * @param fromIndex - Source position (default: current block)
 */
move(toIndex: number, fromIndex?: number): void;

/**
 * Swap two blocks (deprecated - use move instead)
 * @param fromIndex - First block index
 * @param toIndex - Second block index
 * @deprecated Use move() method instead
 */
swap(fromIndex: number, toIndex: number): void;

/**
 * Update block data by ID
 * @param id - Block ID to update
 * @param data - New data (can be partial)
 * @param tunes - Block tunes data
 * @returns Promise resolving to updated BlockAPI
 */
update(
  id: string, 
  data?: Partial<BlockToolData>, 
  tunes?: {[name: string]: BlockTuneData}
): Promise<BlockAPI>;

/**
 * Convert block to another type
 * @param id - Block ID to convert
 * @param newType - Target block type
 * @param dataOverrides - Optional data for new block type
 * @returns Promise resolving to converted BlockAPI
 * @throws Error if conversion is not possible
 */
convert(
  id: string, 
  newType: string, 
  dataOverrides?: BlockToolData
): Promise<BlockAPI>;

// Delete current block
editor.blocks.delete();

// Delete specific block
editor.blocks.delete(2);

// Move block from position 0 to position 3
editor.blocks.move(3, 0);

// Move current block to position 1
editor.blocks.move(1);

// Update block data
await editor.blocks.update('block-id-123', {
  text: 'Updated content'
});

// Update with tunes
await editor.blocks.update('block-id-123', 
  { text: 'Updated content' },
  { textAlignment: { alignment: 'center' } }
);

// Convert paragraph to header
try {
  const convertedBlock = await editor.blocks.convert(
    'block-id-123',
    'header',
    { text: 'Now a header', level: 2 }
  );
  console.log('Converted successfully:', convertedBlock.name);
} catch (error) {
  console.error('Conversion failed:', error.message);
}

/**
 * Create empty block data for specified tool
 * @param toolName - Name of the tool to create data for
 * @returns Promise resolving to empty BlockToolData
 */
composeBlockData(toolName: string): Promise<BlockToolData>;

/**
 * Mark block as stretched (deprecated - use BlockAPI.stretched instead)
 * @param index - Block index
 * @param status - Stretch state
 */
stretchBlock(index: number, status?: boolean): void;

// Create empty block data
const emptyData = await editor.blocks.composeBlockData('paragraph');
console.log('Empty paragraph data:', emptyData);

// Use with insert
const newBlock = editor.blocks.insert('paragraph', emptyData);

interface BlockAPI {
  // Read-only properties
  readonly id: string;
  readonly name: string;
  readonly config: ToolConfig;
  readonly holder: HTMLElement;
  readonly isEmpty: boolean;
  readonly selected: boolean;
  readonly focusable: boolean;
  
  // Mutable properties
  stretched: boolean;
  
  // Methods
  call(methodName: string, param?: object): void;
  save(): Promise<void | SavedData>;
  validate(data: BlockToolData): Promise<boolean>;
  dispatchChange(): void;
  getActiveToolboxEntry(): Promise<ToolboxConfigEntry | undefined>;
}

const block = editor.blocks.getBlockByIndex(0);

if (block) {
  // Access properties
  console.log('Block ID:', block.id);
  console.log('Block type:', block.name);
  console.log('Is empty:', block.isEmpty);
  
  // Modify stretch state
  block.stretched = true;
  
  // Save block data
  const data = await block.save();
  
  // Validate data
  const isValid = await block.validate(data);
  
  // Trigger change event
  block.dispatchChange();
  
  // Call tool method safely
  block.call('customMethod', { param: 'value' });
}

interface OutputBlockData<Type extends string = string, Data extends object = any> {
  id?: string;
  type: Type;
  data: BlockToolData<Data>;
  tunes?: {[name: string]: BlockTuneData};
}

interface BlockToolData<T extends object = any> extends T {}

interface ToolConfig {
  [key: string]: any;
}

interface BlockTuneData {
  [key: string]: any;
}

interface SavedData {
  [key: string]: any;
}

interface ToolboxConfigEntry {
  icon?: string;
  title?: string;
  data?: BlockToolData;
}