package openidea:plugin@1.0.0;

/// Workbench events, delivered in batches to `event-handler.handle`.
interface events {
    use types.{error};

    enum event-kind {
        file-opened,
        file-saved,
        /// The focused editor changed.
        editor-focused,
        /// An IDE action ran. Requires `events.input`.
        action-performed,
        /// A repository's state changed (commit, checkout, fetch, …).
        vcs-changed,
        /// The plugin's `on-schedule` period elapsed.
        scheduled,
    }

    /// How the user started an action.
    enum action-source {
        keyboard,
        menu,
        toolbar,
        context-menu,
        search,
        other,
    }

    record action-performed {
        /// Action id (`editor.duplicate-line`).
        action: string,
        title: string,
        source: action-source,
        /// Its keyboard shortcut, when it has one (`Ctrl+D`).
        shortcut: option<string>,
    }

    variant event {
        file-opened(string),
        file-saved(string),
        editor-focused(option<string>),
        action-performed(action-performed),
        vcs-changed(string),
        scheduled,
    }

    /// Delivers `kind` events from now on, for the rest of the session (also
    /// across idle reclaim: an event activates the plugin again). Declare
    /// `activation = ["on-event:<kind>"]` to get them before first use.
    /// Requires `events` (`events.input` for `action-performed`).
    subscribe: func(kind: event-kind) -> result<_, error>;
    unsubscribe: func(kind: event-kind);
}

/// Long-running work with a progress indicator. While a task is open, the
/// call that began it may run for the background budget (60 s) instead of 5 s.
interface tasks {
    resource task {
        /// `done` of `total` units (`none`: indeterminate), with a short status.
        report: func(done: u32, total: option<u32>, message: option<string>);
        /// The user cancelled it: stop soon and return.
        is-cancelled: func() -> bool;
    }

    /// Starts a task shown in the status bar; dropping it ends it.
    begin: func(title: string, cancellable: bool) -> task;
}