@mnaoumov/obsidian-lib 0.0.0 → 1.0.0

package/dist/lib/cjs/command-handlers/command-handler-component.d.cts

@@ -0,0 +1,146 @@
+/// <reference path="../library.d.cts" />
+/**
+ * @file
+ *
+ * Component that registers {@link CommandHandler}s with Obsidian and ties their removal to a chosen lifetime.
+ */
+import type { DisposableEx } from '@mnaoumov/typescript-lib/disposable' with { 'resolution-mode': 'import' };
+import type { ActiveFileProvider } from '../active-file-provider.cjs';
+import type { CommandRegistrar } from '../command-registrar.cjs';
+import type { MenuEventRegistrar } from '../menu-event-registrar.cjs';
+import type { CommandHandler } from './command-handler.cjs';
+import { ComponentEx } from '../components/component-ex.cjs';
+/**
+ * Builds a fresh set of {@link CommandHandler}s.
+ *
+ * A factory rather than a ready-made array because {@link CommandHandlerComponent} registers the same
+ * handlers against several menu surfaces, and a handler carries per-registration state (its
+ * active-file provider, its plugin name, and whatever a subclass records in
+ * {@link CommandHandler.onRegistered}) — so every surface needs its own instances.
+ *
+ * Returning shared instances (`() => [handler1Singleton, handler2Singleton]`) reintroduces exactly the
+ * bug the factory exists to avoid, so it is not merely discouraged: {@link CommandHandler.onRegistered}
+ * throws on the second registration of an instance. {@link CommandHandlerComponent.registerCommandHandlers}
+ * awaits it, so that throw rejects the caller's promise instead of degrading into a wrong context menu.
+ *
+ * @returns The command handlers to register. A NEW instance of each on every call.
+ */
+export type CommandHandlerFactory = () => CommandHandler[];
+interface CommandHandlerComponentConstructorParams {
+    readonly activeFileProvider: ActiveFileProvider;
+    readonly additionalMenuEventRegistrars?: readonly MenuEventRegistrar[] | undefined;
+    /**
+     * Resolves the lifetime owner for a registration that names none of its own.
+     *
+     * When omitted, every registration is owned by the component itself, so its unload removes every command
+     * it registered — the behavior a standalone component has always had. No `@default` tag, because the
+     * effective default is a closure over `this` rather than a literal or a linkable symbol.
+     */
+    readonly commandLifetimeOwnerProvider?: CommandLifetimeOwnerProvider | undefined;
+    readonly commandRegistrar: CommandRegistrar;
+    readonly menuEventRegistrar: MenuEventRegistrar;
+    readonly pluginName: string;
+}
+interface CommandHandlerComponentRegisterCommandHandlersOptions {
+    /**
+     * The component whose unload removes the commands this call registers, overriding the component's
+     * {@link CommandLifetimeOwnerProvider} for this one call.
+     *
+     * Name one when the batch's lifetime differs from the default — the caller that needs it is one
+     * registering through a component whose default owner is some SHORTER-lived surface, and whose own
+     * commands have to outlive it.
+     */
+    readonly lifetimeOwner?: ComponentEx | undefined;
+}
+/**
+ * Resolves the component that owns the teardown of the commands a {@link CommandHandlerComponent.registerCommandHandlers}
+ * call registers — the one whose unload removes them from the palette.
+ *
+ * A provider rather than a component, because the owner is not stable for the life of the registering
+ * component. `PluginBase` hands back the wrapper holding the plugin's feature surface, and that wrapper is
+ * REPLACED wholesale every time the surface goes down and comes back (a declared dependency lost and
+ * regained, a declared conflict appearing and being resolved). A value captured once would tie the second
+ * cycle's commands to the first cycle's dead wrapper, where nothing would ever dispose them.
+ *
+ * @returns The component that should own the registration's teardown.
+ */
+type CommandLifetimeOwnerProvider = () => ComponentEx;
+/**
+ * Registers {@link CommandHandler}s with Obsidian and manages their lifecycle.
+ *
+ * Call {@link registerCommandHandlers} to register a batch of handlers on demand (as many times as
+ * needed while the component is alive); dispose the returned {@link DisposableEx} to unregister exactly
+ * those handlers — including any menu events they registered — or let the batch's LIFETIME OWNER unload to
+ * remove every command still registered through it.
+ *
+ * That owner is this component by default, which is why a standalone component removes its own commands
+ * when it unloads. It is overridable because the registering component and the registered commands do not
+ * always share a lifetime: `PluginBase` keeps ONE of these running for the whole life of the plugin — it is
+ * what the "your dependency went away" notice is built beside — while the commands a subclass registers from
+ * `onloadImpl` belong to the feature surface the gate tears down and rebuilds underneath it. So the owner is
+ * resolved per call, from a {@link CommandLifetimeOwnerProvider} or from the call's own `lifetimeOwner`.
+ *
+ * The same handlers are fed to every menu surface the component knows about: Obsidian's own workspace
+ * events, plus each additional {@link MenuEventRegistrar} bridging another plugin's menus.
+ */
+export declare class CommandHandlerComponent extends ComponentEx {
+    /**
+     * Provider for accessing the currently active file.
+     */
+    protected readonly activeFileProvider: ActiveFileProvider;
+    /**
+     * Registrars for menu surfaces that build their own plugin-titled parent entry, and therefore take
+     * the handlers with their section submenu forced off.
+     */
+    protected readonly additionalMenuEventRegistrars: readonly MenuEventRegistrar[];
+    /**
+     * Registrar used to add and remove commands with Obsidian.
+     */
+    protected readonly commandRegistrar: CommandRegistrar;
+    /**
+     * Registrar for menu event handlers.
+     */
+    protected readonly menuEventRegistrar: MenuEventRegistrar;
+    /**
+     * The name of the plugin that owns the commands.
+     */
+    protected readonly pluginName: string;
+    private readonly commandLifetimeOwnerProvider;
+    /**
+     * Creates a new command handler component.
+     *
+     * @param params - The constructor parameters.
+     */
+    constructor(params: CommandHandlerComponentConstructorParams);
+    /**
+     * Builds the command handlers and registers them with Obsidian, giving each its own runtime
+     * registration context. Each handler's command is added immediately; the returned
+     * {@link DisposableEx} removes the commands registered by this call — and any menu events those
+     * handlers registered via their context's {@link MenuEventRegistrar} — when disposed. Any command
+     * still registered when the component unloads is removed automatically.
+     *
+     * The factory is invoked once more for every additional menu surface, so a plugin declares its
+     * handlers ONCE and all surfaces are fed. Those extra passes add no commands — the palette already
+     * has every command from the first pass.
+     *
+     * Which component's unload removes them is the caller's to choose: `options.lifetimeOwner` for this one
+     * batch, otherwise whatever this component's {@link CommandLifetimeOwnerProvider} resolves to, which
+     * defaults to the component itself. A command must never outlive the collaborators its handler closes
+     * over — left on a longer-lived owner it stays in the palette calling into torn-down objects — so the
+     * owner to name is the shortest-lived thing the batch depends on.
+     *
+     * @param commandHandlerFactory - Builds a fresh set of command handlers, once per menu surface.
+     * @param options - The registration options.
+     * @returns A {@link DisposableEx} that unregisters the handlers (commands + menu events) registered by this call.
+     */
+    registerCommandHandlers(commandHandlerFactory: CommandHandlerFactory, options?: CommandHandlerComponentRegisterCommandHandlersOptions): Promise<DisposableEx>;
+    /**
+     * Hands a command handler its registration context, scoped so that disposing the returned scope
+     * unregisters exactly the menu events that handler registered.
+     *
+     * @param params - The parameters for this registration.
+     * @returns The handler's menu-event scope.
+     */
+    private registerMenuEventHandlers;
+}
+export {};

