obsidian-dev-utils 55.4.1 → 56.0.1

package/dist/lib/esm/obsidian/plugin/components/lifecycle-events-component.d.mts

@@ -0,0 +1,59 @@
+/**
+ * @file
+ *
+ * Component that manages plugin lifecycle events (load, layoutReady, unload).
+ */
+import type { App } from 'obsidian';
+import { AsyncEvents } from '../../../async-events.mjs';
+import { AsyncComponentBase } from '../../components/async-component.mjs';
+/**
+ * The name of a lifecycle event.
+ */
+export type LifecycleEventName = 'layoutReady' | 'load' | 'unload';
+/**
+ * Manages plugin lifecycle events: `load`, `layoutReady`, and `unload`.
+ *
+ * Components can wait for or register callbacks for these events.
+ */
+export declare class LifecycleEventsComponent extends AsyncComponentBase {
+    private readonly app;
+    /**
+     * The async events instance.
+     */
+    readonly events: AsyncEvents;
+    private readonly triggeredEvents;
+    /**
+     * Creates a new lifecycle events component.
+     *
+     * @param app - The Obsidian app instance.
+     */
+    constructor(app: App);
+    /**
+     * Triggers load and registers layoutReady callback.
+     */
+    onload(): Promise<void>;
+    /**
+     * Triggers the unload lifecycle event.
+     */
+    onunload(): void;
+    /**
+     * Registers a callback to be executed when a lifecycle event is triggered.
+     *
+     * @param name - The name of the event.
+     * @param callback - The callback to execute.
+     */
+    registerForLifecycleEvent(name: LifecycleEventName, callback: () => Promise<void>): Promise<void>;
+    /**
+     * Triggers a lifecycle event.
+     *
+     * @param name - The name of the lifecycle event to trigger.
+     */
+    triggerLifecycleEvent(name: LifecycleEventName): Promise<void>;
+    /**
+     * Waits for a lifecycle event to be triggered.
+     *
+     * @param name - The name of the event.
+     * @returns A {@link Promise} that resolves when the event is triggered.
+     */
+    waitForLifecycleEvent(name: LifecycleEventName): Promise<void>;
+}

package/dist/lib/esm/obsidian/plugin/components/lifecycle-events-component.mjs

