Utility Functions

/**
 * Main utility plugin providing image detection and manipulation functions
 */
class ImageUtils {
  static pluginName: 'ImageUtils';
  static isOfficialPlugin: true;
  
  /**
   * Check if model element is an image (block or inline)
   * @param modelElement - Element to check
   * @returns True if element is an image
   */
  isImage(modelElement?: ModelElement | null): boolean;
  
  /**
   * Check if model element is specifically an inline image
   * @param modelElement - Element to check
   * @returns True if element is inline image
   */
  isInlineImage(modelElement?: ModelElement | null): boolean;
  
  /**
   * Check if model element is specifically a block image
   * @param modelElement - Element to check
   * @returns True if element is block image
   */
  isBlockImage(modelElement?: ModelElement | null): boolean;
  
  /**
   * Insert image at specified position with given attributes
   * @param attributes - Image attributes (src, alt, etc.)
   * @param selectable - Position to insert at (ModelSelection | ModelPosition | null)
   * @param imageType - 'imageBlock' | 'imageInline' | null - if null, determined automatically
   * @param options - Additional insertion options including setImageSizes
   * @returns Inserted image element or null
   */
  insertImage(
    attributes: Record<string, unknown> = {},
    selectable: ModelSelection | ModelPosition | null = null,
    imageType: 'imageBlock' | 'imageInline' | null = null,
    options: { setImageSizes?: boolean } = {}
  ): ModelElement | null;
  
  /**
   * Get closest selected image widget in view
   * @param selection - Current selection
   * @returns Image widget element or null
   */
  getClosestSelectedImageWidget(selection: any): ViewElement | null;
  
  /**
   * Get closest selected image element in model
   * @param selection - Current selection
   * @returns Image model element or null
   */
  getClosestSelectedImageElement(selection: any): ModelElement | null;
}

import { ImageUtils } from '@ckeditor/ckeditor5-image';

const imageUtils = editor.plugins.get('ImageUtils');

// Check if element is an image
const selection = editor.model.document.selection;
const element = selection.getSelectedElement();

if (imageUtils.isImage(element)) {
  console.log('Selected element is an image');
  
  if (imageUtils.isBlockImage(element)) {
    console.log('It is a block image');
  } else if (imageUtils.isInlineImage(element)) {
    console.log('It is an inline image');
  }
}

// Insert image programmatically
const imageElement = imageUtils.insertImage(
  { src: 'https://example.com/image.jpg', alt: 'Example image' },
  editor.model.document.selection,
  'imageBlock'
);

// Get selected image for operations
const selectedImage = imageUtils.getClosestSelectedImageElement(
  editor.model.document.selection
);

if (selectedImage) {
  console.log('Image source:', selectedImage.getAttribute('src'));
  console.log('Image alt text:', selectedImage.getAttribute('alt'));
}

/**
 * Create inline image view element
 * @param writer - View writer
 * @param attributes - Image attributes
 * @returns Inline image view element
 */
function _createInlineImageViewElement(
  writer: any,
  attributes: { src: string; alt?: string; [key: string]: any }
): ViewElement;

/**
 * Create block image view element with figure wrapper
 * @param writer - View writer  
 * @param attributes - Image attributes
 * @returns Block image view element
 */
function _createBlockImageViewElement(
  writer: any,
  attributes: { src: string; alt?: string; [key: string]: any }
): ViewElement;

// In view conversion or custom functionality
editor.editing.view.change(writer => {
  // Create inline image element
  const inlineImage = _createInlineImageViewElement(writer, {
    src: 'image.jpg',
    alt: 'Description',
    width: '100px'
  });
  
  // Create block image element
  const blockImage = _createBlockImageViewElement(writer, {
    src: 'image.jpg',
    alt: 'Description',
    class: 'custom-image'
  });
});

/**
 * Get matcher for image view elements
 * @param imageType - 'imageBlock', 'imageInline', or both
 * @returns Matcher function for view elements
 */
function _getImageViewElementMatcher(imageType?: string): any;

/**
 * Determine appropriate image type for insertion at selection
 * @param model - Editor model
 * @param selection - Current selection
 * @returns 'imageBlock' or 'imageInline'
 */
function _determineImageTypeForInsertionAtSelection(
  model: any,
  selection: any
): 'imageBlock' | 'imageInline';

