obsidian-dev-utils 92.0.0 → 93.0.0

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

@@ -9,6 +9,35 @@ import type { Promisable } from 'type-fest';
 import { Notice } from 'obsidian';
 import type { ValueProvider } from '../../value-provider.mjs';
 import { ComponentEx } from './component-ex.mjs';
+/**
+ * How a new notice relates to the plugin's current notice — the one occupying the single per-plugin
+ * slot this component keeps.
+ *
+ * Raw `new Notice(...)` calls always pile up, which is rarely what a plugin wants: usually only the
+ * latest message matters. So the slot exists, and this chooses what a new message does with it.
+ */
+export declare enum PluginNoticeMode {
+    /**
+     * Adds the message to the current notice, so both messages stay visible in a single notice — for a
+     * running account of an operation. The countdown restarts, so an appended message is readable for a
+     * full duration rather than inheriting the remains of the current one.
+     *
+     * Falls back to {@link PluginNoticeMode.Replace} when there is no current notice on screen (it was
+     * never shown, or it has since been dismissed).
+     */
+    Append = "append",
+    /**
+     * Hides the current notice and shows this one in its place, so only the latest message is on screen.
+     * This is the default, and the reason the slot exists.
+     */
+    Replace = "replace",
+    /**
+     * Shows the message as its own notice, leaving the current one alone: both are on screen, piled up
+     * like plain `new Notice(...)` calls. A separate notice never replaces, and is never replaced by, a
+     * slot notice; any number of them coexist. They are still hidden together on unload.
+     */
+    Separate = "separate"
+}
 /**
  * The event passed to {@link PluginNoticeComponentShowNoticeOptions.onCloseClick} when the notice's
  * close (X) button is clicked.
@@ -26,10 +55,14 @@ export interface PluginNoticeCloseClickEvent {
  */
 export interface PluginNoticeComponentDelayedNotice extends Disposable {
     /**
-     * Replaces the notice content, re-applying the plugin-name prefix, the interactive-click guard, and
+     * Replaces this handle's message, re-applying the plugin-name prefix, the interactive-click guard, and
      * the Cancel button. Useful for reporting progress. If the delay has not elapsed yet, the new content
      * becomes what is shown once it does.
      *
+     * Only this handle's own message is rewritten: when the notice was joined rather than opened (see
+     * {@link PluginNoticeComponentShowNoticeAfterDelayParams.mode}), the messages already in it are left
+     * alone.
+     *
      * @param content - The new notice content.
      */
     setContent(content: DocumentFragment | string): void;
@@ -60,6 +93,20 @@ export interface PluginNoticeComponentShowNoticeAfterDelayParams {
      * @default `500`
      */
     readonly delayInMilliseconds?: number;
+    /**
+     * How this notice relates to the plugin's current notice — see {@link PluginNoticeMode}.
+     *
+     * {@link PluginNoticeMode.Separate} is worth considering for a long operation: on the default
+     * {@link PluginNoticeMode.Replace} the progress notice takes the shared slot, so any ordinary notice
+     * raised while the operation runs hides it, and the progress the user was watching does not come back.
+     *
+     * Whichever mode is used, the returned handle owns only ITS message: updating the content rewrites
+     * that message alone, and disposing takes away only that message when the notice was already on
+     * screen (a notice this handle opened is hidden as a whole).
+     *
+     * @default {@link PluginNoticeMode.Replace}
+     */
+    readonly mode?: PluginNoticeMode;
 }
 /**
  * Options for {@link PluginNoticeComponent.showNotice}.
@@ -77,18 +124,17 @@ export interface PluginNoticeComponentShowNoticeOptions {
      */
     readonly isPermanent?: boolean;
     /**
-     * Whether the notice occupies the single per-plugin reusable slot.
-     *
-     * A reusable notice takes the shared slot: the next reusable notice hides it, and it is hidden on unload.
-     * A non-reusable (standalone) notice is not placed in the slot — it never hides, and is never hidden by, a
-     * reusable notice; multiple standalone notices coexist. Standalone notices are still hidden together on unload.
+     * How this notice relates to the plugin's current notice — see {@link PluginNoticeMode}.
      *
-     * A permanent notice must be reusable ({@link PluginNoticeComponentShowNoticeOptions.isPermanent} implies
-     * `isReusable`); passing `isReusable: false` together with `isPermanent: true` throws.
+     * A permanent notice cannot be {@link PluginNoticeMode.Separate} (it needs the shared slot it is
+     * tracked in), and a notice that does not hide on click must be
+     * {@link PluginNoticeMode.Separate} (so a later notice never silently replaces it); either
+     * contradiction throws.
      *
-     * @default `true`
+     * @default {@link PluginNoticeMode.Replace}, or {@link PluginNoticeMode.Separate} when
+     * {@link PluginNoticeComponentShowNoticeOptions.shouldHideOnClick} is `false`
      */
-    readonly isReusable?: boolean;
+    readonly mode?: PluginNoticeMode;
     /**
      * A callback invoked when the user clicks the close (X) button, before the notice is hidden. Call
      * {@link PluginNoticeCloseClickEvent.cancel} on the event to cancel the close and keep the notice
@@ -113,9 +159,10 @@ export interface PluginNoticeComponentShowNoticeOptions {
      * {@link PluginNoticeComponentShowNoticeOptions.shouldShowCloseButton} and
      * {@link PluginNoticeComponentShowNoticeOptions.onCloseClick}).
      *
-     * A `shouldHideOnClick: false` notice is shown with an infinite duration and is standalone (implies
-     * {@link PluginNoticeComponentShowNoticeOptions.isReusable} `= false`), so a later notice never
-     * silently replaces it; passing `isReusable: true` together with `shouldHideOnClick: false` throws.
+     * A `shouldHideOnClick: false` notice is shown with an infinite duration and stands on its own
+     * (implies {@link PluginNoticeMode.Separate}), so a later notice never silently replaces it; passing
+     * any other {@link PluginNoticeComponentShowNoticeOptions.mode} together with `shouldHideOnClick: false`
+     * throws.
      *
      * @default `true`
      */
@@ -151,7 +198,9 @@ interface PluginNoticeComponentConstructorParams {
     readonly pluginName: string;
 }
 /**
- * Manages showing plugin notices. Automatically hides the previous notice when a new one is shown.
+ * Manages showing plugin notices. By default a new notice hides the previous one, so only the latest
+ * message is on screen; {@link PluginNoticeComponentShowNoticeOptions.mode} chooses otherwise — see
+ * {@link PluginNoticeMode}.
  */
 export declare class PluginNoticeComponent extends ComponentEx {
     /**
@@ -221,6 +270,24 @@ export declare class PluginNoticeComponent extends ComponentEx {
      * @param params - The parameters.
      */
     private appendCloseButton;
+    /**
+     * Adds a message to the notice currently in the per-plugin slot, so both messages stay on screen in a
+     * single notice.
+     *
+     * The appended message carries no plugin-name prefix — the notice already opens with one, and
+     * repeating it on every line reads as noise. It is wrapped like any other notice content, so a link or
+     * button inside it still keeps the notice open when clicked.
+     *
+     * Appending restarts the notice's countdown ({@link Notice.setAutoHide}), so the new message gets a
+     * full duration instead of inheriting what was left of the current one — a line appended a moment
+     * before the notice expires would otherwise flash and vanish.
+     *
+     * @param params - The parameters.
+     * @returns The {@link PluginNoticeComponentShownNotice} describing the joined notice, or `null` when
+     * there is nothing on screen to append to — the slot is empty, or its notice has since been dismissed
+     * — and the caller should show a new notice instead.
+     */
+    private appendToCurrentNotice;
     /**
      * Builds the message for a delayed notice: the resolved content, optionally followed by a Cancel
      * button that aborts the provided controller when clicked.
@@ -236,7 +303,7 @@ export declare class PluginNoticeComponent extends ComponentEx {
      * input, etc.) and stops them there, so the element's own handler still runs but the notice stays.
      *
      * @param params - The parameters.
-     * @returns A {@link DocumentFragment} holding the wrapped, prefixed notice content.
+     * @returns The {@link PluginNoticeComponentNoticeContent} holding the wrapped notice content.
      */
     private buildNoticeContent;
     /**
@@ -272,12 +339,14 @@ export declare class PluginNoticeComponent extends ComponentEx {
     private installUserClickTracking;
     private setPermanentNotice;
     /**
-     * Shows a notice with the given duration. A reusable notice replaces the current reusable notice (and
-     * is optionally registered as this plugin's permanent notice); a standalone notice is tracked
-     * separately, leaving the reusable slot untouched.
+     * Shows a notice with the given duration, placing it according to its {@link PluginNoticeMode}: a
+     * {@link PluginNoticeMode.Replace} notice takes the per-plugin slot (hiding whatever was in it, and
+     * optionally registering as this plugin's permanent notice), an {@link PluginNoticeMode.Append} one
+     * joins the notice already in the slot, and a {@link PluginNoticeMode.Separate} one is tracked on its
+     * own, leaving the slot untouched.
      *
      * @param params - The parameters.
-     * @returns The created notice.
+     * @returns The {@link PluginNoticeComponentShownNotice} describing where the message ended up.
      */
     private showNoticeWithDuration;
     /**