@mnaoumov/obsidian-lib 0.0.0 → 1.0.0

package/dist/lib/cjs/plugin/plugin-settings-tab.d.cts

@@ -0,0 +1,368 @@
+/// <reference path="../library.d.cts" />
+/**
+ * @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' with { 'resolution-mode': 'import' };
+import type { Plugin, SettingDefinitionGroup, SettingDefinitionItem, SettingDefinitionRender, SettingGroup } from 'obsidian' with { 'resolution-mode': 'import' };
+import type { ConditionalKeys, Except, Promisable, ReadonlyDeep } from 'type-fest' with { 'resolution-mode': 'import' };
+import { PluginSettingTab } from 'obsidian';
+import type { PluginSettingsComponentBase, ReadonlyPluginSettingsState } from '../components/plugin-settings-component.cjs';
+import type { ValueComponentWithChangeTracking } from '../setting-components/value-component-with-change-tracking.cjs';
+import type { SettingEx } from '../setting-ex.cjs';
+import type { ValidationMessageHolder } from '../validation.cjs';
+/**
+ * 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", { with: { 'resolution-mode': 'import' } }).AbstractConstructor<import("@mnaoumov/typescript-lib/async-events", { with: { 'resolution-mode': 'import' } }).AsyncEventSource<PluginSettingsTabBaseEventMap> & import("@mnaoumov/typescript-lib/async-events", { with: { 'resolution-mode': 'import' } }).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 {};