// src/plugin/types.ts

import type { Editor } from './editor'
import type { MarkdownView } from './views/markdown-view'
import type { MarkdownFileInfo } from './obsidian-cm6-stubs'

/**
 * Plugin manifest metadata.
 */
export interface PluginManifest {
  /** Unique plugin ID */
  id: string
  /** Display name */
  name: string
  /** Author name */
  author: string
  /** Semantic version string */
  version: string
  /** Minimum app version required */
  minAppVersion: string
  /** Plugin description */
  description: string
  /** Optional author URL */
  authorUrl?: string
  /** Whether plugin is desktop-only */
  isDesktopOnly?: boolean
  /** Plugin directory path (set by system) */
  dir?: string
}

/**
 * Command definition for the command palette.
 * @public
 */
export interface Command {
  /**
   * Globally unique ID to identify this command.
   * @public
   */
  id: string
  /**
   * Human friendly name for searching.
   * @public
   */
  name: string
  /**
   * Icon ID to be used in the toolbar.
   * @public
   */
  icon?: string
  /**
   * @public
   */
  mobileOnly?: boolean
  /**
   * Whether holding the hotkey should repeatedly trigger this command.
   * @defaultValue false
   * @public
   */
  repeatable?: boolean
  /**
   * Simple callback, triggered globally.
   * @public
   */
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  callback?: () => any
  /**
   * Complex callback, overrides the simple callback.
   * Used to 'check' whether your command can be performed in the current circumstances.
   *
   * @param checking - Whether the command palette is just 'checking' if your command should show right now.
   * If checking is true, then this function should not perform any action.
   * If checking is false, then this function should perform the action.
   * @returns Whether this command can be executed at the moment.
   * @public
   */
  checkCallback?: (checking: boolean) => boolean | void
  /**
   * A command callback that is only triggered when the user is in an editor.
   * Overrides `callback` and `checkCallback`
   * @public
   * @since 0.12.2
   */
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  editorCallback?: (editor: Editor, ctx: MarkdownView | MarkdownFileInfo) => any
  /**
   * A command callback that is only triggered when the user is in an editor.
   * Overrides `editorCallback`, `callback` and `checkCallback`
   * @public
   * @since 0.12.2
   */
  editorCheckCallback?: (checking: boolean, editor: Editor, ctx: MarkdownView | MarkdownFileInfo) => boolean | void
  /**
   * Sets the default hotkey. It is recommended for plugins to avoid setting default hotkeys if possible,
   * to avoid conflicting hotkeys with one that's set by the user, even though customized hotkeys have higher priority.
   * @public
   */
  hotkeys?: Hotkey[]
}

/**
 * Hotkey definition.
 */
export interface Hotkey {
  /** Modifier keys */
  modifiers: Modifier[]
  /** Key to press */
  key: string
}

/**
 * Modifier keys.
 */
export type Modifier = 'Mod' | 'Ctrl' | 'Meta' | 'Shift' | 'Alt'

/**
 * User input events for keyboard, mouse, touch, and pointer interactions.
 * @public
 * @since 0.12.17
 */
export type UserEvent = MouseEvent | KeyboardEvent | TouchEvent | PointerEvent

/**
 * Specifies where a new pane should be opened.
 * - 'tab': new tab in current split
 * - 'split': new split pane
 * - 'window': new popup window
 * @public
 * @since 0.16.0
 */
export type PaneType = 'tab' | 'split' | 'window'

/**
 * Editor position (line and character).
 */
export interface EditorPosition {
  line: number
  ch: number
}

/**
 * Editor selection range.
 */
export interface EditorRange {
  from: EditorPosition
  to: EditorPosition
}

/**
 * @public
 * @since 0.12.11
 */
export interface EditorRangeOrCaret {
  /** @public */
  from: EditorPosition
  /** @public */
  to?: EditorPosition
}

/**
 * @public
 * @since 0.12.11
 */
export interface EditorChange extends EditorRangeOrCaret {
  /** @public */
  text: string
}

/**
 * Editor selection with anchor and head.
 */
export interface EditorSelection {
  anchor: EditorPosition
  head: EditorPosition
}

/**
 * @public
 * @since 0.15.0
 */
export interface EditorScrollInfo {
  /** @public */
  left: number
  /** @public */
  top: number
  /** @public */
  width: number
  /** @public */
  height: number
  /** @public */
  clientWidth: number
  /** @public */
  clientHeight: number
}