// Get appropriate image type for current position
const selection = editor.model.document.selection;
const imageType = _determineImageTypeForInsertionAtSelection(
  editor.model,
  selection
);

console.log('Should insert as:', imageType);

// Use in image insertion
editor.execute('insertImage', {
  source: 'image.jpg',
  imageType: imageType
});

/**
 * Check if image source is a local file
 * @param src - Image source URL or data
 * @returns True if image is local
 */
function _isLocalImage(src: string): boolean;

/**
 * Fetch local image and convert to data URL
 * @param image - Image element or source
 * @returns Promise resolving to data URL
 */
function _fetchLocalImage(image: string | HTMLImageElement): Promise<string>;

// Handle local images
const imageSrc = 'blob:http://localhost:3000/image-id';

if (_isLocalImage(imageSrc)) {
  console.log('Image is local');
  
  // Convert to data URL for upload
  _fetchLocalImage(imageSrc).then(dataUrl => {
    console.log('Converted to data URL:', dataUrl);
    // Can now upload or process the image
  });
}

/**
 * Upcast converter for figure elements containing images
 * @param imageUtils - ImageUtils plugin instance
 * @returns Upcast converter configuration
 */
function _upcastImageFigure(imageUtils: ImageUtils): any;

/**
 * Upcast converter for HTML5 picture elements
 * @param imageUtils - ImageUtils plugin instance
 * @returns Upcast converter configuration
 */
function _upcastImagePicture(imageUtils: ImageUtils): any;

/**
 * Downcast converter for srcset attribute
 * @returns Downcast converter configuration
 */
function _downcastImageSrcsetAttribute(): any;

/**
 * Downcast converter for picture sources attribute
 * @returns Downcast converter configuration
 */
function _downcastImageSourcesAttribute(): any;

/**
 * Downcast converter for generic image attributes
 * @param attributeName - Name of attribute to convert
 * @returns Downcast converter configuration
 */
function _downcastImageAttribute(attributeName: string): any;

/**
 * Get selected image editor nodes (model and view)
 * @param editor - Editor instance
 * @returns Object with model and view elements
 */
function _getSelectedImageEditorNodes(editor: any): {
  model: ModelElement | null;
  view: ViewElement | null;
};

/**
 * Get possible resize range for selected image
 * @param editor - Editor instance
 * @returns Resize range information
 */
function _getSelectedImagePossibleResizeRange(editor: any): {
  unit: 'px' | '%';
  lower: number;
  upper: number;
} | null;

// Get selected image elements
const { model, view } = _getSelectedImageEditorNodes(editor);

if (model && view) {
  console.log('Model element:', model.name);
  console.log('View element:', view.name);
  
  // Get resize range
  const resizeRange = _getSelectedImagePossibleResizeRange(editor);
  if (resizeRange) {
    console.log('Can resize from', resizeRange.lower, 'to', resizeRange.upper, resizeRange.unit);
  }
}

/**
 * Get positioning data for image contextual balloon
 * @param editor - Editor instance
 * @returns Positioning configuration object
 */
function _getImageBalloonPositionData(editor: any): {
  target: any;
  positions: Array<any>;
};

/**
 * Reposition image contextual balloon
 * @param editor - Editor instance
 */
function _repositionImageContextualBalloon(editor: any): void;

// Custom balloon positioning
const positionData = _getImageBalloonPositionData(editor);
console.log('Balloon target:', positionData.target);

// Manually reposition balloon
_repositionImageContextualBalloon(editor);

// Use in custom UI
editor.plugins.get('ContextualBalloon').add({
  view: customFormView,
  position: positionData
});

/** Default image style options */
const _IMAGE_DEFAULT_OPTIONS: Array<any>;

/** Default image style icons */
const _IMAGE_DEFAULT_ICONS: { [key: string]: string };

/** Default image style dropdown definitions */
const _IMAGE_DEFAULT_DROPDOWN_DEFINITIONS: Array<any>;

// Access default configurations
console.log('Default image options:', _IMAGE_DEFAULT_OPTIONS);
console.log('Available icons:', _IMAGE_DEFAULT_ICONS);

// Use in custom style configuration
const customStyles = [
  ..._IMAGE_DEFAULT_OPTIONS,
  {
    name: 'customStyle',
    icon: _IMAGE_DEFAULT_ICONS.center,
    title: 'Custom Style'
  }
];