@mnaoumov/obsidian-lib 0.0.0 → 1.0.1

package/dist/lib/esm/plugin/plugin.d.mts

@@ -0,0 +1,363 @@
+/// <reference path="../library.d.mts" />
+/**
+ * @file
+ *
+ * Base class for Obsidian plugins using a component-based architecture.
+ *
+ * PluginBase registers universal components (context, i18n, error handling, abort signal, lifecycle events, debug).
+ */
+import type { Component, IconName } from 'obsidian';
+import type { Promisable } from 'type-fest';
+import { Plugin } from 'obsidian';
+import type { PluginConflict, PluginDependency } from '../components/plugin-gate-component.mjs';
+import type { TranslationsMap } from '../i18n/i18n.mjs';
+import type { PluginApiDeclaration } from './plugin-api.mjs';
+import type { PluginEventMap, PluginEventSource } from './plugin-event-source.mjs';
+import { CommandHandlerComponent } from '../command-handlers/command-handler-component.mjs';
+import { AbortSignalComponent } from '../components/abort-signal-component.mjs';
+import { AsyncErrorHandlerComponent } from '../components/async-error-handler-component.mjs';
+import { ConsoleDebugComponent } from '../components/console-debug-component.mjs';
+import { PluginContextComponent } from '../components/plugin-context-component.mjs';
+import { PluginGateComponent } from '../components/plugin-gate-component.mjs';
+import { PluginNoticeComponent } from '../components/plugin-notice-component.mjs';
+import { PluginSettingsComponentBase } from '../components/plugin-settings-component.mjs';
+import { ResourceLockComponent } from '../resource-lock.mjs';
+declare const PluginBase_base: import("type-fest").AbstractConstructor<import("@mnaoumov/typescript-lib/async-events").AsyncEventSource<PluginEventMap> & import("@mnaoumov/typescript-lib/async-events").AsyncEventTrigger<PluginEventMap>> & typeof Plugin;
+/**
+ * Base class for creating Obsidian plugins with a component-based architecture.
+ *
+ * Registers universal components automatically. Subclasses add or replace components
+ * via {@link removeChild} / {@link addChild}.
+ */
+export declare abstract class PluginBase extends PluginBase_base implements PluginEventSource {
+    /**
+     * Gets abort signal component.
+     *
+     * @returns abort signal component.
+     */
+    protected get abortSignalComponent(): AbortSignalComponent;
+    /**
+     * Sets abort signal component.
+     *
+     * @param value - Abort signal component.
+     */
+    protected set abortSignalComponent(value: AbortSignalComponent);
+    /**
+     * Gets async error handler component.
+     *
+     * @returns async error handler component.
+     */
+    protected get asyncErrorHandlerComponent(): AsyncErrorHandlerComponent;
+    /**
+     * Sets async error handler component.
+     *
+     * @param value - Async error handler component.
+     */
+    protected set asyncErrorHandlerComponent(value: AsyncErrorHandlerComponent);
+    /**
+     * Gets the shared command handler component. Register a plugin's commands on it via
+     * {@link CommandHandlerComponent.registerCommandHandlers} rather than constructing your own
+     * {@link CommandHandlerComponent} — the app-backed active-file provider, command registrar, menu
+     * event registrar, and plugin name are already wired.
+     *
+     * @returns The command handler component.
+     */
+    protected get commandHandlerComponent(): CommandHandlerComponent;
+    /**
+     * Sets the command handler component.
+     *
+     * @param value - The command handler component.
+     */
+    protected set commandHandlerComponent(value: CommandHandlerComponent);
+    /**
+     * Gets console debug component.
+     *
+     * @returns console debug component.
+     */
+    protected get consoleDebugComponent(): ConsoleDebugComponent;
+    /**
+     * Sets console debug component.
+     *
+     * @param value - Console debug component.
+     */
+    protected set consoleDebugComponent(value: ConsoleDebugComponent);
+    /**
+     * Gets plugin context component (plugin ID, debug controller, library styles).
+     *
+     * @returns plugin context component.
+     */
+    protected get pluginContextComponent(): PluginContextComponent;
+    /**
+     * Sets plugin context component.
+     *
+     * @param value - Plugin context component.
+     */
+    protected set pluginContextComponent(value: PluginContextComponent);
+    /**
+     * Gets the gate holding the plugin's feature surface up or down.
+     *
+     * Reach for it from a settings tab to render the overlap banner for a
+     * {@link components/plugin-gate-component!PluginConflictSeverity.Warn} conflict — the one
+     * banner the library cannot place itself, because a running plugin builds its own settings tab.
+     *
+     * Readable throughout {@link onloadImpl}, including its synchronous prefix, which is where a settings
+     * tab is built. That is deliberate rather than incidental: adding the gate is what runs
+     * {@link onloadImpl}, so {@link onload} assigns this field before adding it.
+     *
+     * @returns The plugin gate component.
+     */
+    protected get pluginGateComponent(): PluginGateComponent;
+    /**
+     * Sets the plugin gate component.
+     *
+     * @param value - The plugin gate component.
+     */
+    protected set pluginGateComponent(value: PluginGateComponent);
+    /**
+     * Gets plugin notice component.
+     *
+     * @returns plugin notice component.
+     */
+    protected get pluginNoticeComponent(): PluginNoticeComponent;
+    /**
+     * Sets plugin notice component.
+     *
+     * @param value - Plugin notice component.
+     */
+    protected set pluginNoticeComponent(value: PluginNoticeComponent);
+    /**
+     * Gets plugin settings component.
+     *
+     * @returns plugin settings component.
+     */
+    protected get pluginSettingsComponent(): PluginSettingsComponentBase<object>;
+    /**
+     * Sets plugin settings component.
+     *
+     * @param value - Plugin settings component.
+     */
+    protected set pluginSettingsComponent(value: PluginSettingsComponentBase<object>);
+    /**
+     * Gets the editor lock component, used to lock notes read-only during long operations. Owned by
+     * the plugin, so its locks are released automatically when the plugin unloads.
+     *
+     * @returns Editor lock component.
+     */
+    protected get resourceLockComponent(): ResourceLockComponent;
+    /**
+     * Sets the editor lock component.
+     *
+     * @param value - Editor lock component.
+     */
+    protected set resourceLockComponent(value: ResourceLockComponent);
+    private readonly components;
+    private gatedWrapperComponent;
+    private lifecycleEventPayload;
+    private readonly universalWrapperComponent;
+    /**
+     * Adds a child component.
+     *
+     * The child is added to the internal wrapper holding the subclass's own surface, which {@link onload}
+     * creates and loads before calling {@link onloadImpl}. So a child added during {@link onloadImpl} is
+     * loaded immediately, children-first, and is usable by the time this method returns.
+     *
+     * That wrapper is torn down and rebuilt whenever the gate closes and opens again — a dependency declared
+     * by {@link getPluginDependencies} going away and coming back, or a conflict declared by
+     * {@link getPluginConflicts} appearing and being resolved — so a child added here lives exactly as long
+     * as the plugin's feature surface does. Adding one while the surface is down is still legitimate — it is
+     * queued and loaded when the surface next comes up, the way {@link ComponentEx.addChild} already queues
+     * a child added to a not-yet-loaded component.
+     *
+     * This is the SUBCLASS's door, and the only one it has: the universal components {@link onload} registers
+     * take a private route onto a different wrapper. So anything observing this method — a test counting its
+     * calls, a patch wrapping it — sees exactly the children the subclass added, and none of the library's.
+     * Before the two tiers existed one door carried both, and a consumer counting the total is the one thing
+     * the split could not keep working.
+     *
+     * @typeParam TComponent - The type of component to add.
+     * @param component - The component instance to add.
+     * @returns The added component.
+     */
+    addChild<TComponent extends Component>(component: TComponent): TComponent;
+    /**
+     * Called when the external settings change.
+     *
+     * Override in subclass if needed. Make sure to call `await super.onExternalSettingsChange()` first.
+     */
+    onExternalSettingsChange(): Promise<void>;
+    /**
+     * Called when the plugin is loaded.
+     *
+     * Orchestrates loading: registers the universal components, lets the subclass wire its own
+     * components via {@link onloadImpl}, then awaits the async tail of every load.
+     * Each component loads as it is added, children-first.
+     *
+     * Do NOT override this method. Override {@link onloadImpl} instead.
+     */
+    onload(): Promise<void>;
+    /**
+     * Called when the plugin is unloaded.
+     *
+     * Announces the departure on `app.workspace` so anything depending on this plugin learns of it at the
+     * moment it happens, rather than discovering it later through behavior that quietly stopped.
+     *
+     * Do NOT override this method; put teardown on a component instead, which unloads with the plugin.
+     */
+    onunload(): void;
+    /**
+     * Removes a child component.
+     *
+     * @typeParam TComponent - The type of component to remove.
+     * @param component - The component instance to remove.
+     * @returns The removed component.
+     */
+    removeChild<TComponent extends Component>(component: TComponent): TComponent;
+    /**
+     * Provides the translations map used to initialize i18n during {@link onload}.
+     *
+     * Override in subclass to supply plugin-specific translations. The default returns the built-in
+     * `obsidian-dev-utils` translations.
+     *
+     * @returns The translations map.
+     */
+    protected createTranslationsMap(): TranslationsMap;
+    /**
+     * Provides the icon shown on the plugin's parent entry in Notebook Navigator's context menus.
+     *
+     * Override in subclass to brand that entry; the default leaves it without an icon. The entry is
+     * titled with the plugin name and is added automatically — see
+     * {@link NotebookNavigatorMenuEventRegistrarComponent}.
+     *
+     * @returns The icon, or `''` for no icon.
+     */
+    protected getNotebookNavigatorMenuSubmenuIcon(): IconName;
+    /**
+     * Provides the APIs this plugin exposes to other plugins.
+     *
+     * Override in subclass to publish one. The default publishes none. Called after {@link onloadImpl}, so a
+     * declaration may reference anything it created; the returned declarations are published through
+     * `publishPluginApi` and revoked when the plugin's feature surface unloads.
+     *
+     * Returning a LIST rather than a single API is deliberate: the registry supports several contract
+     * versions published side by side, which is how a provider ships a breaking `2.0.0` without stranding
+     * consumers still pinned to `^1`.
+     *
+     * Every declaration here is published BEFORE the `obsidian-dev-utils:plugin-loaded` broadcast, which is
+     * what lets a listener call these APIs the moment it hears that event.
+     *
+     * @returns The API declarations.
+     */
+    protected getPluginApis(): PluginApiDeclaration[];
+    /**
+     * Provides the plugins this one refuses, or warns about, running beside.
+     *
+     * Override in subclass to declare an overlap. The default declares none.
+     *
+     * A `Block` conflict is the mirror image of a dependency: while a conflicting plugin is enabled at a
+     * conflicting version, {@link onloadImpl} does not run at all and the plugin registers nothing. Declare
+     * it when both plugins acting on the same operation damages the vault — there is no reliable way to win
+     * that race, because whichever plugin loaded first keeps a hand on the wheel, so refusing deterministically
+     * beats competing unpredictably. A `Warn` conflict declares an overlap that is merely annoying, such as a
+     * duplicated command: both plugins keep running and the user is told.
+     *
+     * Unlike a dependency, a conflicting plugin need not publish anything — it is detected by reading its
+     * installed version, which is the only thing about another plugin that reads the same regardless of load
+     * order.
+     *
+     * @returns The declared conflicts.
+     */
+    protected getPluginConflicts(): PluginConflict[];
+    /**
+     * Provides the plugins this one cannot work without.
+     *
+     * Override in subclass to declare a mandatory dependency. The default declares none, and such a plugin
+     * loads exactly as it always has.
+     *
+     * A declared dependency is MANDATORY, unlike the offer `PluginSuggestionComponent` makes: while one is
+     * missing, disabled, or too old, {@link onloadImpl} does not run at all and the plugin registers nothing
+     * — no commands, no handlers, no patches. It stays enabled in Obsidian's list rather than disabling
+     * itself, because the enabled set is the user's to change, and it explains itself through a notice and a
+     * settings banner that installs the missing plugin in one click. The load completes the moment the
+     * dependency arrives, with no restart.
+     *
+     * A dependency must publish an API through `publishPluginApi`, which is what makes its presence,
+     * absence, version and departure all observable through one mechanism. A plugin with nothing to expose
+     * can publish an empty API purely so it can be depended upon.
+     *
+     * @returns The declared dependencies.
+     */
+    protected getPluginDependencies(): PluginDependency[];
+    /**
+     * Called during {@link onload} to wire plugin-specific child components.
+     *
+     * Override in subclass to add child components via {@link addChild}. The universal components are
+     * available here. Children are loaded sequentially in the order they are added (children-first).
+     *
+     * @returns A {@link Promise} that resolves when the subclass load logic is complete.
+     */
+    protected onloadImpl(): Promisable<void>;
+    /**
+     * Stores a universal component, unloading whichever component the key held before.
+     *
+     * Keyed by name rather than handed the previous value because `keyof this` excludes private
+     * members, so the components live in a single {@link PluginBaseComponents} bag whose keys ARE
+     * indexable.
+     *
+     * @typeParam TKey - The key of the component to store.
+     * @param key - The key of the component to store.
+     * @param value - The component to store.
+     */
+    /**
+     * Adds a component to the universal tier, which outlives any dependency.
+     *
+     * Private on purpose: only this class decides what is universal. A subclass adding one of its own goes
+     * through {@link addChild} and lands in the gated tier, where it belongs.
+     *
+     * @typeParam TComponent - The type of component to add.
+     * @param component - The component instance to add.
+     * @returns The added component.
+     */
+    private addUniversalChild;
+    /**
+     * Announces on `app.workspace` that this plugin is loaded and its APIs are callable.
+     */
+    private broadcastLoaded;
+    /**
+     * Announces on `app.workspace` that this plugin's surface has gone away.
+     *
+     * Silent unless a loaded broadcast is outstanding, so the two events stay paired: a plugin that never
+     * got past its dependency gate never announced itself, and must not announce a departure either.
+     */
+    private broadcastUnloaded;
+    /**
+     * Builds and loads the subclass's feature surface, then publishes its APIs and announces itself.
+     *
+     * NOT idempotent, deliberately. `PluginGateComponent` owns the up/down state machine and calls
+     * this only on a real transition; a second guard here would be a second copy of that state, which is the
+     * kind of duplicate that drifts.
+     *
+     * @returns A {@link Promise} that resolves once the surface is loaded and the broadcast has been made.
+     */
+    private loadFeatureSurface;
+    private setComponent;
+    /**
+     * Tears the subclass's feature surface down, leaving the universal components running.
+     */
+    private unloadFeatureSurface;
+}
+/**
+ * Reloads the specified plugin by disabling and then re-enabling it.
+ *
+ * @param plugin - The plugin to reload.
+ * @returns A {@link Promise} that resolves when the plugin is reloaded.
+ */
+export declare function reloadPlugin(plugin: Plugin): Promise<void>;
+/**
+ * Displays an error message as a notice, logs it to the console, and disables the specified plugin.
+ *
+ * @param plugin - The plugin to disable.
+ * @param message - The error message to display and log.
+ * @returns A {@link Promise} that resolves when the plugin is disabled.
+ */
+export declare function showErrorAndDisablePlugin(plugin: Plugin, message: string): Promise<void>;
+export {};