/**
 * Editor selection or caret. Like EditorSelection but head is optional.
 * When head is omitted, the selection is a caret (cursor) at anchor.
 * @public
 * @since 0.12.11
 */
export interface EditorSelectionOrCaret {
  /** @public */
  anchor: EditorPosition
  /** @public */
  head?: EditorPosition
}

/**
 * Editor command name for `Editor.exec()`.
 * @public
 */
export type EditorCommandName =
  | 'goUp'
  | 'goDown'
  | 'goLeft'
  | 'goRight'
  | 'goStart'
  | 'goEnd'
  | 'goWordLeft'
  | 'goWordRight'
  | 'indentMore'
  | 'indentLess'
  | 'newlineAndIndent'
  | 'swapLineUp'
  | 'swapLineDown'
  | 'deleteLine'
  | 'toggleFold'
  | 'foldAll'
  | 'unfoldAll'

/**
 * Editor transaction for atomic updates.
 *
 * Matches upstream Obsidian's EditorTransaction interface.
 *
 * @public
 * @since 0.12.2
 */
export interface EditorTransaction {
  /** @public */
  replaceSelection?: string
  /** @public */
  selection?: EditorRangeOrCaret
  /** @public */
  selections?: EditorRangeOrCaret[]
  /** @public */
  changes?: EditorChange[]
}

/**
 * View creator function type.
 */
import type { View } from './views/view'
import type { WorkspaceLeaf } from './workspace'

export type ViewCreator = (leaf: WorkspaceLeaf) => View

/**
 * Context passed to MarkdownPostProcessors.
 * Matches Obsidian's MarkdownPostProcessorContext shape.
 */
export interface MarkdownPostProcessorContext {
  /** The document ID (per-render unique). */
  docId: string
  /** Source file path */
  sourcePath: string
  /**
   * Frontmatter if any.
   * @public
   */
  frontmatter: any | null | undefined
  /**
   * Add a MarkdownRenderChild whose lifecycle is tied to this render.
   * The child's load() fires immediately, and unload() fires when the
   * parent component unloads.
   *
   * Signature matches Obsidian's d.ts exactly: only MarkdownRenderChild
   * (or a subclass) is accepted. Plain Components are not, to preserve
   * compatibility with plugins compiled against the official Obsidian types.
   */
  addChild(child: import('./markdown-render-child').MarkdownRenderChild): void
  /**
   * Gets the section information of this element at this point in time.
   * Only call this function right before you need this information to get the most up-to-date version.
   * This function may also return null in many circumstances; if you use it, you must be prepared to deal with nulls.
   * @public
   */
  getSectionInfo(el: HTMLElement): import('./obsidian-stubs').MarkdownSectionInformation | null
}

/**
 * A post processor receives an element which is a section of the preview.
 *
 * Post processors can mutate the DOM to render various things, such as mermaid graphs, latex equations, or custom controls.
 *
 * If your post processor requires lifecycle management, for example, to clear an interval, kill a subprocess, etc when this element is
 * removed from the app, look into {@link MarkdownPostProcessorContext.addChild}
 * @public
 * @since 0.10.12
 */
export interface MarkdownPostProcessor {
  /**
   * The processor function itself.
   * @public
   */
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  (el: HTMLElement, ctx: MarkdownPostProcessorContext): Promise<any> | void
  /**
   * An optional integer sort order. Defaults to 0. Lower number runs before higher numbers.
   * @public
   */
  sortOrder?: number
}

/**
 * Open-view state passed to `Workspace.openLinkText` and
 * `WorkspaceLeaf.openFile`. Obsidian-compatible shape.
 *
 * - `active`: whether to focus the new leaf. Defaults to true. Set to
 *   false to open without stealing focus from the editor.
 * - `state`: view-specific state payload passed to `view.setState`.
 *   Shape is per view type; markdown view accepts `{ mode, source }` etc.
 * - `eState`: ephemeral state (typically scroll position / line). Reams
 *   uses `eState.line` (0-indexed) and `eState.subpath` (`#heading` or
 *   `^block`) to drive `scrollActiveEditorToLine` after open.
 * - `group`: link to another leaf for synced scrolling. Reams accepts the
 *   key for plugin-API compatibility but does not implement linked-pane
 *   scrolling — logs a warning when provided.
 */
export interface OpenViewState {
  active?: boolean
  state?: Record<string, unknown>
  eState?: Record<string, unknown>
  group?: WorkspaceLeaf
}