@@ -0,0 +1,102 @@
+/*
+THIS IS A GENERATED/BUNDLED FILE BY ESBUILD
+if you want to view the source, please visit the github repository of this plugin
+*/
+
+(function initEsm() {
+  // eslint-disable-next-line obsidianmd/prefer-active-doc -- Actively use globalThis.
+  if (globalThis.process) {
+    return;
+  }
+
+  const browserProcess = {
+    browser: true,
+    cwd() {
+      return '/';
+    },
+    env: {},
+    platform: 'android'
+  };
+  // eslint-disable-next-line obsidianmd/prefer-active-doc -- Actively use globalThis.
+  globalThis.process = browserProcess;
+})();
+
+import { AsyncEvents } from "../../../async-events.mjs";
+import {
+  convertAsyncToSync,
+  invokeAsyncSafely
+} from "../../../async.mjs";
+import { AsyncComponentBase } from "../../components/async-component.mjs";
+class LifecycleEventsComponent extends AsyncComponentBase {
+  /**
+   * Creates a new lifecycle events component.
+   *
+   * @param app - The Obsidian app instance.
+   */
+  constructor(app) {
+    super();
+    this.app = app;
+  }
+  app;
+  /**
+   * The async events instance.
+   */
+  events = new AsyncEvents();
+  triggeredEvents = /* @__PURE__ */ new Set();
+  /**
+   * Triggers load and registers layoutReady callback.
+   */
+  async onload() {
+    await this.triggerLifecycleEvent("load");
+    this.app.workspace.onLayoutReady(convertAsyncToSync(async () => {
+      await this.triggerLifecycleEvent("layoutReady");
+    }));
+  }
+  /**
+   * Triggers the unload lifecycle event.
+   */
+  onunload() {
+    invokeAsyncSafely(async () => {
+      await this.triggerLifecycleEvent("unload");
+    });
+  }
+  /**
+   * Registers a callback to be executed when a lifecycle event is triggered.
+   *
+   * @param name - The name of the event.
+   * @param callback - The callback to execute.
+   */
+  async registerForLifecycleEvent(name, callback) {
+    await this.waitForLifecycleEvent(name);
+    await callback();
+  }
+  /**
+   * Triggers a lifecycle event.
+   *
+   * @param name - The name of the lifecycle event to trigger.
+   */
+  async triggerLifecycleEvent(name) {
+    this.triggeredEvents.add(name);
+    await this.events.triggerAsync(name);
+  }
+  /**
+   * Waits for a lifecycle event to be triggered.
+   *
+   * @param name - The name of the event.
+   * @returns A {@link Promise} that resolves when the event is triggered.
+   */
+  async waitForLifecycleEvent(name) {
+    if (this.triggeredEvents.has(name)) {
+      return;
+    }
+    await new Promise((resolve) => {
+      this.events.once(name, () => {
+        resolve();
+      });
+    });
+  }
+}
+export {
+  LifecycleEventsComponent
+};
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsiLi4vLi4vLi4vLi4vLi4vLi4vc3JjL29ic2lkaWFuL3BsdWdpbi9jb21wb25lbnRzL2xpZmVjeWNsZS1ldmVudHMtY29tcG9uZW50LnRzIl0sCiAgInNvdXJjZXNDb250ZW50IjogWyIvKipcbiAqIEBmaWxlXG4gKlxuICogQ29tcG9uZW50IHRoYXQgbWFuYWdlcyBwbHVnaW4gbGlmZWN5Y2xlIGV2ZW50cyAobG9hZCwgbGF5b3V0UmVhZHksIHVubG9hZCkuXG4gKi9cblxuaW1wb3J0IHR5cGUgeyBBcHAgfSBmcm9tICdvYnNpZGlhbic7XG5cbmltcG9ydCB7IEFzeW5jRXZlbnRzIH0gZnJvbSAnLi4vLi4vLi4vYXN5bmMtZXZlbnRzLnRzJztcbmltcG9ydCB7XG4gIGNvbnZlcnRBc3luY1RvU3luYyxcbiAgaW52b2tlQXN5bmNTYWZlbHlcbn0gZnJvbSAnLi4vLi4vLi4vYXN5bmMudHMnO1xuaW1wb3J0IHsgQXN5bmNDb21wb25lbnRCYXNlIH0gZnJvbSAnLi4vLi4vY29tcG9uZW50cy9hc3luYy1jb21wb25lbnQudHMnO1xuXG4vKipcbiAqIFRoZSBuYW1lIG9mIGEgbGlmZWN5Y2xlIGV2ZW50LlxuICovXG5leHBvcnQgdHlwZSBMaWZlY3ljbGVFdmVudE5hbWUgPSAnbGF5b3V0UmVhZHknIHwgJ2xvYWQnIHwgJ3VubG9hZCc7XG5cbi8qKlxuICogTWFuYWdlcyBwbHVnaW4gbGlmZWN5Y2xlIGV2ZW50czogYGxvYWRgLCBgbGF5b3V0UmVhZHlgLCBhbmQgYHVubG9hZGAuXG4gKlxuICogQ29tcG9uZW50cyBjYW4gd2FpdCBmb3Igb3IgcmVnaXN0ZXIgY2FsbGJhY2tzIGZvciB0aGVzZSBldmVudHMuXG4gKi9cbmV4cG9ydCBjbGFzcyBMaWZlY3ljbGVFdmVudHNDb21wb25lbnQgZXh0ZW5kcyBBc3luY0NvbXBvbmVudEJhc2Uge1xuICAvKipcbiAgICogVGhlIGFzeW5jIGV2ZW50cyBpbnN0YW5jZS5cbiAgICovXG4gIHB1YmxpYyByZWFkb25seSBldmVudHMgPSBuZXcgQXN5bmNFdmVudHMoKTtcblxuICBwcml2YXRlIHJlYWRvbmx5IHRyaWdnZXJlZEV2ZW50cyA9IG5ldyBTZXQ8TGlmZWN5Y2xlRXZlbnROYW1lPigpO1xuXG4gIC8qKlxuICAgKiBDcmVhdGVzIGEgbmV3IGxpZmVjeWNsZSBldmVudHMgY29tcG9uZW50LlxuICAgKlxuICAgKiBAcGFyYW0gYXBwIC0gVGhlIE9ic2lkaWFuIGFwcCBpbnN0YW5jZS5cbiAgICovXG4gIHB1YmxpYyBjb25zdHJ1Y3Rvcihwcml2YXRlIHJlYWRvbmx5IGFwcDogQXBwKSB7XG4gICAgc3VwZXIoKTtcbiAgfVxuXG4gIC8qKlxuICAgKiBUcmlnZ2VycyBsb2FkIGFuZCByZWdpc3RlcnMgbGF5b3V0UmVhZHkgY2FsbGJhY2suXG4gICAqL1xuICBwdWJsaWMgb3ZlcnJpZGUgYXN5bmMgb25sb2FkKCk6IFByb21pc2U8dm9pZD4ge1xuICAgIGF3YWl0IHRoaXMudHJpZ2dlckxpZmVjeWNsZUV2ZW50KCdsb2FkJyk7XG4gICAgdGhpcy5hcHAud29ya3NwYWNlLm9uTGF5b3V0UmVhZHkoY29udmVydEFzeW5jVG9TeW5jKGFzeW5jICgpID0+IHtcbiAgICAgIGF3YWl0IHRoaXMudHJpZ2dlckxpZmVjeWNsZUV2ZW50KCdsYXlvdXRSZWFkeScpO1xuICAgIH0pKTtcbiAgfVxuXG4gIC8qKlxuICAgKiBUcmlnZ2VycyB0aGUgdW5sb2FkIGxpZmVjeWNsZSBldmVudC5cbiAgICovXG4gIHB1YmxpYyBvdmVycmlkZSBvbnVubG9hZCgpOiB2b2lkIHtcbiAgICBpbnZva2VBc3luY1NhZmVseShhc3luYyAoKSA9PiB7XG4gICAgICBhd2FpdCB0aGlzLnRyaWdnZXJMaWZlY3ljbGVFdmVudCgndW5sb2FkJyk7XG4gICAgfSk7XG4gIH1cblxuICAvKipcbiAgICogUmVnaXN0ZXJzIGEgY2FsbGJhY2sgdG8gYmUgZXhlY3V0ZWQgd2hlbiBhIGxpZmVjeWNsZSBldmVudCBpcyB0cmlnZ2VyZWQuXG4gICAqXG4gICAqIEBwYXJhbSBuYW1lIC0gVGhlIG5hbWUgb2YgdGhlIGV2ZW50LlxuICAgKiBAcGFyYW0gY2FsbGJhY2sgLSBUaGUgY2FsbGJhY2sgdG8gZXhlY3V0ZS5cbiAgICovXG4gIHB1YmxpYyBhc3luYyByZWdpc3RlckZvckxpZmVjeWNsZUV2ZW50KG5hbWU6IExpZmVjeWNsZUV2ZW50TmFtZSwgY2FsbGJhY2s6ICgpID0+IFByb21pc2U8dm9pZD4pOiBQcm9taXNlPHZvaWQ+IHtcbiAgICBhd2FpdCB0aGlzLndhaXRGb3JMaWZlY3ljbGVFdmVudChuYW1lKTtcbiAgICBhd2FpdCBjYWxsYmFjaygpO1xuICB9XG5cbiAgLyoqXG4gICAqIFRyaWdnZXJzIGEgbGlmZWN5Y2xlIGV2ZW50LlxuICAgKlxuICAgKiBAcGFyYW0gbmFtZSAtIFRoZSBuYW1lIG9mIHRoZSBsaWZlY3ljbGUgZXZlbnQgdG8gdHJpZ2dlci5cbiAgICovXG4gIHB1YmxpYyBhc3luYyB0cmlnZ2VyTGlmZWN5Y2xlRXZlbnQobmFtZTogTGlmZWN5Y2xlRXZlbnROYW1lKTogUHJvbWlzZTx2b2lkPiB7XG4gICAgdGhpcy50cmlnZ2VyZWRFdmVudHMuYWRkKG5hbWUpO1xuICAgIGF3YWl0IHRoaXMuZXZlbnRzLnRyaWdnZXJBc3luYyhuYW1lKTtcbiAgfVxuXG4gIC8qKlxuICAgKiBXYWl0cyBmb3IgYSBsaWZlY3ljbGUgZXZlbnQgdG8gYmUgdHJpZ2dlcmVkLlxuICAgKlxuICAgKiBAcGFyYW0gbmFtZSAtIFRoZSBuYW1lIG9mIHRoZSBldmVudC5cbiAgICogQHJldHVybnMgQSB7QGxpbmsgUHJvbWlzZX0gdGhhdCByZXNvbHZlcyB3aGVuIHRoZSBldmVudCBpcyB0cmlnZ2VyZWQuXG4gICAqL1xuICBwdWJsaWMgYXN5bmMgd2FpdEZvckxpZmVjeWNsZUV2ZW50KG5hbWU6IExpZmVjeWNsZUV2ZW50TmFtZSk6IFByb21pc2U8dm9pZD4ge1xuICAgIGlmICh0aGlzLnRyaWdnZXJlZEV2ZW50cy5oYXMobmFtZSkpIHtcbiAgICAgIHJldHVybjtcbiAgICB9XG5cbiAgICBhd2FpdCBuZXcgUHJvbWlzZTx2b2lkPigocmVzb2x2ZSkgPT4ge1xuICAgICAgdGhpcy5ldmVudHMub25jZShuYW1lLCAoKSA9PiB7XG4gICAgICAgIHJlc29sdmUoKTtcbiAgICAgIH0pO1xuICAgIH0pO1xuICB9XG59XG4iXSwKICAibWFwcGluZ3MiOiAiOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztBQVFBLFNBQVMsbUJBQW1CO0FBQzVCO0FBQUEsRUFDRTtBQUFBLEVBQ0E7QUFBQSxPQUNLO0FBQ1AsU0FBUywwQkFBMEI7QUFZNUIsTUFBTSxpQ0FBaUMsbUJBQW1CO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBLEVBYXhELFlBQTZCLEtBQVU7QUFDNUMsVUFBTTtBQUQ0QjtBQUFBLEVBRXBDO0FBQUEsRUFGb0M7QUFBQTtBQUFBO0FBQUE7QUFBQSxFQVRwQixTQUFTLElBQUksWUFBWTtBQUFBLEVBRXhCLGtCQUFrQixvQkFBSSxJQUF3QjtBQUFBO0FBQUE7QUFBQTtBQUFBLEVBYy9ELE1BQXNCLFNBQXdCO0FBQzVDLFVBQU0sS0FBSyxzQkFBc0IsTUFBTTtBQUN2QyxTQUFLLElBQUksVUFBVSxjQUFjLG1CQUFtQixZQUFZO0FBQzlELFlBQU0sS0FBSyxzQkFBc0IsYUFBYTtBQUFBLElBQ2hELENBQUMsQ0FBQztBQUFBLEVBQ0o7QUFBQTtBQUFBO0FBQUE7QUFBQSxFQUtnQixXQUFpQjtBQUMvQixzQkFBa0IsWUFBWTtBQUM1QixZQUFNLEtBQUssc0JBQXNCLFFBQVE7QUFBQSxJQUMzQyxDQUFDO0FBQUEsRUFDSDtBQUFBO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBLEVBUUEsTUFBYSwwQkFBMEIsTUFBMEIsVUFBOEM7QUFDN0csVUFBTSxLQUFLLHNCQUFzQixJQUFJO0FBQ3JDLFVBQU0sU0FBUztBQUFBLEVBQ2pCO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBLEVBT0EsTUFBYSxzQkFBc0IsTUFBeUM7QUFDMUUsU0FBSyxnQkFBZ0IsSUFBSSxJQUFJO0FBQzdCLFVBQU0sS0FBSyxPQUFPLGFBQWEsSUFBSTtBQUFBLEVBQ3JDO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBO0FBQUEsRUFRQSxNQUFhLHNCQUFzQixNQUF5QztBQUMxRSxRQUFJLEtBQUssZ0JBQWdCLElBQUksSUFBSSxHQUFHO0FBQ2xDO0FBQUEsSUFDRjtBQUVBLFVBQU0sSUFBSSxRQUFjLENBQUMsWUFBWTtBQUNuQyxXQUFLLE9BQU8sS0FBSyxNQUFNLE1BQU07QUFDM0IsZ0JBQVE7QUFBQSxNQUNWLENBQUM7QUFBQSxJQUNILENBQUM7QUFBQSxFQUNIO0FBQ0Y7IiwKICAibmFtZXMiOiBbXQp9Cg==