package/dist/lib/cjs/command-handlers/command-handler.cjs

@@ -0,0 +1,224 @@
+/*
+THIS IS A GENERATED/BUNDLED FILE BY ESBUILD
+if you want to view the source, please visit the github repository of this plugin
+*/
+
+(function () {
+function ensureDisposeSymbols(symbolConstructor = Symbol) {
+  symbolConstructor.asyncDispose ??= symbolConstructor.for('Symbol.asyncDispose');
+  symbolConstructor.dispose ??= symbolConstructor.for('Symbol.dispose');
+}
+
+function ensureBrowserProcess() {
+  const browserProcess = {
+    browser: true,
+    cwd() {
+      return '/';
+    },
+    env: {},
+    platform: 'android'
+  };
+
+  // eslint-disable-next-line obsidianmd/no-global-this, unicorn/no-unnecessary-global-this -- Must stay `globalThis`-qualified: in the emitted banner a bare `process` is a free identifier, so reading it where the host has none throws a ReferenceError instead of yielding `undefined`. That is the very case this function exists to handle.
+  const existingProcess = globalThis.process;
+
+  if (!existingProcess) {
+    // eslint-disable-next-line obsidianmd/no-global-this -- Actively use globalThis.
+    globalThis.process = browserProcess;
+    return;
+  }
+
+  if (existingProcess.versions?.node) {
+    return;
+  }
+
+  const existingProcessRecord = existingProcess;
+
+  for (const [key, value] of Object.entries(browserProcess)) {
+    existingProcessRecord[key] ??= value;
+  }
+
+  existingProcessRecord['browser'] = true;
+}
+
+function keepName($unknown) {
+  return $unknown;
+}
+
+(function initCjs() {
+  // eslint-disable-next-line obsidianmd/no-global-this -- Actively use globalThis.
+  const globalThisRecord = globalThis;
+  ensureDisposeSymbols();
+  globalThisRecord['__name'] ??= keepName;
+  globalThisRecord['__extractDefault'] ??= extractDefault;
+
+  ensureBrowserProcess();
+
+  // eslint-disable-next-line unicorn/consistent-function-scoping -- Serialized with initCjs into the banner; at module scope it would be left out of it.
+  function extractDefault(module) {
+    return module && module.__esModule && 'default' in module ? module.default : module;
+  }
+})();
+})();
+(function patchObsidianRequire() {
+  const originalRequire = require;
+  if (!originalRequire || originalRequire.__isPatched) {
+    return;
+  }
+
+  // eslint-disable-next-line no-global-assign, no-implicit-globals -- We need to patch the `require()` function.
+  require = Object.assign(
+    (id) => requirePatched(id),
+    originalRequire,
+    {
+      __isPatched: true
+    }
+  );
+
+  function extractDefault(module) {
+    return module && module.__esModule && 'default' in module ? module.default : module;
+  }
+
+  const OBSIDIAN_BUILT_IN_MODULE_NAMES = new Set([
+  '@codemirror/autocomplete',
+  '@codemirror/collab',
+  '@codemirror/commands',
+  '@codemirror/language',
+  '@codemirror/lint',
+  '@codemirror/search',
+  '@codemirror/state',
+  '@codemirror/text',
+  '@codemirror/view',
+  '@lezer/common',
+  '@lezer/highlight',
+  '@lezer/lr',
+  'obsidian']
+  );
+
+  const DEPRECATED_OBSIDIAN_BUILT_IN_MODULE_NAMES = new Set([
+  '@codemirror/closebrackets',
+  '@codemirror/comment',
+  '@codemirror/fold',
+  '@codemirror/gutter',
+  '@codemirror/highlight',
+  '@codemirror/history',
+  '@codemirror/matchbrackets',
+  '@codemirror/panel',
+  '@codemirror/rangeset',
+  '@codemirror/rectangular-selection',
+  '@codemirror/stream-parser',
+  '@codemirror/tooltip']
+  );
+
+  function requirePatched(id) {
+    if (OBSIDIAN_BUILT_IN_MODULE_NAMES.has(id) || DEPRECATED_OBSIDIAN_BUILT_IN_MODULE_NAMES.has(id)) {
+      return originalRequire?.(id);
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-deprecated, obsidianmd/no-global-this  -- Need access to app. Actively use globalThis.
+    if (globalThis.app.isMobile) {
+      if (id === 'process' || id === 'node:process') {
+        // eslint-disable-next-line no-console -- Valid usage.
+        console.debug(`The most likely you can safely ignore this error. Module not found: ${id}. Fake process object is returned instead.`);
+
+        return process;
+      }
+    } else {
+      const module = originalRequire?.(id);
+      if (module) {
+        return extractDefault(module);
+      }
+    }
+
+    // eslint-disable-next-line no-console -- Valid usage.
+    console.debug(`The most likely you can safely ignore this error. Module not found: ${id}. Empty object is returned instead.`);
+    return {};
+  }
+})();
+
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var command_handler_exports = {};
+__export(command_handler_exports, {
+  CommandHandler: () => CommandHandler
+});
+module.exports = __toCommonJS(command_handler_exports);
+var import_function = require('@mnaoumov/typescript-lib/function');
+var import_type_guards = require('@mnaoumov/typescript-lib/type-guards');
+class CommandHandler {
+  /**
+   * The icon for the command.
+   */
+  icon;
+  /**
+   * The ID of the command.
+   */
+  id;
+  /**
+   * The display name of the command.
+   */
+  name;
+  /**
+   * Gets the plugin name.
+   *
+   * @returns The plugin name.
+   */
+  get pluginName() {
+    return (0, import_type_guards.ensureNonNullable)(this._pluginName);
+  }
+  _pluginName;
+  /**
+   * Creates a new command handler.
+   *
+   * @param params - The parameters for the command handler.
+   */
+  constructor(params) {
+    this.icon = params.icon;
+    this.id = params.id;
+    this.name = params.name;
+  }
+  /**
+   * Called after the command has been registered with Obsidian.
+   * Subclasses use the provided context to register menu event handlers.
+   *
+   * Throws when the same instance is registered twice. A handler stores per-registration state — the
+   * plugin name here, the active-file provider and the submenu override in `AbstractFileCommandHandler`,
+   * plus whatever a subclass records — and the menu closures registered here read that state lazily, at
+   * menu-render time. So a second registration silently rewrites what the first registration's closures
+   * will see. `CommandHandlerComponent` registers a handler set once per menu surface, which is why
+   * `CommandHandlerFactory` must build FRESH instances on every call; this guard turns a factory that
+   * hands out shared instances into a loud failure instead of a wrong context menu.
+   *
+   * @param context - The registration context providing runtime capabilities.
+   */
+  async onRegistered(context) {
+    await (0, import_function.noopAsync)();
+    if (this._pluginName !== void 0) {
+      throw new Error(
+        `Command handler '${this.id}' is already registered. A command handler instance cannot be registered twice - the command handler factory must build fresh instances on every call.`
+      );
+    }
+    this._pluginName = context.pluginName;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CommandHandler
+});
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsiLi4vLi4vLi4vLi4vc3JjL2NvbW1hbmQtaGFuZGxlcnMvY29tbWFuZC1oYW5kbGVyLnRzIl0sCiAgInNvdXJjZXNDb250ZW50IjogWyIvKipcbiAqIEBmaWxlXG4gKlxuICogQmFzZSBjbGFzcyBhbmQgaW50ZXJmYWNlcyBmb3IgY29tbWFuZCBoYW5kbGVycy5cbiAqL1xuXG5pbXBvcnQgdHlwZSB7XG4gIENvbW1hbmQsXG4gIEljb25OYW1lXG59IGZyb20gJ29ic2lkaWFuJztcblxuaW1wb3J0IHsgbm9vcEFzeW5jIH0gZnJvbSAnQG1uYW91bW92L3R5cGVzY3JpcHQtbGliL2Z1bmN0aW9uJztcbmltcG9ydCB7IGVuc3VyZU5vbk51bGxhYmxlIH0gZnJvbSAnQG1uYW91bW92L3R5cGVzY3JpcHQtbGliL3R5cGUtZ3VhcmRzJztcblxuaW1wb3J0IHR5cGUgeyBBY3RpdmVGaWxlUHJvdmlkZXIgfSBmcm9tICcuLi9hY3RpdmUtZmlsZS1wcm92aWRlci50cyc7XG5pbXBvcnQgdHlwZSB7IE1lbnVFdmVudFJlZ2lzdHJhciB9IGZyb20gJy4uL21lbnUtZXZlbnQtcmVnaXN0cmFyLnRzJztcblxuLyoqXG4gKiBQYXJhbWV0ZXJzIGZvciBjcmVhdGluZyBhIGNvbW1hbmQgaGFuZGxlci5cbiAqL1xuZXhwb3J0IGludGVyZmFjZSBDb21tYW5kSGFuZGxlckNvbnN0cnVjdG9yUGFyYW1zIHtcbiAgLyoqXG4gICAqIFRoZSBpY29uIGZvciB0aGUgY29tbWFuZC5cbiAgICovXG4gIHJlYWRvbmx5IGljb246IEljb25OYW1lO1xuXG4gIC8qKlxuICAgKiBUaGUgSUQgb2YgdGhlIGNvbW1hbmQuXG4gICAqL1xuICByZWFkb25seSBpZDogc3RyaW5nO1xuXG4gIC8qKlxuICAgKiBUaGUgZGlzcGxheSBuYW1lIG9mIHRoZSBjb21tYW5kLlxuICAgKi9cbiAgcmVhZG9ubHkgbmFtZTogc3RyaW5nO1xufVxuXG4vKipcbiAqIENvbnRleHQgcHJvdmlkZWQgdG8gY29tbWFuZCBoYW5kbGVycyBkdXJpbmcgcmVnaXN0cmF0aW9uLlxuICovXG5leHBvcnQgaW50ZXJmYWNlIENvbW1hbmRIYW5kbGVyUmVnaXN0cmF0aW9uQ29udGV4dCB7XG4gIC8qKlxuICAgKiBQcm92aWRlciBmb3IgYWNjZXNzaW5nIHRoZSBjdXJyZW50bHkgYWN0aXZlIGZpbGUuXG4gICAqL1xuICByZWFkb25seSBhY3RpdmVGaWxlUHJvdmlkZXI6IEFjdGl2ZUZpbGVQcm92aWRlcjtcblxuICAvKipcbiAgICogUmVnaXN0cmFyIGZvciBtZW51IGV2ZW50IGhhbmRsZXJzLlxuICAgKi9cbiAgcmVhZG9ubHkgbWVudUV2ZW50UmVnaXN0cmFyOiBNZW51RXZlbnRSZWdpc3RyYXI7XG5cbiAgLyoqXG4gICAqIFRoZSBuYW1lIG9mIHRoZSBwbHVnaW4gdGhhdCBvd25zIHRoaXMgY29tbWFuZC5cbiAgICovXG4gIHJlYWRvbmx5IHBsdWdpbk5hbWU6IHN0cmluZztcblxuICAvKipcbiAgICogT3ZlcnJpZGVzIHRoZSBoYW5kbGVyJ3Mgb3duIGBzaG91bGRBZGRDb21tYW5kVG9TdWJtZW51YCwgb3IgYHVuZGVmaW5lZGAgdG8gbGVhdmUgaXQgYWxvbmUuXG4gICAqXG4gICAqIEEgbWVudSBzdXJmYWNlIHRoYXQgYWxyZWFkeSB3cmFwcyBldmVyeSBjb250cmlidXRlZCBpdGVtIGluIGEgcGx1Z2luLXRpdGxlZCBwYXJlbnQgZW50cnkgXHUyMDE0IHN1Y2ggYXNcbiAgICogYE5vdGVib29rTmF2aWdhdG9yTWVudUV2ZW50UmVnaXN0cmFyQ29tcG9uZW50YCBcdTIwMTQgc2V0cyB0aGlzIHRvIGBmYWxzZWAsIGJlY2F1c2UgYSBoYW5kbGVyIGRlY2xhcmluZ1xuICAgKiBhIHNlY3Rpb24gc3VibWVudSBvZiBpdHMgb3duIHdvdWxkIG1ha2UgYE1lbnUuc29ydCgpYCBuZXN0IGEgc2Vjb25kIHBsdWdpbi10aXRsZWQgZW50cnkgaW5zaWRlIHRoZVxuICAgKiBmaXJzdC4gT25seSBgQWJzdHJhY3RGaWxlQ29tbWFuZEhhbmRsZXJgIHJlYWRzIGl0OiB0aGUgc3VyZmFjZXMgdGhhdCBuZWVkIGl0IGJyaWRnZSBmaWxlIGFuZFxuICAgKiBmb2xkZXIgbWVudXMsIG5ldmVyIHRoZSBlZGl0b3IgbWVudS5cbiAgICovXG4gIHJlYWRvbmx5IHNob3VsZEFkZENvbW1hbmRUb1N1Ym1lbnU/OiBib29sZWFuIHwgdW5kZWZpbmVkO1xufVxuXG4vKipcbiAqIEJhc2UgY2xhc3MgZm9yIGNvbW1hbmQgaGFuZGxlcnMuXG4gKlxuICogVW5saWtlIHRoZSBPYnNpZGlhbiB7QGxpbmsgQ29tbWFuZH0gaW50ZXJmYWNlLCBoYW5kbGVycyBhcmUgbmV2ZXIgbXV0YXRlZCBieSBPYnNpZGlhbi5cbiAqIFRoZSB7QGxpbmsgYnVpbGRDb21tYW5kfSBtZXRob2QgcHJvZHVjZXMgYSBwbGFpbiB7QGxpbmsgQ29tbWFuZH0gb2JqZWN0IGZvciByZWdpc3RyYXRpb24uXG4gKi9cbmV4cG9ydCBhYnN0cmFjdCBjbGFzcyBDb21tYW5kSGFuZGxlciB7XG4gIC8qKlxuICAgKiBUaGUgaWNvbiBmb3IgdGhlIGNvbW1hbmQuXG4gICAqL1xuICBwcm90ZWN0ZWQgcmVhZG9ubHkgaWNvbjogSWNvbk5hbWU7XG5cbiAgLyoqXG4gICAqIFRoZSBJRCBvZiB0aGUgY29tbWFuZC5cbiAgICovXG4gIHByb3RlY3RlZCByZWFkb25seSBpZDogc3RyaW5nO1xuXG4gIC8qKlxuICAgKiBUaGUgZGlzcGxheSBuYW1lIG9mIHRoZSBjb21tYW5kLlxuICAgKi9cbiAgcHJvdGVjdGVkIHJlYWRvbmx5IG5hbWU6IHN0cmluZztcblxuICAvKipcbiAgICogR2V0cyB0aGUgcGx1Z2luIG5hbWUuXG4gICAqXG4gICAqIEByZXR1cm5zIFRoZSBwbHVnaW4gbmFtZS5cbiAgICovXG4gIHByb3RlY3RlZCBnZXQgcGx1Z2luTmFtZSgpOiBzdHJpbmcge1xuICAgIHJldHVybiBlbnN1cmVOb25OdWxsYWJsZSh0aGlzLl9wbHVnaW5OYW1lKTtcbiAgfVxuXG4gIHByaXZhdGUgX3BsdWdpbk5hbWU/OiBzdHJpbmc7XG5cbiAgLyoqXG4gICAqIENyZWF0ZXMgYSBuZXcgY29tbWFuZCBoYW5kbGVyLlxuICAgKlxuICAgKiBAcGFyYW0gcGFyYW1zIC0gVGhlIHBhcmFtZXRlcnMgZm9yIHRoZSBjb21tYW5kIGhhbmRsZXIuXG4gICAqL1xuICBwdWJsaWMgY29uc3RydWN0b3IocGFyYW1zOiBDb21tYW5kSGFuZGxlckNvbnN0cnVjdG9yUGFyYW1zKSB7XG4gICAgdGhpcy5pY29uID0gcGFyYW1zLmljb247XG4gICAgdGhpcy5pZCA9IHBhcmFtcy5pZDtcbiAgICB0aGlzLm5hbWUgPSBwYXJhbXMubmFtZTtcbiAgfVxuXG4gIC8qKlxuICAgKiBCdWlsZHMgYSBwbGFpbiBPYnNpZGlhbiB7QGxpbmsgQ29tbWFuZH0gb2JqZWN0IGZvciByZWdpc3RyYXRpb24uXG4gICAqXG4gICAqIEByZXR1cm5zIEEgbmV3IHtAbGluayBDb21tYW5kfSBvYmplY3QuIE9ic2lkaWFuIG1heSBtdXRhdGUgdGhpcyBvYmplY3QgYWZ0ZXIgcmVnaXN0cmF0aW9uLlxuICAgKi9cbiAgcHVibGljIGFic3RyYWN0IGJ1aWxkQ29tbWFuZCgpOiBDb21tYW5kO1xuXG4gIC8qKlxuICAgKiBDYWxsZWQgYWZ0ZXIgdGhlIGNvbW1hbmQgaGFzIGJlZW4gcmVnaXN0ZXJlZCB3aXRoIE9ic2lkaWFuLlxuICAgKiBTdWJjbGFzc2VzIHVzZSB0aGUgcHJvdmlkZWQgY29udGV4dCB0byByZWdpc3RlciBtZW51IGV2ZW50IGhhbmRsZXJzLlxuICAgKlxuICAgKiBUaHJvd3Mgd2hlbiB0aGUgc2FtZSBpbnN0YW5jZSBpcyByZWdpc3RlcmVkIHR3aWNlLiBBIGhhbmRsZXIgc3RvcmVzIHBlci1yZWdpc3RyYXRpb24gc3RhdGUgXHUyMDE0IHRoZVxuICAgKiBwbHVnaW4gbmFtZSBoZXJlLCB0aGUgYWN0aXZlLWZpbGUgcHJvdmlkZXIgYW5kIHRoZSBzdWJtZW51IG92ZXJyaWRlIGluIGBBYnN0cmFjdEZpbGVDb21tYW5kSGFuZGxlcmAsXG4gICAqIHBsdXMgd2hhdGV2ZXIgYSBzdWJjbGFzcyByZWNvcmRzIFx1MjAxNCBhbmQgdGhlIG1lbnUgY2xvc3VyZXMgcmVnaXN0ZXJlZCBoZXJlIHJlYWQgdGhhdCBzdGF0ZSBsYXppbHksIGF0XG4gICAqIG1lbnUtcmVuZGVyIHRpbWUuIFNvIGEgc2Vjb25kIHJlZ2lzdHJhdGlvbiBzaWxlbnRseSByZXdyaXRlcyB3aGF0IHRoZSBmaXJzdCByZWdpc3RyYXRpb24ncyBjbG9zdXJlc1xuICAgKiB3aWxsIHNlZS4gYENvbW1hbmRIYW5kbGVyQ29tcG9uZW50YCByZWdpc3RlcnMgYSBoYW5kbGVyIHNldCBvbmNlIHBlciBtZW51IHN1cmZhY2UsIHdoaWNoIGlzIHdoeVxuICAgKiBgQ29tbWFuZEhhbmRsZXJGYWN0b3J5YCBtdXN0IGJ1aWxkIEZSRVNIIGluc3RhbmNlcyBvbiBldmVyeSBjYWxsOyB0aGlzIGd1YXJkIHR1cm5zIGEgZmFjdG9yeSB0aGF0XG4gICAqIGhhbmRzIG91dCBzaGFyZWQgaW5zdGFuY2VzIGludG8gYSBsb3VkIGZhaWx1cmUgaW5zdGVhZCBvZiBhIHdyb25nIGNvbnRleHQgbWVudS5cbiAgICpcbiAgICogQHBhcmFtIGNvbnRleHQgLSBUaGUgcmVnaXN0cmF0aW9uIGNvbnRleHQgcHJvdmlkaW5nIHJ1bnRpbWUgY2FwYWJpbGl0aWVzLlxuICAgKi9cbiAgcHVibGljIGFzeW5jIG9uUmVnaXN0ZXJlZChjb250ZXh0OiBDb21tYW5kSGFuZGxlclJlZ2lzdHJhdGlvbkNvbnRleHQpOiBQcm9taXNlPHZvaWQ+IHtcbiAgICBhd2FpdCBub29wQXN5bmMoKTtcbiAgICBpZiAodGhpcy5fcGx1Z2luTmFtZSAhPT0gdW5kZWZpbmVkKSB7XG4gICAgICB0aHJvdyBuZXcgRXJyb3IoXG4gICAgICAgIGBDb21tYW5kIGhhbmRsZXIgJyR7dGhpcy5pZH0nIGlzIGFscmVhZHkgcmVnaXN0ZXJlZC4gQSBjb21tYW5kIGhhbmRsZXIgaW5zdGFuY2UgY2Fubm90IGJlIHJlZ2lzdGVyZWQgdHdpY2UgLSB0aGUgY29tbWFuZCBoYW5kbGVyIGZhY3RvcnkgbXVzdCBidWlsZCBmcmVzaCBpbnN0YW5jZXMgb24gZXZlcnkgY2FsbC5gXG4gICAgICApO1xuICAgIH1cblxuICAgIHRoaXMuX3BsdWdpbk5hbWUgPSBjb250ZXh0LnBsdWdpbk5hbWU7XG4gIH1cbn1cbiJdLAogICJtYXBwaW5ncyI6ICI7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztBQUFBO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFXQSxzQkFBMEI7QUFDMUIseUJBQWtDO0FBOEQzQixNQUFlLGVBQWU7QUFBQTtBQUFBO0FBQUE7QUFBQSxFQUloQjtBQUFBO0FBQUE7QUFBQTtBQUFBLEVBS0E7QUFBQTtBQUFBO0FBQUE7QUFBQSxFQUtBO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBLEVBT25CLElBQWMsYUFBcUI7QUFDakMsZUFBTyxzQ0FBa0IsS0FBSyxXQUFXO0FBQUEsRUFDM0M7QUFBQSxFQUVRO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBLEVBT0QsWUFBWSxRQUF5QztBQUMxRCxTQUFLLE9BQU8sT0FBTztBQUNuQixTQUFLLEtBQUssT0FBTztBQUNqQixTQUFLLE9BQU8sT0FBTztBQUFBLEVBQ3JCO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBLEVBdUJBLE1BQWEsYUFBYSxTQUEyRDtBQUNuRixjQUFNLDJCQUFVO0FBQ2hCLFFBQUksS0FBSyxnQkFBZ0IsUUFBVztBQUNsQyxZQUFNLElBQUk7QUFBQSxRQUNSLG9CQUFvQixLQUFLLEVBQUU7QUFBQSxNQUM3QjtBQUFBLElBQ0Y7QUFFQSxTQUFLLGNBQWMsUUFBUTtBQUFBLEVBQzdCO0FBQ0Y7IiwKICAibmFtZXMiOiBbXQp9Cg==

package/dist/lib/cjs/command-handlers/command-handler.d.cts

@@ -0,0 +1,107 @@
+/// <reference path="../library.d.cts" />
+/**
+ * @file
+ *
+ * Base class and interfaces for command handlers.
+ */
+import type { Command, IconName } from 'obsidian' with { 'resolution-mode': 'import' };
+import type { ActiveFileProvider } from '../active-file-provider.cjs';
+import type { MenuEventRegistrar } from '../menu-event-registrar.cjs';
+/**
+ * Parameters for creating a command handler.
+ */
+export interface CommandHandlerConstructorParams {
+    /**
+     * The icon for the command.
+     */
+    readonly icon: IconName;
+    /**
+     * The ID of the command.
+     */
+    readonly id: string;
+    /**
+     * The display name of the command.
+     */
+    readonly name: string;
+}
+/**
+ * Context provided to command handlers during registration.
+ */
+export interface CommandHandlerRegistrationContext {
+    /**
+     * Provider for accessing the currently active file.
+     */
+    readonly activeFileProvider: ActiveFileProvider;
+    /**
+     * Registrar for menu event handlers.
+     */
+    readonly menuEventRegistrar: MenuEventRegistrar;
+    /**
+     * The name of the plugin that owns this command.
+     */
+    readonly pluginName: string;
+    /**
+     * Overrides the handler's own `shouldAddCommandToSubmenu`, or `undefined` to leave it alone.
+     *
+     * A menu surface that already wraps every contributed item in a plugin-titled parent entry — such as
+     * `NotebookNavigatorMenuEventRegistrarComponent` — sets this to `false`, because a handler declaring
+     * a section submenu of its own would make `Menu.sort()` nest a second plugin-titled entry inside the
+     * first. Only `AbstractFileCommandHandler` reads it: the surfaces that need it bridge file and
+     * folder menus, never the editor menu.
+     */
+    readonly shouldAddCommandToSubmenu?: boolean | undefined;
+}
+/**
+ * Base class for command handlers.
+ *
+ * Unlike the Obsidian {@link Command} interface, handlers are never mutated by Obsidian.
+ * The {@link buildCommand} method produces a plain {@link Command} object for registration.
+ */
+export declare abstract class CommandHandler {
+    /**
+     * The icon for the command.
+     */
+    protected readonly icon: IconName;
+    /**
+     * The ID of the command.
+     */
+    protected readonly id: string;
+    /**
+     * The display name of the command.
+     */
+    protected readonly name: string;
+    /**
+     * Gets the plugin name.
+     *
+     * @returns The plugin name.
+     */
+    protected get pluginName(): string;
+    private _pluginName?;
+    /**
+     * Creates a new command handler.
+     *
+     * @param params - The parameters for the command handler.
+     */
+    constructor(params: CommandHandlerConstructorParams);
+    /**
+     * Builds a plain Obsidian {@link Command} object for registration.
+     *
+     * @returns A new {@link Command} object. Obsidian may mutate this object after registration.
+     */
+    abstract buildCommand(): Command;
+    /**
+     * Called after the command has been registered with Obsidian.
+     * Subclasses use the provided context to register menu event handlers.
+     *
+     * Throws when the same instance is registered twice. A handler stores per-registration state — the
+     * plugin name here, the active-file provider and the submenu override in `AbstractFileCommandHandler`,
+     * plus whatever a subclass records — and the menu closures registered here read that state lazily, at
+     * menu-render time. So a second registration silently rewrites what the first registration's closures
+     * will see. `CommandHandlerComponent` registers a handler set once per menu surface, which is why
+     * `CommandHandlerFactory` must build FRESH instances on every call; this guard turns a factory that
+     * hands out shared instances into a loud failure instead of a wrong context menu.
+     *
+     * @param context - The registration context providing runtime capabilities.
+     */
+    onRegistered(context: CommandHandlerRegistrationContext): Promise<void>;
+}