@mnaoumov/obsidian-lib 0.0.0 → 1.0.1

package/dist/lib/cjs/components/plugin-notice-component.d.cts

@@ -0,0 +1,362 @@
+/// <reference path="../library.d.cts" />
+/**
+ * @file
+ *
+ * Component that manages displaying notices to the user.
+ */
+import type { ValueProvider } from '@mnaoumov/typescript-lib/value-provider' with { 'resolution-mode': 'import' };
+import type { App } from 'obsidian' with { 'resolution-mode': 'import' };
+import type { Promisable } from 'type-fest' with { 'resolution-mode': 'import' };
+import { Notice } from 'obsidian';
+import { ComponentEx } from './component-ex.cjs';
+/**
+ * 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.
+ */
+export interface PluginNoticeCloseClickEvent {
+    /**
+     * Cancels the close, leaving the notice open.
+     */
+    cancel: () => void;
+}
+/**
+ * A handle to a delayed notice created by {@link PluginNoticeComponent.showNoticeAfterDelay}. It is a
+ * {@link Disposable} (so it can be used with `using`) that also lets the content be updated while the
+ * notice is shown.
+ */
+export interface PluginNoticeComponentDelayedNotice extends Disposable {
+    /**
+     * 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;
+}
+/**
+ * Parameters for {@link PluginNoticeComponent.showNoticeAfterDelay}.
+ */
+export interface PluginNoticeComponentShowNoticeAfterDelayParams {
+    /**
+     * When provided, a Cancel button is appended to the notice; clicking it aborts this controller. When
+     * omitted, no Cancel button is shown.
+     */
+    readonly abortController?: AbortController;
+    /**
+     * The text of the Cancel button shown when {@link PluginNoticeComponentShowNoticeAfterDelayParams.abortController}
+     * is provided. When omitted, the localized `Cancel` label is used.
+     */
+    readonly cancelButtonText?: string;
+    /**
+     * The notice content, resolved lazily only if the delay elapses — so an operation that finishes
+     * sooner never builds it.
+     */
+    readonly content: ValueProvider<DocumentFragment | string>;
+    /**
+     * How long the operation must run before the notice is shown. Operations that finish sooner never
+     * show a notice, avoiding a distracting flash.
+     *
+     * @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}.
+ */
+export interface PluginNoticeComponentShowNoticeOptions {
+    /**
+     * Whether the notice should stay until it is replaced, the plugin is reloaded, or the user dismisses it.
+     *
+     * A permanent notice is shown with an infinite duration and is not hidden when the component unloads, so it can
+     * communicate state that outlives the plugin (e.g. a cleanup that requires a reload). There is at most one permanent
+     * notice per plugin: it is hidden by the next {@link PluginNoticeComponent.showNotice} call and dismissed
+     * automatically the next time the component loads (i.e. when the plugin is re-enabled).
+     *
+     * @default `false`
+     */
+    readonly isPermanent?: boolean;
+    /**
+     * How this notice relates to the plugin's current notice — see {@link PluginNoticeMode}.
+     *
+     * 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 {@link PluginNoticeMode.Replace}, or {@link PluginNoticeMode.Separate} when
+     * {@link PluginNoticeComponentShowNoticeOptions.shouldHideOnClick} is `false`
+     */
+    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
+     * open — for example after your own confirmation declines. An async callback is awaited before the
+     * notice is hidden. Runs only when a close button is shown (both
+     * {@link PluginNoticeComponentShowNoticeOptions.shouldHideOnClick} `= false` and
+     * {@link PluginNoticeComponentShowNoticeOptions.shouldShowCloseButton} are set).
+     */
+    readonly onCloseClick?: (event: PluginNoticeCloseClickEvent) => Promisable<void>;
+    /**
+     * A callback invoked when the notice is hidden — whether by the user closing it, by a later reusable
+     * notice replacing it, by its duration elapsing, or on component unload. It runs at most once per
+     * notice. The {@link PluginNoticeHideInfo} argument distinguishes a user close (the close button) from
+     * a programmatic hide. An async callback is run fire-and-forget (its rejection surfaces through the
+     * async-error pipeline).
+     */
+    readonly onHide?: (info: PluginNoticeHideInfo) => Promisable<void>;
+    /**
+     * Whether clicking the notice hides it. When `true` (the default), the notice dismisses on click like
+     * a normal Obsidian notice. When `false`, the notice is hard to close: it does not dismiss on any stray
+     * click, and instead shows a close (X) button that hides it directly (see
+     * {@link PluginNoticeComponentShowNoticeOptions.shouldShowCloseButton} and
+     * {@link PluginNoticeComponentShowNoticeOptions.onCloseClick}).
+     *
+     * 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`
+     */
+    readonly shouldHideOnClick?: boolean;
+    /**
+     * Whether the close (X) button is shown on a hard-to-close notice
+     * ({@link PluginNoticeComponentShowNoticeOptions.shouldHideOnClick} `= false`). When `false`, no close
+     * button is rendered and the notice can only be hidden programmatically. Ignored unless
+     * `shouldHideOnClick` is `false`.
+     *
+     * @default `true`
+     */
+    readonly shouldShowCloseButton?: boolean;
+}
+/**
+ * Describes why a notice was hidden, passed to {@link PluginNoticeComponentShowNoticeOptions.onHide}.
+ */
+export interface PluginNoticeHideInfo {
+    /**
+     * Whether the notice was hidden by the user clicking its close (X) button specifically. Always implies
+     * {@link PluginNoticeHideInfo.isUserAction}.
+     */
+    readonly isCloseButtonClicked: boolean;
+    /**
+     * Whether the notice was hidden by a user action — clicking the close (X) button, or clicking a
+     * dismissible notice to dismiss it — as opposed to programmatically (a later reusable notice replacing
+     * it, an explicit `hide()`, the duration elapsing, or component unload).
+     */
+    readonly isUserAction: boolean;
+}
+interface PluginNoticeComponentConstructorParams {
+    readonly app: App;
+    readonly pluginName: string;
+}
+/**
+ * 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 {
+    /**
+     * The Obsidian app instance.
+     */
+    protected readonly app: App;
+    /**
+     * The plugin name (shown as prefix in notices).
+     */
+    protected readonly pluginName: string;
+    private readonly closeButtonClickedNotices;
+    private notice;
+    private readonly pendingTimerCancellations;
+    private readonly standaloneNotices;
+    private readonly userClickedNotices;
+    /**
+     * Creates a new plugin notice component.
+     *
+     * @param params - The constructor parameters.
+     */
+    constructor(params: PluginNoticeComponentConstructorParams);
+    /**
+     * Dismisses the permanent notice left over from a previous load (e.g. a previous plugin session) on load.
+     */
+    onload(): void;
+    /**
+     * Hides the current notice on unload, unless it is the permanent notice (which is meant to outlive the plugin).
+     */
+    onunload(): void;
+    /**
+     * Displays a notice message to the user.
+     *
+     * @param message - The message to display.
+     * @param options - The options for displaying the notice.
+     * @returns The notice object.
+     */
+    showNotice(message: DocumentFragment | string, options?: PluginNoticeComponentShowNoticeOptions): Notice;
+    /**
+     * Shows a notice describing a long-running operation, but only once the operation has run for longer
+     * than {@link PluginNoticeComponentShowNoticeAfterDelayParams.delayInMilliseconds} — so operations
+     * that finish sooner never flash a notice. The notice stays until the returned {@link Disposable} is
+     * disposed (which also cancels the pending timer if it has not fired yet), so it can be used with
+     * `using`. When an {@link PluginNoticeComponentShowNoticeAfterDelayParams.abortController} is given, a
+     * Cancel button that aborts it is appended (and, being interactive, does not dismiss the notice).
+     *
+     * @example
+     * ```ts
+     * using _notice = pluginNoticeComponent.showNoticeAfterDelay({
+     *   abortController,
+     *   content: () => buildProgressFragment()
+     * });
+     * await runOperation(abortController.signal);
+     * ```
+     *
+     * @param params - The parameters.
+     * @returns A {@link PluginNoticeComponentDelayedNotice} that hides the notice (or cancels the pending
+     * timer) when disposed and lets the content be updated while it is shown.
+     */
+    showNoticeAfterDelay(params: PluginNoticeComponentShowNoticeAfterDelayParams): PluginNoticeComponentDelayedNotice;
+    /**
+     * Appends a close (X) button to the notice content. Clicking it fires
+     * {@link PluginNoticeComponentAppendCloseButtonParams.onCloseClick} (which may cancel the close); if
+     * not cancelled, it hides the notice and drops it from the standalone-notice tracking set. The hide is
+     * marked as a close-button click so {@link PluginNoticeComponentShowNoticeOptions.onHide} can
+     * distinguish it.
+     *
+     * @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.
+     *
+     * @param params - The parameters.
+     * @returns A {@link DocumentFragment} holding the content and, if requested, a Cancel button.
+     */
+    private buildDelayedNoticeMessage;
+    /**
+     * Builds the notice content wrapped in a container that keeps the notice open when an interactive
+     * element inside it is clicked. Obsidian dismisses a notice on any click that bubbles up to its
+     * element; the container intercepts clicks originating on an interactive element (a link, button,
+     * input, etc.) and stops them there, so the element's own handler still runs but the notice stays.
+     *
+     * @param params - The parameters.
+     * @returns The {@link PluginNoticeComponentNoticeContent} holding the wrapped notice content.
+     */
+    private buildNoticeContent;
+    /**
+     * Builds the notice content, prefixing the message with the plugin name in a styled element so it is
+     * visually distinguished from the message body.
+     *
+     * @param message - The message to display after the plugin name prefix.
+     * @returns A {@link DocumentFragment} with the styled plugin name prefix followed by the message.
+     */
+    private buildPrefixedMessage;
+    private getPermanentNotice;
+    private getPermanentNotices;
+    /**
+     * Makes a notice hard to close: marks its outer element (so the CSS neutralizes its padding) and
+     * installs a capture-phase click guard that stops every click except on an interactive element (a
+     * button, link, the close button, etc.) from reaching Obsidian's own dismiss handler — so an
+     * interactive child's own handler still runs while a stray click cannot dismiss the notice.
+     *
+     * @param notice - The notice to guard.
+     * @param requiresExplicitClose - Whether the notice requires explicit close; when `false`, nothing is
+     * installed.
+     */
+    private installExplicitCloseGuards;
+    /**
+     * Tracks a click on the notice so {@link PluginNoticeComponentShowNoticeOptions.onHide} can report a
+     * user dismissal. Obsidian hides a dismissible notice synchronously during the click, so a
+     * capture-phase listener marks the notice before that hide runs; the mark is cleared after the event
+     * so a later programmatic hide is not misattributed. A close-button click is tracked separately (see
+     * {@link PluginNoticeComponent.appendCloseButton}).
+     *
+     * @param notice - The notice to track.
+     */
+    private installUserClickTracking;
+    private setPermanentNotice;
+    /**
+     * 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 {@link PluginNoticeComponentShownNotice} describing where the message ended up.
+     */
+    private showNoticeWithDuration;
+    /**
+     * Wraps a notice's `hide` so the given callback runs the first time the notice is hidden — by the
+     * user, by a replacing notice, by its duration elapsing, or on unload. Does nothing when no callback
+     * is given.
+     *
+     * @param notice - The notice whose `hide` to wrap.
+     * @param onHide - The callback to invoke on the first hide, or `undefined` to skip wrapping.
+     */
+    private wireOnHide;
+}
+export {};