package/dist/lib/esm/obsidian/plugin/components/plugin-context-component.d.mts

@@ -0,0 +1,25 @@
+/**
+ * @file
+ *
+ * Component that initializes the plugin context, debug controller, and library styles.
+ */
+import type { App } from 'obsidian';
+import { Component } from 'obsidian';
+/**
+ * Initializes plugin context (plugin ID, debug controller, library styles) on load.
+ */
+export declare class PluginContextComponent extends Component {
+    private readonly app;
+    private readonly pluginId;
+    /**
+     * Creates a new plugin context component.
+     *
+     * @param app - The Obsidian app instance.
+     * @param pluginId - The plugin ID.
+     */
+    constructor(app: App, pluginId: string);
+    /**
+     * Initializes the plugin context and debug controller.
+     */
+    onload(): void;
+}

package/dist/lib/esm/obsidian/plugin/components/plugin-context-component.mjs

@@ -0,0 +1,57 @@
+/*
+THIS IS A GENERATED/BUNDLED FILE BY ESBUILD
+if you want to view the source, please visit the github repository of this plugin
+*/
+
+(function initEsm() {
+  // eslint-disable-next-line obsidianmd/prefer-active-doc -- Actively use globalThis.
+  if (globalThis.process) {
+    return;
+  }
+
+  const browserProcess = {
+    browser: true,
+    cwd() {
+      return '/';
+    },
+    env: {},
+    platform: 'android'
+  };
+  // eslint-disable-next-line obsidianmd/prefer-active-doc -- Actively use globalThis.
+  globalThis.process = browserProcess;
+})();
+
+import { Component } from "obsidian";
+import { AllWindowsEventHandler } from "../../components/all-windows-event-handler.mjs";
+import {
+  initDebugController,
+  initPluginContext
+} from "../plugin-context.mjs";
+class PluginContextComponent extends Component {
+  /**
+   * Creates a new plugin context component.
+   *
+   * @param app - The Obsidian app instance.
+   * @param pluginId - The plugin ID.
+   */
+  constructor(app, pluginId) {
+    super();
+    this.app = app;
+    this.pluginId = pluginId;
+  }
+  app;
+  pluginId;
+  /**
+   * Initializes the plugin context and debug controller.
+   */
+  onload() {
+    initPluginContext(this.app, this.pluginId);
+    new AllWindowsEventHandler(this.app, this).registerAllWindowsHandler((win) => {
+      initDebugController(win, this);
+    });
+  }
+}
+export {
+  PluginContextComponent
+};
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsiLi4vLi4vLi4vLi4vLi4vLi4vc3JjL29ic2lkaWFuL3BsdWdpbi9jb21wb25lbnRzL3BsdWdpbi1jb250ZXh0LWNvbXBvbmVudC50cyJdLAogICJzb3VyY2VzQ29udGVudCI6IFsiLyoqXG4gKiBAZmlsZVxuICpcbiAqIENvbXBvbmVudCB0aGF0IGluaXRpYWxpemVzIHRoZSBwbHVnaW4gY29udGV4dCwgZGVidWcgY29udHJvbGxlciwgYW5kIGxpYnJhcnkgc3R5bGVzLlxuICovXG5cbmltcG9ydCB0eXBlIHsgQXBwIH0gZnJvbSAnb2JzaWRpYW4nO1xuXG5pbXBvcnQgeyBDb21wb25lbnQgfSBmcm9tICdvYnNpZGlhbic7XG5cbmltcG9ydCB7IEFsbFdpbmRvd3NFdmVudEhhbmRsZXIgfSBmcm9tICcuLi8uLi9jb21wb25lbnRzL2FsbC13aW5kb3dzLWV2ZW50LWhhbmRsZXIudHMnO1xuaW1wb3J0IHtcbiAgaW5pdERlYnVnQ29udHJvbGxlcixcbiAgaW5pdFBsdWdpbkNvbnRleHRcbn0gZnJvbSAnLi4vcGx1Z2luLWNvbnRleHQudHMnO1xuXG4vKipcbiAqIEluaXRpYWxpemVzIHBsdWdpbiBjb250ZXh0IChwbHVnaW4gSUQsIGRlYnVnIGNvbnRyb2xsZXIsIGxpYnJhcnkgc3R5bGVzKSBvbiBsb2FkLlxuICovXG5leHBvcnQgY2xhc3MgUGx1Z2luQ29udGV4dENvbXBvbmVudCBleHRlbmRzIENvbXBvbmVudCB7XG4gIC8qKlxuICAgKiBDcmVhdGVzIGEgbmV3IHBsdWdpbiBjb250ZXh0IGNvbXBvbmVudC5cbiAgICpcbiAgICogQHBhcmFtIGFwcCAtIFRoZSBPYnNpZGlhbiBhcHAgaW5zdGFuY2UuXG4gICAqIEBwYXJhbSBwbHVnaW5JZCAtIFRoZSBwbHVnaW4gSUQuXG4gICAqL1xuICBwdWJsaWMgY29uc3RydWN0b3IoXG4gICAgcHJpdmF0ZSByZWFkb25seSBhcHA6IEFwcCxcbiAgICBwcml2YXRlIHJlYWRvbmx5IHBsdWdpbklkOiBzdHJpbmdcbiAgKSB7XG4gICAgc3VwZXIoKTtcbiAgfVxuXG4gIC8qKlxuICAgKiBJbml0aWFsaXplcyB0aGUgcGx1Z2luIGNvbnRleHQgYW5kIGRlYnVnIGNvbnRyb2xsZXIuXG4gICAqL1xuICBwdWJsaWMgb3ZlcnJpZGUgb25sb2FkKCk6IHZvaWQge1xuICAgIGluaXRQbHVnaW5Db250ZXh0KHRoaXMuYXBwLCB0aGlzLnBsdWdpbklkKTtcbiAgICBuZXcgQWxsV2luZG93c0V2ZW50SGFuZGxlcih0aGlzLmFwcCwgdGhpcykucmVnaXN0ZXJBbGxXaW5kb3dzSGFuZGxlcigod2luKSA9PiB7XG4gICAgICBpbml0RGVidWdDb250cm9sbGVyKHdpbiwgdGhpcyk7XG4gICAgfSk7XG4gIH1cbn1cbiJdLAogICJtYXBwaW5ncyI6ICI7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0FBUUEsU0FBUyxpQkFBaUI7QUFFMUIsU0FBUyw4QkFBOEI7QUFDdkM7QUFBQSxFQUNFO0FBQUEsRUFDQTtBQUFBLE9BQ0s7QUFLQSxNQUFNLCtCQUErQixVQUFVO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBO0FBQUEsRUFPN0MsWUFDWSxLQUNBLFVBQ2pCO0FBQ0EsVUFBTTtBQUhXO0FBQ0E7QUFBQSxFQUduQjtBQUFBLEVBSm1CO0FBQUEsRUFDQTtBQUFBO0FBQUE7QUFBQTtBQUFBLEVBUUgsU0FBZTtBQUM3QixzQkFBa0IsS0FBSyxLQUFLLEtBQUssUUFBUTtBQUN6QyxRQUFJLHVCQUF1QixLQUFLLEtBQUssSUFBSSxFQUFFLDBCQUEwQixDQUFDLFFBQVE7QUFDNUUsMEJBQW9CLEtBQUssSUFBSTtBQUFBLElBQy9CLENBQUM7QUFBQSxFQUNIO0FBQ0Y7IiwKICAibmFtZXMiOiBbXQp9Cg==

