/** * @file * * Mock of Obsidian's `Setting`, one row of a settings tab with a name, description and controls. */ import type { ButtonComponent as ButtonComponentOriginal, ColorComponent as ColorComponentOriginal, DisplayValueComponent as DisplayValueComponentOriginal, DropdownComponent as DropdownComponentOriginal, ExtraButtonComponent as ExtraButtonComponentOriginal, IconName as IconNameOriginal, MomentFormatComponent as MomentFormatComponentOriginal, ProgressBarComponent as ProgressBarComponentOriginal, SearchComponent as SearchComponentOriginal, Setting as SettingOriginal, SliderComponent as SliderComponentOriginal, TextAreaComponent as TextAreaComponentOriginal, TextComponent as TextComponentOriginal, ToggleComponent as ToggleComponentOriginal, TooltipOptions as TooltipOptionsOriginal } from 'obsidian'; import type { BaseComponent } from './BaseComponent.cjs'; /** * Mock of Obsidian's `Setting`, a settings row with an info area (name and description) and a control area. * * The row is built as Obsidian builds it: `settingEl` (`setting-item`) holds `infoEl` (`setting-item-info`), which * holds `nameEl` (`setting-item-name`) and `descEl` (`setting-item-description`), followed by `controlEl` * (`setting-item-control`). * * Each `add*` method creates the real mock component in {@link Setting.controlEl}, hands it to the callback * synchronously, and (except for {@link Setting.addDisplayValue}, as in Obsidian) records it in * {@link Setting.components}. */ export declare class Setting { /** * The components added to the row, in the order they were added. */ components: BaseComponent[]; /** * The element holding the row's controls. */ controlEl: HTMLElement; /** * The element holding the row's description. */ descEl: HTMLElement; /** * Whether the row is disabled, as set by {@link Setting.setDisabled}. */ disabled: boolean; /** * The validation error element created by {@link Setting.setErrorMessage}, or `null` when no error is shown. */ errorEl: HTMLElement | null; /** * The element holding the row's icon, created by {@link Setting.setIcon} on its first call and `null` until then. */ iconEl: HTMLDivElement | null; /** * The element holding the row's name and description. */ infoEl: HTMLElement; /** * The element holding the row's name. */ nameEl: HTMLElement; /** * The handler run when the row is clicked, as recorded by {@link Setting.setRowClick}, or `null` when the row has no * handler. */ rowClick: (() => void) | null; /** * The row's outer element. */ settingEl: HTMLElement; /** * Creates the setting row inside `containerEl`. * * @param containerEl - The element to create the row in. */ constructor(containerEl: HTMLElement); /** * Mock-only factory: creates a setting row, spyable via `vi.spyOn(Setting, 'create__')`. * * @param containerEl - The element to create the row in. * @returns The new setting row. */ static create__(containerEl: HTMLElement): Setting; /** * Mock-only: views a value typed as Obsidian's `Setting` as this mock. * * @param value - The value typed as the original `Setting`. * @returns The same object, typed as the mock. */ static fromOriginalType__(value: SettingOriginal): Setting; /** * Adds a button to the row. * * @param callback - Called with the new button, to configure it. * @returns This setting, for chaining. */ addButton(callback: (component: ButtonComponentOriginal) => unknown): this; /** * Adds a color picker to the row. * * @param callback - Called with the new color picker, to configure it. * @returns This setting, for chaining. */ addColorPicker(callback: (component: ColorComponentOriginal) => unknown): this; /** * Adds a custom component to the row. * * @param callback - Called with {@link Setting.controlEl}; returns the component it created there. * @returns This setting, for chaining. */ addComponent(callback: (el: HTMLElement) => BaseComponent): this; /** * Adds a read-only display value to the row. On a navigable row, Obsidian uses it to surface the value edited on * the page the row opens. As in Obsidian, it is not recorded in {@link Setting.components}. * * @param callback - Called with the new display value component, to configure it. * @returns This setting, for chaining. */ addDisplayValue(callback: (component: DisplayValueComponentOriginal) => unknown): this; /** * Adds a dropdown to the row. * * @param callback - Called with the new dropdown, to configure it. * @returns This setting, for chaining. */ addDropdown(callback: (component: DropdownComponentOriginal) => unknown): this; /** * Adds an extra (icon) button to the row. * * @param callback - Called with the new button, to configure it. * @returns This setting, for chaining. */ addExtraButton(callback: (component: ExtraButtonComponentOriginal) => unknown): this; /** * Adds a moment.js date format input to the row. * * @param callback - Called with the new format input, to configure it. * @returns This setting, for chaining. */ addMomentFormat(callback: (component: MomentFormatComponentOriginal) => unknown): this; /** * Adds a progress bar to the row. * * @param callback - Called with the new progress bar, to configure it. * @returns This setting, for chaining. */ addProgressBar(callback: (component: ProgressBarComponentOriginal) => unknown): this; /** * Adds a search input to the row. * * @param callback - Called with the new search input, to configure it. * @returns This setting, for chaining. */ addSearch(callback: (component: SearchComponentOriginal) => unknown): this; /** * Adds a slider to the row. * * @param callback - Called with the new slider, to configure it. * @returns This setting, for chaining. */ addSlider(callback: (component: SliderComponentOriginal) => unknown): this; /** * Adds a single-line text input to the row. * * As in Obsidian, when `Platform.hasPhysicalKeyboard` is `false` the input is blurred on `Enter`, dismissing the * soft keyboard rather than letting the key reach a single-line field. An event that is composing or already * default-prevented is left alone. This is the only `add*` method Obsidian guards this way. * * @param callback - Called with the new text input, to configure it. * @returns This setting, for chaining. */ addText(callback: (component: TextComponentOriginal) => unknown): this; /** * Adds a multi-line text area to the row. * * @param callback - Called with the new text area, to configure it. * @returns This setting, for chaining. */ addTextArea(callback: (component: TextAreaComponentOriginal) => unknown): this; /** * Adds a toggle switch to the row, marking the row `mod-toggle` once the callback has run, as Obsidian does. * * @param callback - Called with the new toggle, to configure it. * @returns This setting, for chaining. */ addToggle(callback: (component: ToggleComponentOriginal) => unknown): this; /** * Mock-only: views this mock as Obsidian's `Setting` type. * * @returns The same object, typed as the original `Setting`. */ asOriginalType__(): SettingOriginal; /** * Removes the row's controls: empties {@link Setting.controlEl} and {@link Setting.components}, drops the error * element and removes the `is-invalid` class, as Obsidian does. * * @returns This setting, for chaining. */ clear(): this; /** * Mock-only construction hook, called at the end of the constructor; a no-op meant for * `vi.spyOn(Setting.prototype, 'constructor__')`. * * @param _containerEl - The element the row was created in. */ constructor__(_containerEl: HTMLElement): void; /** * Makes the whole row act as a button: adds the `mod-action` and `tappable` classes and runs `callback` when the * row is clicked. * * @param callback - Called when the row is clicked. * @returns This setting, for chaining. */ setAction(callback: () => void): this; /** * Adds one or more CSS classes to the row's element. As in Obsidian, the string is split on spaces first, so a * multi-class string adds every class rather than throwing, and empty parts are dropped. * * @param cls - The class name, or several separated by spaces. * @returns This setting, for chaining. */ setClass(cls: string): this; /** * Sets the row's description, replacing the content of {@link Setting.descEl} with the text or the fragment. * * @param desc - The description, as text or as a fragment. * @returns This setting, for chaining. */ setDesc(desc: DocumentFragment | string): this; /** * Disables or enables the row: records {@link Setting.disabled}, toggles the `is-disabled` class on * {@link Setting.settingEl}, and disables or enables every component in {@link Setting.components}. * * @param disabled - Whether the row is disabled. * @returns This setting, for chaining. */ setDisabled(disabled: boolean): this; /** * Shows a persistent validation error below the setting and adds the `is-invalid` class to the row. An empty * string or `null` hides the error element and removes the class. As in Obsidian, the element is created once, in * {@link Setting.controlEl}, and is then kept and re-shown rather than detached — so {@link Setting.errorEl} stays * set until {@link Setting.clear} drops it. * * @param message - The error message, or an empty string or `null` to clear it. * @returns This setting, for chaining. */ setErrorMessage(message: null | string): this; /** * Styles the row as a section heading, by adding the `setting-item-heading` class. * * @returns This setting, for chaining. */ setHeading(): this; /** * Sets the row's icon, shown before the info area. As in Obsidian, {@link Setting.iconEl} is created on the first * call only, as a `setting-item-icon` div prepended to {@link Setting.settingEl}, and a `null` or empty id empties * that element rather than removing it — so the element stays set once a first call has made it. * * Obsidian renders the icon into that element; the mock only records its id in the element's `data-icon` attribute, * as it does for the chevron {@link Setting.setNavigable} adds. Emptying therefore drops the attribute as well as * the element's children. * * @param icon - The icon id, or `null` to empty the icon element. * @returns This setting, for chaining. */ setIcon(icon: IconNameOriginal | null): this; /** * Sets the row's name, replacing the content of {@link Setting.nameEl} with the text or the fragment. * * @param name - The name, as text or as a fragment. * @returns This setting, for chaining. */ setName(name: DocumentFragment | string): this; /** * Makes the row navigable: adds the `mod-navigable` and `tappable` classes, appends a chevron to * {@link Setting.controlEl}, and runs `callback` when the row is clicked, as {@link Setting.setAction} does. * * Obsidian renders the chevron's icon; the mock only records its id in the element's `data-icon` attribute. * * @param callback - Called when the row is clicked. * @returns This setting, for chaining. */ setNavigable(callback: () => void): this; /** * Hides the row's info area ({@link Setting.infoEl}), for a row that is all control. * * @returns This setting, for chaining. */ setNoInfo(): this; /** * Records the handler run when the row is clicked, in {@link Setting.rowClick}, attaching the listener the first * time only, as Obsidian does — so a later call replaces the handler rather than adding a second listener. A * disabled row and an event whose default was already prevented are both ignored. * * Unlike {@link Setting.setAction} and {@link Setting.setNavigable}, which are both built on it, this returns * nothing and so does not chain. * * @param callback - Called when the row is clicked. */ setRowClick(callback: () => void): void; /** * Sets the row's tooltip on {@link Setting.nameEl}, the element Obsidian tooltips, through `setTooltip`, as * Obsidian does. * * @param tooltip - The tooltip text. * @param options - How the tooltip is displayed. * @returns This setting, for chaining. */ setTooltip(tooltip: string, options?: TooltipOptionsOriginal): this; /** * Shows or hides the setting. * * @param visible - Whether the setting should be visible. * @returns This setting, for chaining. */ setVisibility(visible: boolean): this; /** * Calls `callback` with this setting, to keep configuration in one chain. * * @param callback - Called with this setting. * @returns This setting, for chaining. */ then(callback: (setting: this) => unknown): this; }