@mnaoumov/obsidian-lib 0.0.0 → 1.0.0

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

@@ -0,0 +1,127 @@
+/// <reference path="../library.d.mts" />
+/**
+ * @file
+ *
+ * The lifecycle broadcast every {@link PluginBase} makes: `obsidian-dev-utils:plugin-loaded` when it has
+ * finished loading and `obsidian-dev-utils:plugin-unloaded` when it goes away.
+ *
+ * Obsidian gives a plugin no way to learn that ANOTHER plugin was enabled or disabled — there is no such
+ * event on `app.plugins`, and a plugin's own `Events` source cannot help a listener that does not yet hold
+ * the instance. So the broadcast goes through `app.workspace`, which is one object every plugin in the
+ * vault can reach. Deliberately NOT the `globalThis.__obsidianDevUtils` bag the rest of the library shares
+ * its state through: a listener there needs its own copy of this library, and these events are meant to be
+ * consumable by any plugin at all.
+ *
+ * The names are past tense because a broadcast states something that has already happened. `loaded` in
+ * particular carries a guarantee: it is triggered only after every API the plugin declares has been
+ * published, so a listener may call them immediately.
+ *
+ * Both the event names and {@link PluginLifecycleEventPayload} are a CROSS-VERSION CONTRACT. Copies of
+ * this library at different versions publish and consume them side by side in one vault, so neither may
+ * change incompatibly: plain data only, and new payload fields only ever added.
+ *
+ * That contract is also PUBLISHED, as of the `Plugin API protocol` guide: third-party plugins that will
+ * never install this library are told to hardcode these two strings and this payload shape. Publishing it
+ * added no new constraint — the cross-copy one above already forbade every change an outsider could
+ * notice — but it does mean a rename is now doubly unavailable. The `obsidian-dev-utils:` prefix names the
+ * library rather than the subject, which is a wart, and a permanent one: a neutral alias would not retire
+ * the old name (already-released plugins emit only it), so it would leave every correct consumer listening
+ * for both, forever.
+ */
+import type { App } from 'obsidian';
+/**
+ * The name of either lifecycle event.
+ */
+export type PluginLifecycleEventName = typeof PLUGIN_LOADED_EVENT_NAME | typeof PLUGIN_UNLOADED_EVENT_NAME;
+/**
+ * The payload of {@link PLUGIN_LOADED_EVENT_NAME} and {@link PLUGIN_UNLOADED_EVENT_NAME}.
+ *
+ * Plain data by design — no class instances and no types owned by this library — because it crosses
+ * between independently bundled copies of it, and between plugins that do not use it at all.
+ */
+export interface PluginLifecycleEventPayload {
+    /**
+     * The contract versions the plugin published, empty when it publishes no API.
+     *
+     * An array rather than a single version because a provider may publish several contract versions side by
+     * side, so consumers pinned to an older range keep working across a breaking change.
+     *
+     * The API objects themselves are deliberately NOT here. A handle delivered by a one-shot event is a
+     * probe: it answers "now" and never says when "now" changed, and one that outlives the provider is
+     * exactly the stale handle the plugin-api registry's revocable handles exist to prevent. Reach the API
+     * through `watchPluginApi` instead, whose reference stays correct across unload and re-enable.
+     */
+    readonly apiVersions: readonly string[];
+    /**
+     * The ids of the plugins this one declares as mandatory dependencies, empty when it declares none.
+     *
+     * Present so the relationship can be read from the OTHER end: a provider has no way to ask who depends
+     * on it — the registry only answers consumer-to-provider — and "which installed plugins need this one"
+     * is what lets a provider's settings tab tell the user why it is in their vault at all.
+     */
+    readonly dependencyPluginIds: readonly string[];
+    /**
+     * The plugin's `manifest.id`.
+     */
+    readonly pluginId: string;
+    /**
+     * The plugin's `manifest.name`, for display.
+     */
+    readonly pluginName: string;
+    /**
+     * The plugin's `manifest.version`.
+     */
+    readonly pluginVersion: string;
+}
+/**
+ * Parameters for {@link triggerPluginLifecycleEvent}.
+ */
+export interface TriggerPluginLifecycleEventParams {
+    /**
+     * The Obsidian app instance whose workspace carries the broadcast.
+     */
+    readonly app: App;
+    /**
+     * The event to trigger.
+     */
+    readonly name: PluginLifecycleEventName;
+    /**
+     * The payload describing the plugin.
+     */
+    readonly payload: PluginLifecycleEventPayload;
+}
+/**
+ * Triggered once a plugin has finished loading AND published every API it declares, so a listener may call
+ * those APIs immediately.
+ *
+ * Namespaced by the package name rather than by an abbreviation of it: the event is global to the vault
+ * and aimed at plugin authors who have never heard of this library, so the prefix has to identify itself.
+ */
+export declare const PLUGIN_LOADED_EVENT_NAME = "obsidian-dev-utils:plugin-loaded";
+/**
+ * Triggered as a plugin unloads — whether the user disabled it, uninstalled it, or Obsidian is shutting
+ * down. Its APIs are revoked by the time a listener runs.
+ */
+export declare const PLUGIN_UNLOADED_EVENT_NAME = "obsidian-dev-utils:plugin-unloaded";
+declare module 'obsidian' {
+    interface Workspace {
+        /**
+         * Subscribes to a plugin finishing its load, or to one unloading.
+         *
+         * @param name - Should be {@link PLUGIN_LOADED_EVENT_NAME} or {@link PLUGIN_UNLOADED_EVENT_NAME}.
+         * @param callback - The callback receiving the plugin's payload.
+         * @param context - The context passed as `this` to the `callback` function.
+         * @returns The event reference.
+         */
+        on(name: PluginLifecycleEventName, callback: (payload: PluginLifecycleEventPayload) => unknown, context?: unknown): EventRef;
+    }
+}
+/**
+ * Triggers one of the two lifecycle events on the app's workspace.
+ *
+ * A thin typed wrapper over `Workspace.trigger`, which accepts any event name and any arguments, so that
+ * the one place a payload is constructed is checked against {@link PluginLifecycleEventPayload}.
+ *
+ * @param params - The {@link TriggerPluginLifecycleEventParams}.
+ */
+export declare function triggerPluginLifecycleEvent(params: TriggerPluginLifecycleEventParams): void;