package/dist/lib/esm/obsidian/plugin/components/plugin-notice-component.d.mts

@@ -0,0 +1,25 @@
+/**
+ * @file
+ *
+ * Component that manages displaying notices to the user.
+ */
+import { Component } from 'obsidian';
+/**
+ * Manages showing plugin notices. Automatically hides the previous notice when a new one is shown.
+ */
+export declare class PluginNoticeComponent extends Component {
+    private readonly pluginName;
+    private notice?;
+    /**
+     * Creates a new plugin notice component.
+     *
+     * @param pluginName - The plugin name (shown as prefix in notices).
+     */
+    constructor(pluginName: string);
+    /**
+     * Displays a notice message to the user.
+     *
+     * @param message - The message to display.
+     */
+    showNotice(message: string): void;
+}

package/dist/lib/esm/obsidian/plugin/components/plugin-notice-component.mjs

@@ -0,0 +1,56 @@
+/*
+THIS IS A GENERATED/BUNDLED FILE BY ESBUILD
+if you want to view the source, please visit the github repository of this plugin
+*/
+
+(function initEsm() {
+  // eslint-disable-next-line obsidianmd/prefer-active-doc -- Actively use globalThis.
+  if (globalThis.process) {
+    return;
+  }
+
+  const browserProcess = {
+    browser: true,
+    cwd() {
+      return '/';
+    },
+    env: {},
+    platform: 'android'
+  };
+  // eslint-disable-next-line obsidianmd/prefer-active-doc -- Actively use globalThis.
+  globalThis.process = browserProcess;
+})();
+
+import {
+  Component,
+  Notice
+} from "obsidian";
+class PluginNoticeComponent extends Component {
+  /**
+   * Creates a new plugin notice component.
+   *
+   * @param pluginName - The plugin name (shown as prefix in notices).
+   */
+  constructor(pluginName) {
+    super();
+    this.pluginName = pluginName;
+  }
+  pluginName;
+  notice;
+  /**
+   * Displays a notice message to the user.
+   *
+   * @param message - The message to display.
+   */
+  showNotice(message) {
+    if (this.notice) {
+      this.notice.hide();
+    }
+    this.notice = new Notice(`${this.pluginName}
+${message}`);
+  }
+}
+export {
+  PluginNoticeComponent
+};
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsiLi4vLi4vLi4vLi4vLi4vLi4vc3JjL29ic2lkaWFuL3BsdWdpbi9jb21wb25lbnRzL3BsdWdpbi1ub3RpY2UtY29tcG9uZW50LnRzIl0sCiAgInNvdXJjZXNDb250ZW50IjogWyIvKipcbiAqIEBmaWxlXG4gKlxuICogQ29tcG9uZW50IHRoYXQgbWFuYWdlcyBkaXNwbGF5aW5nIG5vdGljZXMgdG8gdGhlIHVzZXIuXG4gKi9cblxuaW1wb3J0IHtcbiAgQ29tcG9uZW50LFxuICBOb3RpY2Vcbn0gZnJvbSAnb2JzaWRpYW4nO1xuXG4vKipcbiAqIE1hbmFnZXMgc2hvd2luZyBwbHVnaW4gbm90aWNlcy4gQXV0b21hdGljYWxseSBoaWRlcyB0aGUgcHJldmlvdXMgbm90aWNlIHdoZW4gYSBuZXcgb25lIGlzIHNob3duLlxuICovXG5leHBvcnQgY2xhc3MgUGx1Z2luTm90aWNlQ29tcG9uZW50IGV4dGVuZHMgQ29tcG9uZW50IHtcbiAgcHJpdmF0ZSBub3RpY2U/OiBOb3RpY2U7XG5cbiAgLyoqXG4gICAqIENyZWF0ZXMgYSBuZXcgcGx1Z2luIG5vdGljZSBjb21wb25lbnQuXG4gICAqXG4gICAqIEBwYXJhbSBwbHVnaW5OYW1lIC0gVGhlIHBsdWdpbiBuYW1lIChzaG93biBhcyBwcmVmaXggaW4gbm90aWNlcykuXG4gICAqL1xuICBwdWJsaWMgY29uc3RydWN0b3IocHJpdmF0ZSByZWFkb25seSBwbHVnaW5OYW1lOiBzdHJpbmcpIHtcbiAgICBzdXBlcigpO1xuICB9XG5cbiAgLyoqXG4gICAqIERpc3BsYXlzIGEgbm90aWNlIG1lc3NhZ2UgdG8gdGhlIHVzZXIuXG4gICAqXG4gICAqIEBwYXJhbSBtZXNzYWdlIC0gVGhlIG1lc3NhZ2UgdG8gZGlzcGxheS5cbiAgICovXG4gIHB1YmxpYyBzaG93Tm90aWNlKG1lc3NhZ2U6IHN0cmluZyk6IHZvaWQge1xuICAgIGlmICh0aGlzLm5vdGljZSkge1xuICAgICAgdGhpcy5ub3RpY2UuaGlkZSgpO1xuICAgIH1cblxuICAgIHRoaXMubm90aWNlID0gbmV3IE5vdGljZShgJHt0aGlzLnBsdWdpbk5hbWV9XFxuJHttZXNzYWdlfWApO1xuICB9XG59XG4iXSwKICAibWFwcGluZ3MiOiAiOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztBQU1BO0FBQUEsRUFDRTtBQUFBLEVBQ0E7QUFBQSxPQUNLO0FBS0EsTUFBTSw4QkFBOEIsVUFBVTtBQUFBO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQSxFQVE1QyxZQUE2QixZQUFvQjtBQUN0RCxVQUFNO0FBRDRCO0FBQUEsRUFFcEM7QUFBQSxFQUZvQztBQUFBLEVBUDVCO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBLEVBZ0JELFdBQVcsU0FBdUI7QUFDdkMsUUFBSSxLQUFLLFFBQVE7QUFDZixXQUFLLE9BQU8sS0FBSztBQUFBLElBQ25CO0FBRUEsU0FBSyxTQUFTLElBQUksT0FBTyxHQUFHLEtBQUssVUFBVTtBQUFBLEVBQUssT0FBTyxFQUFFO0FBQUEsRUFDM0Q7QUFDRjsiLAogICJuYW1lcyI6IFtdCn0K

