obsidian-dev-utils 96.5.4 → 96.6.0

package/dist/lib/esm/obsidian/modals/modal-command-builder.d.mts

@@ -0,0 +1,281 @@
+/// <reference path="../../library.d.mts" />
+/**
+ * @file
+ *
+ * A builder for a modal's control strip.
+ *
+ * {@link ModalCommandBuilder} assembles the strip of controls shown at the bottom of a modal:
+ * keyboard-command hints ({@link ModalCommandBuilder.addKeyboardCommand}), interactive checkboxes bound to
+ * a modifier+key shortcut ({@link ModalCommandBuilder.addCheckbox}), and dropdowns bound to a modifier+key
+ * shortcut ({@link ModalCommandBuilder.addDropDown}). Chain the `add*` calls, then apply everything to a
+ * modal with {@link ModalCommandBuilder.build}:
+ *
+ * ```ts
+ * new ModalCommandBuilder()
+ *   .addKeyboardCommand({ key: 'Enter', modifiers: ['Mod'], onKey, purpose: 'to create' })
+ *   .addCheckbox({ key: '1', modifiers: ['Alt'], onChange, onInit, purpose: 'Fix footnotes' })
+ *   .build(modal);
+ * ```
+ *
+ * The strip is described by two independent axes:
+ *
+ * - **Where it is hosted.** A {@link SuggestModal} in {@link ModalCommandsRenderMode.Instructions} mode
+ *   keeps Obsidian's own instruction bar (`setInstructions` + `instructionsEl`). Every other target — a
+ *   plain {@link Modal}, or a bare {@link ModalCommandsHost} of an element plus a `Scope` — gets a strip
+ *   element the builder creates itself.
+ * - **How each control looks.** {@link ModalCommandsRenderMode.Instructions} renders the purpose text with
+ *   an inline checkbox or dropdown; {@link ModalCommandsRenderMode.Buttons} renders one clickable button
+ *   per control, carrying its pressed and disabled state.
+ *
+ * The axes are independent because a button strip inside a {@link SuggestModal} is a real combination.
+ *
+ * {@link ModalCommandBuilder.build} always registers the essential navigation/action key handlers, but
+ * only renders the control UI and registers the option-toggle shortcuts when
+ * {@link ModalCommandBuilderBuildOptions.shouldShowInstructions} is `true` (the default).
+ */
+import type { KeymapContext, Modal, Modifier, Scope, SuggestModal } from 'obsidian';
+import { DropdownComponent } from 'obsidian';
+/**
+ * The way {@link ModalCommandBuilder.build} renders each control.
+ */
+export declare enum ModalCommandsRenderMode {
+    /**
+     * One clickable button per control, carrying its pressed (`aria-pressed`) and disabled state.
+     *
+     * Only controls reachable by pointer are rendered — checkboxes, and keyboard commands that supply
+     * {@link KeyboardCommand.onActivate}. A hint-only or keyboard-only command still registers its handler
+     * but renders no button, because a button nobody can press is worse than no button. A dropdown throws:
+     * a control that CYCLES has no button form.
+     */
+    Buttons = "buttons",
+    /**
+     * Obsidian's instruction-bar look: the shortcut, then the purpose text with an inline checkbox or
+     * dropdown.
+     */
+    Instructions = "instructions"
+}
+/**
+ * A checkbox command shown in a modal's control strip and bound to a modifier+key shortcut that toggles
+ * it.
+ */
+export interface CheckboxCommand extends CommandBase {
+    /**
+     * Called when the checkbox value changes.
+     *
+     * @param isChecked - The new checked state.
+     */
+    onChange(isChecked: boolean): void;
+    /**
+     * Called once with the created checkbox element, to initialize its state.
+     *
+     * In {@link ModalCommandsRenderMode.Buttons} mode the element is created but never appended — the
+     * button is a view of it — so the same initialization code serves both render modes.
+     *
+     * @param checkboxEl - The created checkbox element.
+     */
+    onInit(checkboxEl: HTMLInputElement): void;
+}
+/**
+ * The members every command shares.
+ */
+export interface CommandBase {
+    /**
+     * Whether the control can be used right now. When it returns `false` the control is rendered
+     * **disabled rather than removed**, so the strip does not reflow under the pointer as modes change —
+     * which on a phone means a mis-tap.
+     *
+     * Re-read by {@link ModalCommands.refresh}. When omitted, the builder never touches the control's
+     * disabled state, leaving whatever {@link CheckboxCommand.onInit} / {@link DropDownCommand.onInit} set.
+     *
+     * @returns Whether the control can be used right now.
+     */
+    checkIsAvailable?(this: void): boolean;
+    /**
+     * The key that activates the command.
+     */
+    key: string;
+    /**
+     * The modifiers combined with {@link CommandBase.key}. When omitted, no modifiers are required.
+     */
+    modifiers?: Modifier[];
+    /**
+     * The human-readable description shown next to the control.
+     */
+    purpose: string;
+}
+/**
+ * A dropdown command shown in a modal's control strip and bound to a modifier+key shortcut that cycles
+ * through its options.
+ *
+ * Supported in {@link ModalCommandsRenderMode.Instructions} mode only.
+ */
+export interface DropDownCommand extends CommandBase {
+    /**
+     * Called when the dropdown value changes.
+     *
+     * @param value - The newly selected value.
+     */
+    onChange(value: string): void;
+    /**
+     * Called once with the created dropdown component, to initialize its options and state.
+     *
+     * @param dropdownComponent - The created dropdown component.
+     */
+    onInit(dropdownComponent: DropdownComponent): void;
+}
+/**
+ * A keyboard command shown in a modal's control strip and optionally bound to a modifier+key handler.
+ */
+export interface KeyboardCommand extends CommandBase {
+    /**
+     * Whether the command reads as ON. Supply it for a toggle whose state lives outside the strip; omit it
+     * for an action, which does something and is done. A {@link CheckboxCommand} needs no equivalent — its
+     * checkbox element is the state.
+     *
+     * Re-read by {@link ModalCommands.refresh}.
+     *
+     * @returns Whether the command reads as ON.
+     */
+    checkIsOn?(this: void): boolean;
+    /**
+     * The pointer route into the same handler the shortcut runs. Required for the command to render a
+     * button in {@link ModalCommandsRenderMode.Buttons} mode — on a phone there is no modifier key to
+     * press, so this is the only way in.
+     *
+     * @param $event - The click event, so a command that picks something has one to hand on.
+     */
+    onActivate?(this: void, $event: MouseEvent): void;
+    /**
+     * The handler invoked when the shortcut is pressed. When omitted, the command is a hint only and no
+     * scope handler is registered.
+     *
+     * @param $event - The keyboard event.
+     * @param context - The keymap context.
+     * @returns `false` to prevent Obsidian's default handling, or `void`/`true` otherwise.
+     */
+    onKey?($event: KeyboardEvent, context: KeymapContext): boolean;
+}
+/**
+ * Options for {@link ModalCommandBuilder.build}.
+ */
+export interface ModalCommandBuilderBuildOptions {
+    /**
+     * The way each control is rendered.
+     *
+     * @default {@link ModalCommandsRenderMode.Instructions}
+     */
+    readonly renderMode?: ModalCommandsRenderMode;
+    /**
+     * Whether to render the control strip (checkboxes, dropdowns, keyboard hints) and register the
+     * option-toggle keyboard shortcuts. When `false`, no control UI is shown and the option-toggle
+     * shortcuts are not registered; only the essential navigation key handlers remain active.
+     *
+     * @default `true`
+     */
+    readonly shouldShowInstructions?: boolean;
+}
+/**
+ * The handle returned by {@link ModalCommandBuilder.build}.
+ */
+export interface ModalCommands {
+    /**
+     * Brings every rendered control's disabled and pressed state up to date, by re-reading
+     * {@link CommandBase.checkIsAvailable} and {@link KeyboardCommand.checkIsOn}.
+     *
+     * The strip is built once and only re-stated afterwards, because rebuilding it would replace an element
+     * the pointer may be about to click.
+     */
+    refresh(): void;
+}
+/**
+ * A bare host for a control strip: the element to render into, plus the scope to register shortcuts with.
+ */
+export interface ModalCommandsHost {
+    /**
+     * The element the control strip is appended to.
+     */
+    readonly containerEl: HTMLElement;
+    /**
+     * The scope the shortcuts are registered with.
+     */
+    readonly scope: Scope;
+}
+/**
+ * Every target {@link ModalCommandBuilder.build} accepts.
+ */
+export type ModalCommandsTarget = Modal | ModalCommandsHost | SuggestModal<unknown>;
+/**
+ * Builds a modal's control strip from keyboard commands, interactive checkboxes, and dropdowns, then
+ * applies them to a modal via {@link ModalCommandBuilder.build}.
+ */
+export declare class ModalCommandBuilder {
+    private readonly entries;
+    /**
+     * Adds an interactive checkbox to the control strip, bound to a modifier+key shortcut that toggles it.
+     *
+     * @param command - The checkbox command to add.
+     * @returns The builder instance for chaining.
+     */
+    addCheckbox(command: CheckboxCommand): this;
+    /**
+     * Adds a dropdown to the control strip, bound to a modifier+key shortcut that cycles through its
+     * options.
+     *
+     * @param command - The dropdown command to add.
+     * @returns The builder instance for chaining.
+     */
+    addDropDown(command: DropDownCommand): this;
+    /**
+     * Adds a keyboard command to the control strip. When {@link KeyboardCommand.onKey} is provided, its
+     * handler is registered with the modal scope; otherwise the command is a hint only.
+     *
+     * @param command - The keyboard command to add.
+     * @returns The builder instance for chaining.
+     */
+    addKeyboardCommand(command: KeyboardCommand): this;
+    /**
+     * Applies the accumulated commands to a modal. Always registers the essential navigation/action key
+     * handlers; only renders the control strip and registers the option-toggle shortcuts when
+     * {@link ModalCommandBuilderBuildOptions.shouldShowInstructions} is `true`.
+     *
+     * @param target - The modal, or the bare element + scope, to apply the commands to.
+     * @param options - The build options.
+     * @returns A handle whose {@link ModalCommands.refresh} re-states every rendered control.
+     */
+    build(target: ModalCommandsTarget, options?: ModalCommandBuilderBuildOptions): ModalCommands;
+    private buildCommandText;
+    private getModifierString;
+    /**
+     * Resolves the element a self-created strip is appended to.
+     *
+     * A {@link Modal} carries both `modalEl` and a `containerEl` that is the OUTER `.modal-container`, so
+     * `modalEl` has to win — otherwise the strip lands outside the modal frame. Discriminated with `in`
+     * rather than a property read, because tests hand `build` a `strictProxy` mock whose `get` trap throws
+     * on unmocked members.
+     *
+     * @param target - The build target.
+     * @returns The element to append the strip to.
+     */
+    private getStripContainerEl;
+    private renderButtons;
+    private renderInstructions;
+    /**
+     * Renders through Obsidian's own instruction bar, the way every {@link SuggestModal} consumer has always
+     * had it.
+     *
+     * @param modal - The suggest modal.
+     * @param instructions - The instructions to render.
+     * @returns The purpose element of each rendered instruction.
+     */
+    private renderNativeInstructions;
+    /**
+     * Renders an instruction bar of the builder's own, for a host that has none.
+     *
+     * The markup mirrors what `setInstructions` produces, so Obsidian's own styling applies unchanged.
+     *
+     * @param containerEl - The element to append the bar to.
+     * @param instructions - The instructions to render.
+     * @returns The purpose element of each rendered instruction.
+     */
+    private renderOwnInstructions;
+}