package/dist/lib/esm/plugin/plugin-lifecycle-events.mjs

@@ -0,0 +1,60 @@
+/*
+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 initEsm() {
+  ensureDisposeSymbols();
+  ensureBrowserProcess();
+})();
+})();
+
+const PLUGIN_LOADED_EVENT_NAME = "obsidian-dev-utils:plugin-loaded";
+const PLUGIN_UNLOADED_EVENT_NAME = "obsidian-dev-utils:plugin-unloaded";
+function triggerPluginLifecycleEvent(params) {
+  params.app.workspace.trigger(params.name, params.payload);
+}
+export {
+  PLUGIN_LOADED_EVENT_NAME,
+  PLUGIN_UNLOADED_EVENT_NAME,
+  triggerPluginLifecycleEvent
+};
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsiLi4vLi4vLi4vLi4vc3JjL3BsdWdpbi9wbHVnaW4tbGlmZWN5Y2xlLWV2ZW50cy50cyJdLAogICJzb3VyY2VzQ29udGVudCI6IFsiLyoqXG4gKiBAZmlsZVxuICpcbiAqIFRoZSBsaWZlY3ljbGUgYnJvYWRjYXN0IGV2ZXJ5IHtAbGluayBQbHVnaW5CYXNlfSBtYWtlczogYG9ic2lkaWFuLWRldi11dGlsczpwbHVnaW4tbG9hZGVkYCB3aGVuIGl0IGhhc1xuICogZmluaXNoZWQgbG9hZGluZyBhbmQgYG9ic2lkaWFuLWRldi11dGlsczpwbHVnaW4tdW5sb2FkZWRgIHdoZW4gaXQgZ29lcyBhd2F5LlxuICpcbiAqIE9ic2lkaWFuIGdpdmVzIGEgcGx1Z2luIG5vIHdheSB0byBsZWFybiB0aGF0IEFOT1RIRVIgcGx1Z2luIHdhcyBlbmFibGVkIG9yIGRpc2FibGVkIFx1MjAxNCB0aGVyZSBpcyBubyBzdWNoXG4gKiBldmVudCBvbiBgYXBwLnBsdWdpbnNgLCBhbmQgYSBwbHVnaW4ncyBvd24gYEV2ZW50c2Agc291cmNlIGNhbm5vdCBoZWxwIGEgbGlzdGVuZXIgdGhhdCBkb2VzIG5vdCB5ZXQgaG9sZFxuICogdGhlIGluc3RhbmNlLiBTbyB0aGUgYnJvYWRjYXN0IGdvZXMgdGhyb3VnaCBgYXBwLndvcmtzcGFjZWAsIHdoaWNoIGlzIG9uZSBvYmplY3QgZXZlcnkgcGx1Z2luIGluIHRoZVxuICogdmF1bHQgY2FuIHJlYWNoLiBEZWxpYmVyYXRlbHkgTk9UIHRoZSBgZ2xvYmFsVGhpcy5fX29ic2lkaWFuRGV2VXRpbHNgIGJhZyB0aGUgcmVzdCBvZiB0aGUgbGlicmFyeSBzaGFyZXNcbiAqIGl0cyBzdGF0ZSB0aHJvdWdoOiBhIGxpc3RlbmVyIHRoZXJlIG5lZWRzIGl0cyBvd24gY29weSBvZiB0aGlzIGxpYnJhcnksIGFuZCB0aGVzZSBldmVudHMgYXJlIG1lYW50IHRvIGJlXG4gKiBjb25zdW1hYmxlIGJ5IGFueSBwbHVnaW4gYXQgYWxsLlxuICpcbiAqIFRoZSBuYW1lcyBhcmUgcGFzdCB0ZW5zZSBiZWNhdXNlIGEgYnJvYWRjYXN0IHN0YXRlcyBzb21ldGhpbmcgdGhhdCBoYXMgYWxyZWFkeSBoYXBwZW5lZC4gYGxvYWRlZGAgaW5cbiAqIHBhcnRpY3VsYXIgY2FycmllcyBhIGd1YXJhbnRlZTogaXQgaXMgdHJpZ2dlcmVkIG9ubHkgYWZ0ZXIgZXZlcnkgQVBJIHRoZSBwbHVnaW4gZGVjbGFyZXMgaGFzIGJlZW5cbiAqIHB1Ymxpc2hlZCwgc28gYSBsaXN0ZW5lciBtYXkgY2FsbCB0aGVtIGltbWVkaWF0ZWx5LlxuICpcbiAqIEJvdGggdGhlIGV2ZW50IG5hbWVzIGFuZCB7QGxpbmsgUGx1Z2luTGlmZWN5Y2xlRXZlbnRQYXlsb2FkfSBhcmUgYSBDUk9TUy1WRVJTSU9OIENPTlRSQUNULiBDb3BpZXMgb2ZcbiAqIHRoaXMgbGlicmFyeSBhdCBkaWZmZXJlbnQgdmVyc2lvbnMgcHVibGlzaCBhbmQgY29uc3VtZSB0aGVtIHNpZGUgYnkgc2lkZSBpbiBvbmUgdmF1bHQsIHNvIG5laXRoZXIgbWF5XG4gKiBjaGFuZ2UgaW5jb21wYXRpYmx5OiBwbGFpbiBkYXRhIG9ubHksIGFuZCBuZXcgcGF5bG9hZCBmaWVsZHMgb25seSBldmVyIGFkZGVkLlxuICpcbiAqIFRoYXQgY29udHJhY3QgaXMgYWxzbyBQVUJMSVNIRUQsIGFzIG9mIHRoZSBgUGx1Z2luIEFQSSBwcm90b2NvbGAgZ3VpZGU6IHRoaXJkLXBhcnR5IHBsdWdpbnMgdGhhdCB3aWxsXG4gKiBuZXZlciBpbnN0YWxsIHRoaXMgbGlicmFyeSBhcmUgdG9sZCB0byBoYXJkY29kZSB0aGVzZSB0d28gc3RyaW5ncyBhbmQgdGhpcyBwYXlsb2FkIHNoYXBlLiBQdWJsaXNoaW5nIGl0XG4gKiBhZGRlZCBubyBuZXcgY29uc3RyYWludCBcdTIwMTQgdGhlIGNyb3NzLWNvcHkgb25lIGFib3ZlIGFscmVhZHkgZm9yYmFkZSBldmVyeSBjaGFuZ2UgYW4gb3V0c2lkZXIgY291bGRcbiAqIG5vdGljZSBcdTIwMTQgYnV0IGl0IGRvZXMgbWVhbiBhIHJlbmFtZSBpcyBub3cgZG91Ymx5IHVuYXZhaWxhYmxlLiBUaGUgYG9ic2lkaWFuLWRldi11dGlsczpgIHByZWZpeCBuYW1lcyB0aGVcbiAqIGxpYnJhcnkgcmF0aGVyIHRoYW4gdGhlIHN1YmplY3QsIHdoaWNoIGlzIGEgd2FydCwgYW5kIGEgcGVybWFuZW50IG9uZTogYSBuZXV0cmFsIGFsaWFzIHdvdWxkIG5vdCByZXRpcmVcbiAqIHRoZSBvbGQgbmFtZSAoYWxyZWFkeS1yZWxlYXNlZCBwbHVnaW5zIGVtaXQgb25seSBpdCksIHNvIGl0IHdvdWxkIGxlYXZlIGV2ZXJ5IGNvcnJlY3QgY29uc3VtZXIgbGlzdGVuaW5nXG4gKiBmb3IgYm90aCwgZm9yZXZlci5cbiAqL1xuXG5pbXBvcnQgdHlwZSB7IEFwcCB9IGZyb20gJ29ic2lkaWFuJztcblxuLyoqXG4gKiBUaGUgbmFtZSBvZiBlaXRoZXIgbGlmZWN5Y2xlIGV2ZW50LlxuICovXG5leHBvcnQgdHlwZSBQbHVnaW5MaWZlY3ljbGVFdmVudE5hbWUgPSB0eXBlb2YgUExVR0lOX0xPQURFRF9FVkVOVF9OQU1FIHwgdHlwZW9mIFBMVUdJTl9VTkxPQURFRF9FVkVOVF9OQU1FO1xuXG4vKipcbiAqIFRoZSBwYXlsb2FkIG9mIHtAbGluayBQTFVHSU5fTE9BREVEX0VWRU5UX05BTUV9IGFuZCB7QGxpbmsgUExVR0lOX1VOTE9BREVEX0VWRU5UX05BTUV9LlxuICpcbiAqIFBsYWluIGRhdGEgYnkgZGVzaWduIFx1MjAxNCBubyBjbGFzcyBpbnN0YW5jZXMgYW5kIG5vIHR5cGVzIG93bmVkIGJ5IHRoaXMgbGlicmFyeSBcdTIwMTQgYmVjYXVzZSBpdCBjcm9zc2VzXG4gKiBiZXR3ZWVuIGluZGVwZW5kZW50bHkgYnVuZGxlZCBjb3BpZXMgb2YgaXQsIGFuZCBiZXR3ZWVuIHBsdWdpbnMgdGhhdCBkbyBub3QgdXNlIGl0IGF0IGFsbC5cbiAqL1xuZXhwb3J0IGludGVyZmFjZSBQbHVnaW5MaWZlY3ljbGVFdmVudFBheWxvYWQge1xuICAvKipcbiAgICogVGhlIGNvbnRyYWN0IHZlcnNpb25zIHRoZSBwbHVnaW4gcHVibGlzaGVkLCBlbXB0eSB3aGVuIGl0IHB1Ymxpc2hlcyBubyBBUEkuXG4gICAqXG4gICAqIEFuIGFycmF5IHJhdGhlciB0aGFuIGEgc2luZ2xlIHZlcnNpb24gYmVjYXVzZSBhIHByb3ZpZGVyIG1heSBwdWJsaXNoIHNldmVyYWwgY29udHJhY3QgdmVyc2lvbnMgc2lkZSBieVxuICAgKiBzaWRlLCBzbyBjb25zdW1lcnMgcGlubmVkIHRvIGFuIG9sZGVyIHJhbmdlIGtlZXAgd29ya2luZyBhY3Jvc3MgYSBicmVha2luZyBjaGFuZ2UuXG4gICAqXG4gICAqIFRoZSBBUEkgb2JqZWN0cyB0aGVtc2VsdmVzIGFyZSBkZWxpYmVyYXRlbHkgTk9UIGhlcmUuIEEgaGFuZGxlIGRlbGl2ZXJlZCBieSBhIG9uZS1zaG90IGV2ZW50IGlzIGFcbiAgICogcHJvYmU6IGl0IGFuc3dlcnMgXCJub3dcIiBhbmQgbmV2ZXIgc2F5cyB3aGVuIFwibm93XCIgY2hhbmdlZCwgYW5kIG9uZSB0aGF0IG91dGxpdmVzIHRoZSBwcm92aWRlciBpc1xuICAgKiBleGFjdGx5IHRoZSBzdGFsZSBoYW5kbGUgdGhlIHBsdWdpbi1hcGkgcmVnaXN0cnkncyByZXZvY2FibGUgaGFuZGxlcyBleGlzdCB0byBwcmV2ZW50LiBSZWFjaCB0aGUgQVBJXG4gICAqIHRocm91Z2ggYHdhdGNoUGx1Z2luQXBpYCBpbnN0ZWFkLCB3aG9zZSByZWZlcmVuY2Ugc3RheXMgY29ycmVjdCBhY3Jvc3MgdW5sb2FkIGFuZCByZS1lbmFibGUuXG4gICAqL1xuICByZWFkb25seSBhcGlWZXJzaW9uczogcmVhZG9ubHkgc3RyaW5nW107XG5cbiAgLyoqXG4gICAqIFRoZSBpZHMgb2YgdGhlIHBsdWdpbnMgdGhpcyBvbmUgZGVjbGFyZXMgYXMgbWFuZGF0b3J5IGRlcGVuZGVuY2llcywgZW1wdHkgd2hlbiBpdCBkZWNsYXJlcyBub25lLlxuICAgKlxuICAgKiBQcmVzZW50IHNvIHRoZSByZWxhdGlvbnNoaXAgY2FuIGJlIHJlYWQgZnJvbSB0aGUgT1RIRVIgZW5kOiBhIHByb3ZpZGVyIGhhcyBubyB3YXkgdG8gYXNrIHdobyBkZXBlbmRzXG4gICAqIG9uIGl0IFx1MjAxNCB0aGUgcmVnaXN0cnkgb25seSBhbnN3ZXJzIGNvbnN1bWVyLXRvLXByb3ZpZGVyIFx1MjAxNCBhbmQgXCJ3aGljaCBpbnN0YWxsZWQgcGx1Z2lucyBuZWVkIHRoaXMgb25lXCJcbiAgICogaXMgd2hhdCBsZXRzIGEgcHJvdmlkZXIncyBzZXR0aW5ncyB0YWIgdGVsbCB0aGUgdXNlciB3aHkgaXQgaXMgaW4gdGhlaXIgdmF1bHQgYXQgYWxsLlxuICAgKi9cbiAgcmVhZG9ubHkgZGVwZW5kZW5jeVBsdWdpbklkczogcmVhZG9ubHkgc3RyaW5nW107XG5cbiAgLyoqXG4gICAqIFRoZSBwbHVnaW4ncyBgbWFuaWZlc3QuaWRgLlxuICAgKi9cbiAgcmVhZG9ubHkgcGx1Z2luSWQ6IHN0cmluZztcblxuICAvKipcbiAgICogVGhlIHBsdWdpbidzIGBtYW5pZmVzdC5uYW1lYCwgZm9yIGRpc3BsYXkuXG4gICAqL1xuICByZWFkb25seSBwbHVnaW5OYW1lOiBzdHJpbmc7XG5cbiAgLyoqXG4gICAqIFRoZSBwbHVnaW4ncyBgbWFuaWZlc3QudmVyc2lvbmAuXG4gICAqL1xuICByZWFkb25seSBwbHVnaW5WZXJzaW9uOiBzdHJpbmc7XG59XG5cbi8qKlxuICogUGFyYW1ldGVycyBmb3Ige0BsaW5rIHRyaWdnZXJQbHVnaW5MaWZlY3ljbGVFdmVudH0uXG4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgVHJpZ2dlclBsdWdpbkxpZmVjeWNsZUV2ZW50UGFyYW1zIHtcbiAgLyoqXG4gICAqIFRoZSBPYnNpZGlhbiBhcHAgaW5zdGFuY2Ugd2hvc2Ugd29ya3NwYWNlIGNhcnJpZXMgdGhlIGJyb2FkY2FzdC5cbiAgICovXG4gIHJlYWRvbmx5IGFwcDogQXBwO1xuXG4gIC8qKlxuICAgKiBUaGUgZXZlbnQgdG8gdHJpZ2dlci5cbiAgICovXG4gIHJlYWRvbmx5IG5hbWU6IFBsdWdpbkxpZmVjeWNsZUV2ZW50TmFtZTtcblxuICAvKipcbiAgICogVGhlIHBheWxvYWQgZGVzY3JpYmluZyB0aGUgcGx1Z2luLlxuICAgKi9cbiAgcmVhZG9ubHkgcGF5bG9hZDogUGx1Z2luTGlmZWN5Y2xlRXZlbnRQYXlsb2FkO1xufVxuXG4vKipcbiAqIFRyaWdnZXJlZCBvbmNlIGEgcGx1Z2luIGhhcyBmaW5pc2hlZCBsb2FkaW5nIEFORCBwdWJsaXNoZWQgZXZlcnkgQVBJIGl0IGRlY2xhcmVzLCBzbyBhIGxpc3RlbmVyIG1heSBjYWxsXG4gKiB0aG9zZSBBUElzIGltbWVkaWF0ZWx5LlxuICpcbiAqIE5hbWVzcGFjZWQgYnkgdGhlIHBhY2thZ2UgbmFtZSByYXRoZXIgdGhhbiBieSBhbiBhYmJyZXZpYXRpb24gb2YgaXQ6IHRoZSBldmVudCBpcyBnbG9iYWwgdG8gdGhlIHZhdWx0XG4gKiBhbmQgYWltZWQgYXQgcGx1Z2luIGF1dGhvcnMgd2hvIGhhdmUgbmV2ZXIgaGVhcmQgb2YgdGhpcyBsaWJyYXJ5LCBzbyB0aGUgcHJlZml4IGhhcyB0byBpZGVudGlmeSBpdHNlbGYuXG4gKi9cbmV4cG9ydCBjb25zdCBQTFVHSU5fTE9BREVEX0VWRU5UX05BTUUgPSAnb2JzaWRpYW4tZGV2LXV0aWxzOnBsdWdpbi1sb2FkZWQnO1xuXG4vKipcbiAqIFRyaWdnZXJlZCBhcyBhIHBsdWdpbiB1bmxvYWRzIFx1MjAxNCB3aGV0aGVyIHRoZSB1c2VyIGRpc2FibGVkIGl0LCB1bmluc3RhbGxlZCBpdCwgb3IgT2JzaWRpYW4gaXMgc2h1dHRpbmdcbiAqIGRvd24uIEl0cyBBUElzIGFyZSByZXZva2VkIGJ5IHRoZSB0aW1lIGEgbGlzdGVuZXIgcnVucy5cbiAqL1xuZXhwb3J0IGNvbnN0IFBMVUdJTl9VTkxPQURFRF9FVkVOVF9OQU1FID0gJ29ic2lkaWFuLWRldi11dGlsczpwbHVnaW4tdW5sb2FkZWQnO1xuXG5kZWNsYXJlIG1vZHVsZSAnb2JzaWRpYW4nIHtcbiAgaW50ZXJmYWNlIFdvcmtzcGFjZSB7XG4gICAgLyoqXG4gICAgICogU3Vic2NyaWJlcyB0byBhIHBsdWdpbiBmaW5pc2hpbmcgaXRzIGxvYWQsIG9yIHRvIG9uZSB1bmxvYWRpbmcuXG4gICAgICpcbiAgICAgKiBAcGFyYW0gbmFtZSAtIFNob3VsZCBiZSB7QGxpbmsgUExVR0lOX0xPQURFRF9FVkVOVF9OQU1FfSBvciB7QGxpbmsgUExVR0lOX1VOTE9BREVEX0VWRU5UX05BTUV9LlxuICAgICAqIEBwYXJhbSBjYWxsYmFjayAtIFRoZSBjYWxsYmFjayByZWNlaXZpbmcgdGhlIHBsdWdpbidzIHBheWxvYWQuXG4gICAgICogQHBhcmFtIGNvbnRleHQgLSBUaGUgY29udGV4dCBwYXNzZWQgYXMgYHRoaXNgIHRvIHRoZSBgY2FsbGJhY2tgIGZ1bmN0aW9uLlxuICAgICAqIEByZXR1cm5zIFRoZSBldmVudCByZWZlcmVuY2UuXG4gICAgICovXG4gICAgLypcbiAgICAgKiBBbiBhdWdtZW50YXRpb24gb2YgYW4gRVhJU1RJTkcgb3ZlcmxvYWQgc2V0IGhhcyB0byBzdGF5IGEgbWV0aG9kIHNpZ25hdHVyZS4gQSBwcm9wZXJ0eSBtZW1iZXIgZG9lcyBub3QgbWVyZ2UgaW50b1xuICAgICAqIGBXb3Jrc3BhY2Uub25gJ3Mgb3ZlcmxvYWRzLCBhbmQgVHlwZVNjcmlwdCBzYXlzIHNvIG5vd2hlcmUgbmVhciBoZXJlOiB0aGUgZGVjbGFyYXRpb24gaXRzZWxmIGNvbXBpbGVzLCBhbmQgZXZlcnlcbiAgICAgKiBjYWxsIHNpdGUgbG9zZXMgdGhlIHNpZ25hdHVyZSBpbnN0ZWFkIFx1MjAxNCBgb24oUExVR0lOX0xPQURFRF9FVkVOVF9OQU1FLCAuLi4pYCBmYWlscyB3aXRoIFwidGhlIGxhc3Qgb3ZlcmxvYWQgZ2F2ZSB0aGVcbiAgICAgKiBmb2xsb3dpbmcgZXJyb3JcIi4gVGhlIHJ1bGUgcmVwb3J0cyB0aGlzIG9uZSB3aXRob3V0IGEgZml4IGZvciB0aGUgc2FtZSByZWFzb24sIHNvIHRoZSBkaXNhYmxlIGJlbG93IGlzIHRoZSBhbnN3ZXJcbiAgICAgKiByYXRoZXIgdGhhbiBhIGRlZmVycmFsLlxuICAgICAqL1xuICAgIC8vIGVzbGludC1kaXNhYmxlLW5leHQtbGluZSBAdHlwZXNjcmlwdC1lc2xpbnQvbWV0aG9kLXNpZ25hdHVyZS1zdHlsZSAtLSBBIHByb3BlcnR5IG1lbWJlciBkb2VzIG5vdCBtZXJnZSBpbnRvIGFuIGV4aXN0aW5nIG92ZXJsb2FkIHNldC4gU2VlIGFib3ZlLlxuICAgIG9uKG5hbWU6IFBsdWdpbkxpZmVjeWNsZUV2ZW50TmFtZSwgY2FsbGJhY2s6IChwYXlsb2FkOiBQbHVnaW5MaWZlY3ljbGVFdmVudFBheWxvYWQpID0+IHVua25vd24sIGNvbnRleHQ/OiB1bmtub3duKTogRXZlbnRSZWY7XG4gIH1cbn1cblxuLyoqXG4gKiBUcmlnZ2VycyBvbmUgb2YgdGhlIHR3byBsaWZlY3ljbGUgZXZlbnRzIG9uIHRoZSBhcHAncyB3b3Jrc3BhY2UuXG4gKlxuICogQSB0aGluIHR5cGVkIHdyYXBwZXIgb3ZlciBgV29ya3NwYWNlLnRyaWdnZXJgLCB3aGljaCBhY2NlcHRzIGFueSBldmVudCBuYW1lIGFuZCBhbnkgYXJndW1lbnRzLCBzbyB0aGF0XG4gKiB0aGUgb25lIHBsYWNlIGEgcGF5bG9hZCBpcyBjb25zdHJ1Y3RlZCBpcyBjaGVja2VkIGFnYWluc3Qge0BsaW5rIFBsdWdpbkxpZmVjeWNsZUV2ZW50UGF5bG9hZH0uXG4gKlxuICogQHBhcmFtIHBhcmFtcyAtIFRoZSB7QGxpbmsgVHJpZ2dlclBsdWdpbkxpZmVjeWNsZUV2ZW50UGFyYW1zfS5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIHRyaWdnZXJQbHVnaW5MaWZlY3ljbGVFdmVudChwYXJhbXM6IFRyaWdnZXJQbHVnaW5MaWZlY3ljbGVFdmVudFBhcmFtcyk6IHZvaWQge1xuICBwYXJhbXMuYXBwLndvcmtzcGFjZS50cmlnZ2VyKHBhcmFtcy5uYW1lLCBwYXJhbXMucGF5bG9hZCk7XG59XG4iXSwKICAibWFwcGluZ3MiOiAiOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0FBNkdPLE1BQU0sMkJBQTJCO0FBTWpDLE1BQU0sNkJBQTZCO0FBZ0NuQyxTQUFTLDRCQUE0QixRQUFpRDtBQUMzRixTQUFPLElBQUksVUFBVSxRQUFRLE9BQU8sTUFBTSxPQUFPLE9BQU87QUFDMUQ7IiwKICAibmFtZXMiOiBbXQp9Cg==

package/dist/lib/esm/plugin/plugin-settings-tab.d.mts

@@ -0,0 +1,368 @@
+/// <reference path="../library.d.mts" />
+/**
+ * @file
+ *
+ * This module defines a base class for creating plugin setting tabs in Obsidian.
+ * It provides a utility method to bind value components to plugin settings and handle changes.
+ */
+import type { StringKeys } from '@mnaoumov/typescript-lib/type';
+import type { Plugin, SettingDefinitionGroup, SettingDefinitionItem, SettingDefinitionRender, SettingGroup } from 'obsidian';
+import type { ConditionalKeys, Except, Promisable, ReadonlyDeep } from 'type-fest';
+import { PluginSettingTab } from 'obsidian';
+import type { PluginSettingsComponentBase, ReadonlyPluginSettingsState } from '../components/plugin-settings-component.mjs';
+import type { ValueComponentWithChangeTracking } from '../setting-components/value-component-with-change-tracking.mjs';
+import type { SettingEx } from '../setting-ex.mjs';
+import type { ValidationMessageHolder } from '../validation.mjs';
+/**
+ * A context passed to the {@link PluginSettingsComponentBase.saveToFile} method.
+ */
+export declare const SAVE_TO_FILE_CONTEXT = "PluginSettingsTab";
+/**
+ * Options for `PluginSettingsTabBase.bind`.
+ *
+ * @typeParam T - The type of the settings property value.
+ */
+export interface BindOptions<T> {
+    /**
+     * A callback function that is called when the value of the component changes.
+     */
+    readonly onChanged?: (newValue: ReadonlyDeep<T>, oldValue: ReadonlyDeep<T>) => Promisable<void>;
+    /**
+     * Whether to reset the setting when the component value is empty.
+     * Applicable only to text-based components.
+     *
+     * @default `true`
+     */
+    readonly shouldResetSettingWhenComponentIsEmpty?: boolean;
+    /**
+     * Whether to show the placeholder for default values.
+     * Applicable only to text-based components.
+     *
+     * @default `true`
+     */
+    readonly shouldShowPlaceholderForDefaultValues?: boolean;
+    /**
+     * Whether to show the validation message when the component value is invalid.
+     *
+     * @default `true`
+     */
+    readonly shouldShowValidationMessage?: boolean;
+}
+/**
+ * Extended options for `PluginSettingsTabBase.bind`.
+ *
+ * @typeParam PluginSettings - The plugin settings type.
+ * @typeParam UIValue - The type of the UI component's value.
+ * @typeParam PropertyName - The settings property name being bound.
+ */
+export interface BindOptionsExtended<PluginSettings extends object, UIValue, PropertyName extends StringKeys<PluginSettings>> extends BindOptions<PluginSettings[PropertyName]> {
+    /**
+     * Converts the UI component's value back to the plugin settings value.
+     *
+     * @param uiValue - The value of the UI component.
+     * @returns The value to set on the plugin settings.
+     */
+    componentToPluginSettingsValueConverter: (uiValue: UIValue) => PluginSettings[PropertyName] | ValidationMessageHolder;
+    /**
+     * Converts the plugin settings value to the value used by the UI component.
+     *
+     * @param pluginSettingsValue - The value of the property in the plugin settings.
+     * @returns The value to set on the UI component.
+     */
+    pluginSettingsToComponentValueConverter: (pluginSettingsValue: ReadonlyDeep<PluginSettings[PropertyName]>) => UIValue;
+}
+/**
+ * Extended params for {@link PluginSettingsTabBase.bind} with value converters.
+ *
+ * @typeParam PluginSettings - The plugin settings type.
+ * @typeParam UIValue - The type of the UI component's value.
+ * @typeParam TValueComponent - The type of the value component.
+ * @typeParam PropertyName - The settings property name being bound.
+ */
+export interface PluginSettingsTabBaseBindExtendedParams<PluginSettings extends object, UIValue, TValueComponent, PropertyName extends StringKeys<PluginSettings>> extends BindOptionsExtended<PluginSettings, UIValue, PropertyName> {
+    /**
+     * The property name of the plugin settings to bind to.
+     */
+    readonly propertyName: PropertyName;
+    /**
+     * The value component to bind.
+     */
+    readonly valueComponent: TValueComponent & ValueComponentWithChangeTracking<UIValue>;
+}
+/**
+ * Params for {@link PluginSettingsTabBase.bind}.
+ *
+ * @typeParam PluginSettings - The plugin settings type.
+ * @typeParam UIValue - The type of the UI component's value.
+ * @typeParam TValueComponent - The type of the value component.
+ */
+export interface PluginSettingsTabBaseBindParams<PluginSettings extends object, UIValue, TValueComponent> extends BindOptions<UIValue> {
+    /**
+     * The property of the plugin settings to bind to.
+     */
+    readonly propertyName: ConditionalKeys<PluginSettings, UIValue>;
+    /**
+     * The value component to bind.
+     */
+    readonly valueComponent: TValueComponent & ValueComponentWithChangeTracking<UIValue>;
+}
+/**
+ * Params for creating a {@link PluginSettingsTabBase}.
+ *
+ * @typeParam PluginSettings - The plugin settings type.
+ */
+export interface PluginSettingsTabBaseConstructorParams<PluginSettings extends object> {
+    /**
+     * The plugin instance (needed by Obsidian's PluginSettingTab).
+     */
+    readonly plugin: Plugin;
+    /**
+     * The settings component.
+     */
+    readonly pluginSettingsComponent: PluginSettingsComponentBase<PluginSettings>;
+}
+/**
+ * Params for {@link PluginSettingsTabBase.settingEx}.
+ */
+export interface PluginSettingsTabBaseSettingExParams {
+    /**
+     * Additional search terms for the setting.
+     */
+    readonly aliases?: string[];
+    /**
+     * The description of the setting. Used for rendering; the text content of a fragment is used for search.
+     */
+    readonly desc?: DocumentFragment | string;
+    /**
+     * Whether the setting row is disabled.
+     *
+     * A function form is re-evaluated on every render AND on every {@link PluginSettingsTabBase.refreshDomState}
+     * call, so it can reflect runtime state. Obsidian applies it with `Setting.setDisabled`, which disables the
+     * row and every component registered on it.
+     */
+    readonly disabled?: (() => boolean) | boolean;
+    /**
+     * The display name of the setting. Used for rendering and search.
+     */
+    readonly name: string;
+    /**
+     * Renders the setting row imperatively, typically via the {@link SettingEx} adders and
+     * {@link PluginSettingsTabBase.bind}.
+     *
+     * The setting Obsidian creates for the row is adopted into a {@link SettingEx} before it is handed over, so
+     * an imperative row body carries over unchanged. May return a cleanup function, invoked before the row is
+     * torn down or re-rendered.
+     *
+     * @param setting - The setting to render into.
+     * @param group - The group the setting belongs to.
+     * @returns An optional cleanup function.
+     */
+    readonly render: (setting: SettingEx, group: SettingGroup) => (() => void) | void;
+    /**
+     * Controls whether the setting is included in the settings search. Defaults to `true`.
+     */
+    readonly searchable?: (() => boolean) | boolean;
+    /**
+     * Controls whether the setting row is rendered. A function form is re-evaluated on every render and on
+     * every {@link PluginSettingsTabBase.refreshDomState} call. Defaults to `true`.
+     */
+    readonly visible?: (() => boolean) | boolean;
+}
+/**
+ * Params for {@link PluginSettingsTabBase.settingGroupEx}.
+ *
+ * Every member of {@link SettingDefinitionGroup} except its discriminator, which
+ * {@link PluginSettingsTabBase.settingGroupEx} sets.
+ */
+export type PluginSettingsTabBaseSettingGroupExParams = Except<SettingDefinitionGroup, 'type'>;
+interface PluginSettingsTabBaseEventMap {
+    validationMessageChanged: [propertyName: string, validationMessage: string];
+}
+declare const PluginSettingsTabBase_base: import("type-fest").AbstractConstructor<import("@mnaoumov/typescript-lib/async-events").AsyncEventSource<PluginSettingsTabBaseEventMap> & import("@mnaoumov/typescript-lib/async-events").AsyncEventTrigger<PluginSettingsTabBaseEventMap>> & typeof PluginSettingTab;
+/**
+ * Base class for creating plugin settings tabs in Obsidian.
+ * Provides a method for binding value components to plugin settings and handling changes.
+ *
+ * @typeParam PluginSettings - The plugin settings type.
+ */
+export declare abstract class PluginSettingsTabBase<PluginSettings extends object> extends PluginSettingsTabBase_base {
+    /**
+     * Whether the plugin settings tab is open.
+     *
+     * @returns Whether the plugin settings tab is open.
+     */
+    get isOpen(): boolean;
+    /**
+     * The settings manager.
+     */
+    protected readonly pluginSettingsComponent: PluginSettingsComponentBase<PluginSettings>;
+    /**
+     * A debounce timeout for saving settings.
+     *
+     * @returns The debounce timeout for saving settings.
+     */
+    protected get saveSettingsDebounceTimeoutInMilliseconds(): number;
+    private _isOpen;
+    private readonly component;
+    private currentRenderComponent;
+    private readonly saveSettingsDebounced;
+    private get pluginSettings();
+    /**
+     * Creates a new plugin settings tab.
+     *
+     * @param params - The params.
+     */
+    constructor(params: PluginSettingsTabBaseConstructorParams<PluginSettings>);
+    /**
+     * Binds a value component to a plugin setting.
+     *
+     * @typeParam UIValue - The type of the value of the UI component.
+     * @typeParam TValueComponent - The type of the value component.
+     * @param params - The params for binding the value component.
+     * @returns The value component.
+     */
+    bind<UIValue, TValueComponent>(params: PluginSettingsTabBaseBindParams<PluginSettings, UIValue, TValueComponent>): TValueComponent;
+    /**
+     * Binds a value component to a plugin setting.
+     *
+     * @typeParam UIValue - The type of the value of the UI component.
+     * @typeParam TValueComponent - The type of the value component.
+     * @typeParam PropertyName - The property name of the plugin settings to bind to.
+     * @param params - The params for binding the value component.
+     * @returns The value component.
+     */
+    bind<UIValue, TValueComponent, PropertyName extends StringKeys<PluginSettings>>(params: PluginSettingsTabBaseBindExtendedParams<PluginSettings, UIValue, TValueComponent, PropertyName>): TValueComponent;
+    /**
+     * Renders the plugin settings tab.
+     */
+    display(): void;
+    /**
+     * Legacy way to render the plugin settings tab imperatively.
+     *
+     * The pre-declarative fallback: Obsidian only calls it when {@link getSettingDefinitions} returns an empty
+     * array, i.e. when the consumer has not overridden {@link getSettingDefinitionItems}. Such a consumer
+     * overrides this method and builds the UI with {@link SettingEx} and {@link bind}.
+     */
+    displayLegacy(): void;
+    /**
+     * Reads the value backing a native `control` setting definition.
+     *
+     * Obsidian calls it on every render of a `control`-type definition. The inherited implementation reads
+     * `plugin.settings`, which a plugin built on {@link PluginSettingsComponentBase} never populates, so it is
+     * routed to the settings component instead.
+     *
+     * @param key - The settings property name.
+     * @returns The current value.
+     */
+    getControlValue(key: string): unknown;
+    /**
+     * Returns the declarative setting definitions rendered by Obsidian 1.13+.
+     *
+     * Delegates to {@link getSettingDefinitionItems}. When a consumer has not overridden that hook it returns
+     * an empty array, and Obsidian falls back to the imperative {@link displayLegacy} path.
+     *
+     * @returns The setting definitions.
+     */
+    getSettingDefinitions(): SettingDefinitionItem[];
+    /**
+     * Hides the plugin settings tab.
+     */
+    hide(): void;
+    /**
+     * Async actions to perform when the settings tab is being hidden.
+     *
+     * @returns A {@link Promise} that resolves when the settings tab is hidden.
+     */
+    hideAsync(): Promise<void>;
+    /**
+     * Re-renders the settings tab after the underlying state changed.
+     *
+     * Rebuilds the definitions and re-renders, which covers both paths: Obsidian renders the declarative
+     * definitions when {@link getSettingDefinitionItems} provides them, and falls back to
+     * {@link displayLegacy} when it does not. Nothing is rendered while the tab is not the one on screen.
+     *
+     * Use it only for changes that alter the STRUCTURE of the tab — rows added or removed. When only a
+     * {@link PluginSettingsTabBaseSettingExParams.disabled} / {@link PluginSettingsTabBaseSettingExParams.visible}
+     * predicate has to be re-evaluated, call the much cheaper {@link refreshDomState} instead, which toggles the
+     * rendered DOM in place.
+     */
+    refresh(): void;
+    /**
+     * Persists the value of a native `control` setting definition.
+     *
+     * The counterpart of {@link getControlValue}: it routes the write to the settings component instead of the
+     * inherited `plugin.saveData` path, so validation, transformers and the debounced save all apply as they do
+     * for a {@link bind}-ed component.
+     *
+     * @param key - The settings property name.
+     * @param value - The value to persist.
+     * @returns A {@link Promise} that resolves when the value is set.
+     */
+    setControlValue(key: string, value: unknown): Promise<void>;
+    /**
+     * Shows the plugin settings tab.
+     */
+    show(): void;
+    /**
+     * The declarative setting definitions for the tab (Obsidian 1.13+).
+     *
+     * Consumers override this, typically building each row with {@link settingEx} and {@link bind} and grouping
+     * them with `settingGroupEx`. Returning an empty array — the default — makes Obsidian fall back to the
+     * imperative {@link displayLegacy} path.
+     *
+     * MUST be a pure builder. Obsidian calls it when the tab is registered (`addSettingTab`), long before the
+     * tab is ever opened, in order to index the settings for search. Anything with a side effect belongs inside
+     * a row's {@link PluginSettingsTabBaseSettingExParams.render} callback, which runs only when the row is
+     * actually rendered.
+     *
+     * @returns The setting definitions.
+     */
+    protected getSettingDefinitionItems(): SettingDefinitionItem[];
+    /**
+     * Called when the plugin settings are loaded.
+     *
+     * @param _loadedState - The loaded settings state.
+     * @param _isInitialLoad - Whether the settings are being loaded for the first time.
+     * @returns A {@link Promise} that resolves when the settings are loaded.
+     */
+    protected onLoadSettings(_loadedState: ReadonlyPluginSettingsState<PluginSettings>, _isInitialLoad: boolean): Promise<void>;
+    /**
+     * Revalidates the settings.
+     *
+     * @returns A {@link Promise} that resolves when the settings are revalidated.
+     */
+    protected revalidate(): Promise<void>;
+    /**
+     * Builds a search-indexable declarative row that is rendered imperatively.
+     *
+     * The bridge between the declarative API and this library's imperative building blocks: Obsidian owns the row (so it
+     * indexes it for search and evaluates its {@link PluginSettingsTabBaseSettingExParams.visible} /
+     * {@link PluginSettingsTabBaseSettingExParams.disabled} predicates on every
+     * {@link refreshDomState}), while {@link PluginSettingsTabBaseSettingExParams.render} fills it in with
+     * {@link SettingEx} adders and {@link bind} exactly as an imperative tab would.
+     *
+     * @param params - The row params.
+     * @returns The setting definition.
+     */
+    protected settingEx(params: PluginSettingsTabBaseSettingExParams): SettingDefinitionRender;
+    /**
+     * Builds a declarative heading group.
+     *
+     * The declarative counterpart of `SettingGroupEx`: where that class appends a group to a container
+     * imperatively, this returns the definition Obsidian renders, so a group-structured tab keeps its shape
+     * after the migration.
+     *
+     * @param params - The group params.
+     * @returns The group definition.
+     */
+    protected settingGroupEx(params: PluginSettingsTabBaseSettingGroupExParams): SettingDefinitionGroup;
+    private beginRenderCycle;
+    private createRenderComponent;
+    private endRenderCycle;
+    private getPluginSettingsProperty;
+    private getRenderComponent;
+    private onSaveSettings;
+    private renderSettingEx;
+    private updateValidations;
+}
+export {};