package/dist/lib/esm/obsidian/plugin/components/plugin-settings-component.d.mts

@@ -0,0 +1,302 @@
+/**
+ * @file
+ *
+ * Component that manages plugin settings: data, persistence, validation, and events.
+ *
+ * This is the single public-facing settings API for plugin authors.
+ * All settings logic (load, save, validate, transform, clone) is handled directly
+ * by this component — no separate manager class is needed.
+ */
+import type { Promisable, ReadonlyDeep } from 'type-fest';
+import type { AsyncEventRef } from '../../../async-events.mjs';
+import type { Transformer } from '../../../transformers/transformer.mjs';
+import type { GenericObject } from '../../../type-guards.mjs';
+import type { MaybeReturn, StringKeys } from '../../../type.mjs';
+import { AsyncComponentBase } from '../../components/async-component.mjs';
+/**
+ * Component key used by {@link registerComponent} to identify settings components.
+ */
+export declare const PLUGIN_SETTINGS_COMPONENT_KEY = "PluginSettingsComponent";
+/**
+ * Params for creating a {@link PluginSettingsComponentBase}.
+ */
+export interface PluginSettingsComponentParams {
+    /**
+     * A function to load data from the plugin's data file.
+     *
+     * @returns The loaded data.
+     */
+    readonly loadData: () => Promise<unknown>;
+    /**
+     * A function to save data to the plugin's data file.
+     *
+     * @param data - The data to save.
+     */
+    readonly saveData: (data: unknown) => Promise<void>;
+}
+/**
+ * A snapshot of plugin settings state, including raw input values, effective (validated) values,
+ * and per-property validation messages.
+ *
+ * @typeParam PluginSettings - The type of the plugin settings.
+ */
+export interface PluginSettingsState<PluginSettings extends object> {
+    /**
+     * The effective settings values used by the plugin. Invalid properties are replaced with defaults.
+     */
+    effectiveValues: PluginSettings;
+    /**
+     * The raw input values as entered by the user. May contain invalid values.
+     */
+    inputValues: PluginSettings;
+    /**
+     * Per-property validation messages. Empty string means valid.
+     */
+    validationMessages: Record<StringKeys<PluginSettings>, string>;
+}
+/**
+ * Readonly version of {@link PluginSettings}.
+ *
+ * @typeParam PluginSettings - The type of the plugin settings.
+ */
+export type ReadonlyPluginSettings<PluginSettings extends object> = ReadonlyDeep<PluginSettings>;
+/**
+ * Readonly version of {@link PluginSettingsState} for use in event callbacks and public getters.
+ *
+ * @typeParam PluginSettings - The type of the plugin settings.
+ */
+export type ReadonlyPluginSettingsState<PluginSettings extends object> = ReadonlyDeep<PluginSettingsState<PluginSettings>>;
+/**
+ * A validator function for a settings property.
+ *
+ * @typeParam PluginSettings - The plugin settings type.
+ * @typeParam PropertyName - The property name.
+ */
+export type SettingsValidator<PluginSettings extends object, PropertyName extends StringKeys<PluginSettings> = StringKeys<PluginSettings>> = (value: PluginSettings[PropertyName], settings: PluginSettings) => Promisable<MaybeReturn<string>>;
+type PropertyNames<PluginSettings extends object> = StringKeys<PluginSettings>;
+type ValidationResult<PluginSettings extends object> = Partial<Record<StringKeys<PluginSettings>, string>>;
+/**
+ * Base class for plugin settings components.
+ *
+ * Manages settings data, persistence, validation, and events.
+ * Plugin authors extend this class and implement {@link createDefaultSettings}.
+ *
+ * @typeParam PluginSettings - The plugin settings type.
+ */
+export declare abstract class PluginSettingsComponentBase<PluginSettings extends object> extends AsyncComponentBase {
+    /**
+     * Component key for {@link registerComponent} replacement.
+     */
+    static readonly COMPONENT_KEY = "PluginSettingsComponent";
+    /**
+     * Gets the readonly default settings.
+     *
+     * @returns The default settings (as a readonly object).
+     */
+    readonly defaultSettings: ReadonlyDeep<PluginSettings>;
+    /**
+     * Gets the readonly effective settings (validated, with defaults substituted for invalid values).
+     *
+     * @returns The readonly effective settings.
+     */
+    get settings(): ReadonlyDeep<PluginSettings>;
+    /**
+     * Gets the current settings state snapshot.
+     *
+     * @returns The current settings state.
+     */
+    get settingsState(): ReadonlyPluginSettingsState<PluginSettings>;
+    private readonly asyncEvents;
+    private currentState;
+    private lastSavedState;
+    private readonly legacySettingsConverters;
+    private readonly loadDataFn;
+    private readonly propertyNames;
+    private readonly saveDataFn;
+    private readonly validators;
+    /**
+     * Creates a new plugin settings component.
+     *
+     * @param params - The params for loading/saving data.
+     */
+    constructor(params: PluginSettingsComponentParams);
+    /**
+     * Edits the plugin settings and saves them.
+     *
+     * @param settingsEditor - The editor.
+     * @param context - The context.
+     * @returns A {@link Promise} that resolves when the settings are saved.
+     */
+    editAndSave(settingsEditor: (settings: PluginSettings) => Promisable<void>, context?: unknown): Promise<void>;
+    /**
+     * Ensures the settings are safe.
+     *
+     * It runs validation for each property and sets the default value if the validation fails.
+     *
+     * @param settings - The settings.
+     * @returns A {@link Promise} that resolves when the settings are safe.
+     */
+    ensureSafe(settings: PluginSettings): Promise<void>;
+    /**
+     * Gets a safe copy of the settings.
+     *
+     * @param settings - The settings.
+     * @returns A {@link Promise} that resolves to the safe copy of the settings.
+     */
+    getSafeCopy(settings: PluginSettings): Promise<PluginSettings>;
+    /**
+     * Loads the plugin settings from the file.
+     *
+     * @param isInitialLoad - Whether the settings are being loaded for the first time.
+     * @returns A {@link Promise} that resolves when the settings are loaded.
+     */
+    loadFromFile(isInitialLoad: boolean): Promise<void>;
+    /**
+     * Subscribes to the `loadSettings` event.
+     *
+     * @param name - Always `loadSettings`.
+     * @param callback - The callback.
+     * @param thisArg - The `this` context.
+     * @returns A reference to the event listener.
+     */
+    on(name: 'loadSettings', callback: (loadedState: ReadonlyPluginSettingsState<PluginSettings>, isInitialLoad: boolean) => Promisable<void>, thisArg?: unknown): AsyncEventRef;
+    /**
+     * Subscribes to the `saveSettings` event.
+     *
+     * @param name - Always `saveSettings`.
+     * @param callback - The callback.
+     * @param thisArg - The `this` context.
+     * @returns A reference to the event listener.
+     */
+    on(name: 'saveSettings', callback: (newState: ReadonlyPluginSettingsState<PluginSettings>, oldState: ReadonlyPluginSettingsState<PluginSettings>, context: unknown) => Promisable<void>, thisArg?: unknown): AsyncEventRef;
+    /**
+     * Called when the external settings change.
+     *
+     * @returns A {@link Promise} that resolves when the settings are reloaded.
+     */
+    onExternalSettingsChange(): Promise<void>;
+    /**
+     * Loads settings from file and registers event handlers.
+     */
+    onload(): Promise<void>;
+    /**
+     * Registers a legacy settings converter.
+     *
+     * @typeParam LegacySettings - The legacy settings class.
+     * @param legacySettingsClass - The legacy settings class.
+     * @param converter - The converter.
+     */
+    registerLegacySettingsConverter<LegacySettings extends object>(legacySettingsClass: new () => LegacySettings, converter: (legacySettings: Partial<LegacySettings> & Partial<PluginSettings>) => void): void;
+    /**
+     * Registers a validator for a property.
+     *
+     * @param propertyName - The name of the property.
+     * @param validator - The validator.
+     */
+    registerValidator<PropertyName extends PropertyNames<PluginSettings>>(propertyName: PropertyName, validator: SettingsValidator<PluginSettings, PropertyName>): void;
+    /**
+     * Revalidates the settings.
+     *
+     * @returns The validation messages.
+     */
+    revalidate(): Promise<Record<PropertyNames<PluginSettings>, string>>;
+    /**
+     * Saves the new plugin settings.
+     *
+     * @param context - The context of the save to file operation.
+     * @returns A {@link Promise} that resolves when the settings are saved.
+     */
+    saveToFile(context?: unknown): Promise<void>;
+    /**
+     * Sets the value of a property.
+     *
+     * @typeParam PropertyName - The name of the property.
+     * @param propertyName - The name of the property.
+     * @param value - The value to set.
+     * @returns A {@link Promise} that resolves to the validation message.
+     */
+    setProperty<PropertyName extends PropertyNames<PluginSettings>>(propertyName: PropertyName, value: PluginSettings[PropertyName]): Promise<string>;
+    /**
+     * Validates the settings.
+     *
+     * @param settings - The settings.
+     * @returns A {@link Promise} that resolves to the validation result.
+     */
+    validate(settings: PluginSettings): Promise<ValidationResult<PluginSettings>>;
+    /**
+     * Creates the default settings. Must be implemented by subclasses.
+     *
+     * @returns The default settings.
+     */
+    protected abstract createDefaultSettings(): PluginSettings;
+    /**
+     * Gets the transformer.
+     *
+     * @returns The transformer.
+     */
+    protected getTransformer(): Transformer;
+    /**
+     * Called when the plugin settings record is loaded from disk.
+     *
+     * @param record - The record.
+     */
+    protected onLoadRecord(record: GenericObject): Promise<void>;
+    /**
+     * Called when settings are loaded or reloaded.
+     *
+     * @param _loadedState - The loaded settings state.
+     * @param _isInitialLoad - Whether this is the initial load.
+     */
+    protected onLoadSettings(_loadedState: ReadonlyPluginSettingsState<PluginSettings>, _isInitialLoad: boolean): Promise<void>;
+    /**
+     * Called when settings are saved.
+     *
+     * @param _newState - The new settings state.
+     * @param _oldState - The old settings state.
+     * @param _context - The save context.
+     */
+    protected onSaveSettings(_newState: ReadonlyPluginSettingsState<PluginSettings>, _oldState: ReadonlyPluginSettingsState<PluginSettings>, _context: unknown): Promise<void>;
+    /**
+     * Called when the plugin settings record is about to be saved to disk.
+     *
+     * @param _record - The record.
+     */
+    protected onSavingRecord(_record: GenericObject): Promise<void>;
+    /**
+     * Registers the legacy settings converters.
+     * Override to register legacy settings converters.
+     */
+    protected registerLegacySettingsConverters(): void;
+    /**
+     * Registers the validators.
+     * Override to register validators for properties.
+     */
+    protected registerValidators(): void;
+    private cloneSettings;
+    private cloneState;
+    private createDefaultState;
+    private edit;
+    private isValidPropertyName;
+    private rawRecordToSettings;
+    private saveToFileImpl;
+    private setPropertyImpl;
+    private settingsToRawRecord;
+}
+/**
+ * A no-op settings component for plugins without settings.
+ */
+export declare class EmptyPluginSettingsComponent extends PluginSettingsComponentBase<object> {
+    /**
+     * Creates a new empty plugin settings component.
+     *
+     * @param params - The params. Uses no-op load/save by default.
+     */
+    constructor(params?: PluginSettingsComponentParams);
+    /**
+     * Creates empty default settings.
+     *
+     * @returns An empty object.
+     */
+    protected createDefaultSettings(): object;
+}
+export {};