obsidian-dev-utils 96.5.4 → 96.6.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## 96.6.0
+
+- feat(modals): let the command builder drive any modal, and prompt() take one
+
 ## 96.5.4
 
 - fix(templates): call parseVersionArguments, and type-check templates so a rename cannot ship broken

package/dist/integration-test-plugin/main.js

@@ -7403,6 +7403,7 @@ var init_css_class = __esm({
       CssClass3["DateTimeComponent"] = "datetime-component";
       CssClass3["EmailComponent"] = "email-component";
       CssClass3["FileComponent"] = "file-component";
+      CssClass3["IsActive"] = "is-active";
       CssClass3["IsPlaceholder"] = "is-placeholder";
       CssClass3["LibraryName"] = "obsidian-dev-utils";
       CssClass3["MarkdownRendered"] = "markdown-rendered";
@@ -7411,6 +7412,9 @@ var init_css_class = __esm({
       CssClass3["MinimizedModalBar"] = "minimized-modal-bar";
       CssClass3["MinimizedModalBarAttention"] = "minimized-modal-bar-attention";
       CssClass3["MinimizedModalBarTitle"] = "minimized-modal-bar-title";
+      CssClass3["ModalCommand"] = "modal-command";
+      CssClass3["ModalCommandHotkey"] = "modal-command-hotkey";
+      CssClass3["ModalCommands"] = "modal-commands";
       CssClass3["ModalHeaderButton"] = "modal-header-button";
       CssClass3["MonthComponent"] = "month-component";
       CssClass3["MultipleDropdownComponent"] = "multiple-dropdown-component";
@@ -7428,6 +7432,8 @@ var init_css_class = __esm({
       CssClass3["PluginSettingsTab"] = "plugin-settings-tab";
       CssClass3["PluginSuggestionBanner"] = "plugin-suggestion-banner";
       CssClass3["Popover"] = "popover";
+      CssClass3["PromptInstruction"] = "prompt-instruction";
+      CssClass3["PromptInstructions"] = "prompt-instructions";
       CssClass3["PromptModal"] = "prompt-modal";
       CssClass3["RestoreButton"] = "restore-button";
       CssClass3["SelectItemModal"] = "select-item-modal";
@@ -12704,6 +12710,8 @@ __export(merged_exports, {
   MinimizableModal: () => MinimizableModal,
   MissingPathTreatment: () => MissingPathTreatment,
   ModalBase: () => ModalBase,
+  ModalCommandBuilder: () => ModalCommandBuilder,
+  ModalCommandsRenderMode: () => ModalCommandsRenderMode,
   MonkeyAroundComponent: () => MonkeyAroundComponent,
   MonthComponent: () => MonthComponent,
   MultipleDisposeBehavior: () => MultipleDisposeBehavior,
@@ -36152,6 +36160,319 @@ function suppressWhilePeekLocked($event) {
   blockEvent($event);
 }
 
+// src/obsidian/modals/modal-command-builder.ts
+var modal_command_builder_exports = {};
+__export(modal_command_builder_exports, {
+  ModalCommandBuilder: () => ModalCommandBuilder,
+  ModalCommandsRenderMode: () => ModalCommandsRenderMode
+});
+var import_obsidian134 = require("obsidian");
+init_css_class();
+init_plugin_context();
+var KEYS_MAP = /* @__PURE__ */ new Map([
+  ["Enter", "\u21B5"],
+  ["UpDown", "\u2191\u2193"]
+]);
+var ModalCommandsRenderMode = /* @__PURE__ */ ((ModalCommandsRenderMode2) => {
+  ModalCommandsRenderMode2["Buttons"] = "buttons";
+  ModalCommandsRenderMode2["Instructions"] = "instructions";
+  return ModalCommandsRenderMode2;
+})(ModalCommandsRenderMode || {});
+var NOOP_MODAL_COMMANDS = {
+  refresh: () => {
+  }
+};
+var ModalCommandBuilder = class {
+  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) {
+    this.entries.push({
+      checkIsAvailable: command.checkIsAvailable ?? null,
+      commandText: this.buildCommandText(command),
+      initButton: (buttonEl, scope) => {
+        const checkboxEl = createEl("input", { type: "checkbox" });
+        initCheckbox(checkboxEl, scope);
+        buttonEl.addEventListener("click", () => {
+          toggleCheckbox(checkboxEl);
+        });
+        return {
+          checkIsOn: () => checkboxEl.checked,
+          setDisabled: (isDisabled) => {
+            checkboxEl.disabled = isDisabled;
+            buttonEl.disabled = isDisabled;
+          }
+        };
+      },
+      initInstruction: (purposeEl, scope) => initCheckbox(purposeEl.createEl("input", { type: "checkbox" }), scope),
+      isDropDown: false,
+      purpose: command.purpose,
+      registerScope: null
+    });
+    return this;
+    function initCheckbox(checkboxEl, scope) {
+      command.onInit(checkboxEl);
+      checkboxEl.addEventListener("change", () => {
+        command.onChange(checkboxEl.checked);
+      });
+      scope.register(command.modifiers ?? [], command.key, () => {
+        toggleCheckbox(checkboxEl);
+      });
+      return {
+        setDisabled: (isDisabled) => {
+          checkboxEl.disabled = isDisabled;
+        }
+      };
+    }
+  }
+  /**
+   * 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) {
+    this.entries.push({
+      checkIsAvailable: command.checkIsAvailable ?? null,
+      commandText: this.buildCommandText(command),
+      initButton: null,
+      initInstruction: (purposeEl, scope) => {
+        purposeEl.appendText(" ");
+        const dropdownComponent = new import_obsidian134.DropdownComponent(purposeEl);
+        command.onInit(dropdownComponent);
+        dropdownComponent.onChange((value) => {
+          command.onChange(value);
+        });
+        scope.register(command.modifiers ?? [], command.key, () => {
+          if (dropdownComponent.disabled) {
+            return;
+          }
+          const selectEl = dropdownComponent.selectEl;
+          selectEl.selectedIndex = (selectEl.selectedIndex + 1) % selectEl.options.length;
+          selectEl.trigger("change");
+        });
+        return {
+          setDisabled: (isDisabled) => {
+            dropdownComponent.setDisabled(isDisabled);
+          }
+        };
+      },
+      isDropDown: true,
+      purpose: command.purpose,
+      registerScope: null
+    });
+    return 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) {
+    const checkIsOn = command.checkIsOn ?? (() => false);
+    const onActivate = command.onActivate ?? null;
+    const onKey = command.onKey?.bind(command) ?? null;
+    this.entries.push({
+      checkIsAvailable: command.checkIsAvailable ?? null,
+      commandText: this.buildCommandText(command),
+      initButton: onActivate ? (buttonEl) => {
+        buttonEl.addEventListener("click", ($event) => {
+          onActivate($event);
+        });
+        return {
+          checkIsOn,
+          setDisabled: (isDisabled) => {
+            buttonEl.disabled = isDisabled;
+          }
+        };
+      } : null,
+      initInstruction: null,
+      isDropDown: false,
+      purpose: command.purpose,
+      registerScope: onKey ? (scope) => {
+        scope.register(command.modifiers ?? [], command.key, onKey);
+      } : null
+    });
+    return 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, options = {}) {
+    const {
+      renderMode = "instructions" /* Instructions */,
+      shouldShowInstructions = true
+    } = options;
+    const scope = target.scope;
+    for (const entry of this.entries) {
+      entry.registerScope?.(scope);
+    }
+    if (!shouldShowInstructions) {
+      return NOOP_MODAL_COMMANDS;
+    }
+    const refreshers = renderMode === "buttons" /* Buttons */ ? this.renderButtons(target, scope) : this.renderInstructions(target, scope);
+    const modalCommands = {
+      refresh: () => {
+        for (const refreshControl of refreshers) {
+          refreshControl();
+        }
+      }
+    };
+    modalCommands.refresh();
+    return modalCommands;
+  }
+  buildCommandText(command) {
+    let commandText = KEYS_MAP.get(command.key) ?? command.key;
+    for (const modifier of command.modifiers ?? []) {
+      commandText = `${this.getModifierString(modifier)} ${commandText}`;
+    }
+    return commandText;
+  }
+  getModifierString(modifier) {
+    switch (modifier) {
+      case "Alt": {
+        return "alt";
+      }
+      case "Ctrl": {
+        return "ctrl";
+      }
+      case "Meta": {
+        return import_obsidian134.Platform.isMacOS ? "cmd" : "win";
+      }
+      case "Mod": {
+        return import_obsidian134.Platform.isMacOS ? "cmd" : "ctrl";
+      }
+      case "Shift": {
+        return "shift";
+      }
+      default: {
+        return modifier;
+      }
+    }
+  }
+  /**
+   * 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.
+   */
+  getStripContainerEl(target) {
+    return "modalEl" in target ? target.modalEl : target.containerEl;
+  }
+  renderButtons(target, scope) {
+    const stripEl = this.getStripContainerEl(target).createDiv();
+    addPluginCssClasses(stripEl, "modal-commands" /* ModalCommands */);
+    const refreshers = [];
+    for (const entry of this.entries) {
+      if (entry.isDropDown) {
+        throw new Error(`Cannot render dropdown command "${entry.purpose}" as a button: a control that cycles has no button form.`);
+      }
+      if (!entry.initButton) {
+        continue;
+      }
+      const buttonEl = stripEl.createEl("button", { type: "button" });
+      addPluginCssClasses(buttonEl, "modal-command" /* ModalCommand */);
+      buttonEl.createSpan({ text: entry.purpose });
+      if (!import_obsidian134.Platform.isMobile) {
+        const hotkeyEl = buttonEl.createSpan({ text: entry.commandText });
+        addPluginCssClasses(hotkeyEl, "modal-command-hotkey" /* ModalCommandHotkey */);
+      }
+      buttonEl.addEventListener("mousedown", ($event) => {
+        $event.preventDefault();
+      });
+      const buttonControl = entry.initButton(buttonEl, scope);
+      const checkIsAvailable = entry.checkIsAvailable;
+      refreshers.push(() => {
+        if (checkIsAvailable) {
+          buttonControl.setDisabled(!checkIsAvailable());
+        }
+        const isOn = buttonControl.checkIsOn();
+        buttonEl.toggleClass("is-active" /* IsActive */, isOn);
+        buttonEl.setAttribute("aria-pressed", String(isOn));
+      });
+    }
+    return refreshers;
+  }
+  renderInstructions(target, scope) {
+    const instructions = this.entries.map((entry) => ({
+      command: entry.commandText,
+      entry,
+      purpose: entry.purpose
+    }));
+    const purposeEls = "setInstructions" in target ? this.renderNativeInstructions(target, instructions) : this.renderOwnInstructions(this.getStripContainerEl(target), instructions);
+    const refreshers = [];
+    for (const [index2, instruction] of instructions.entries()) {
+      const purposeEl = purposeEls[index2];
+      if (!purposeEl) {
+        continue;
+      }
+      const instructionControl = instruction.entry.initInstruction?.(purposeEl, scope);
+      const checkIsAvailable = instruction.entry.checkIsAvailable;
+      if (instructionControl && checkIsAvailable) {
+        refreshers.push(() => {
+          instructionControl.setDisabled(!checkIsAvailable());
+        });
+      }
+    }
+    return refreshers;
+  }
+  /**
+   * 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.
+   */
+  renderNativeInstructions(modal, instructions) {
+    modal.setInstructions(instructions);
+    return [...modal.instructionsEl.findAll(".prompt-instruction > span:nth-child(2)")];
+  }
+  /**
+   * 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.
+   */
+  renderOwnInstructions(containerEl, instructions) {
+    const instructionsEl = containerEl.createDiv("prompt-instructions" /* PromptInstructions */);
+    addPluginCssClasses(instructionsEl, "modal-commands" /* ModalCommands */);
+    return instructions.map((instruction) => {
+      const instructionEl = instructionsEl.createDiv("prompt-instruction" /* PromptInstruction */);
+      instructionEl.createSpan({ text: instruction.command });
+      return instructionEl.createSpan({ text: instruction.purpose });
+    });
+  }
+};
+function toggleCheckbox(checkboxEl) {
+  if (checkboxEl.disabled) {
+    return;
+  }
+  checkboxEl.checked = !checkboxEl.checked;
+  checkboxEl.trigger("change");
+}
+
 // src/__merged.ts
 init_modal();
 
@@ -36160,14 +36481,17 @@ var prompt_exports = {};
 __export(prompt_exports, {
   prompt: () => prompt
 });
-var import_obsidian134 = require("obsidian");
+var import_obsidian135 = require("obsidian");
 init_async();
 init_function();
+init_object_utils();
 init_css_class();
 init_i18n();
 init_modal();
 var PromptModal = class extends ModalBase {
   cancelButtonText;
+  commandBuilder;
+  commandsRenderMode;
   isOkClicked = false;
   isTouched = false;
   okButtonText;
@@ -36179,6 +36503,8 @@ var PromptModal = class extends ModalBase {
     super(params);
     this.addCssClasses("prompt-modal" /* PromptModal */);
     this.cancelButtonText = params.cancelButtonText ?? t2(($) => $.obsidianDevUtils.buttons.cancel);
+    this.commandBuilder = params.commandBuilder ?? null;
+    this.commandsRenderMode = params.commandsRenderMode;
     this.okButtonText = params.okButtonText ?? t2(($) => $.obsidianDevUtils.buttons.ok);
     this.placeholder = params.placeholder ?? "";
     this.title = params.title ?? "";
@@ -36190,7 +36516,7 @@ var PromptModal = class extends ModalBase {
   }
   onOpen() {
     this.titleEl.setText(this.title);
-    const textComponent = new import_obsidian134.TextComponent(this.contentEl);
+    const textComponent = new import_obsidian135.TextComponent(this.contentEl);
     const inputEl = textComponent.inputEl;
     inputEl.setAttribute("spellcheck", String(isSpellcheckEnabled(this.app)));
     const validate = async (shouldReport) => {
@@ -36225,17 +36551,18 @@ var PromptModal = class extends ModalBase {
     inputEl.addEventListener("input", convertAsyncToSync(handleInput));
     inputEl.addEventListener("focus", convertAsyncToSync(handleFocus));
     invokeAsyncSafely(() => validate(false));
-    const okButton = new import_obsidian134.ButtonComponent(this.contentEl);
+    const okButton = new import_obsidian135.ButtonComponent(this.contentEl);
     okButton.setButtonText(this.okButtonText);
     okButton.setCta();
     okButton.onClick((event) => {
       this.handleOk(event, textComponent);
     });
     okButton.setClass("ok-button" /* OkButton */);
-    const cancelButton = new import_obsidian134.ButtonComponent(this.contentEl);
+    const cancelButton = new import_obsidian135.ButtonComponent(this.contentEl);
     cancelButton.setButtonText(this.cancelButtonText);
     cancelButton.onClick(this.close.bind(this));
     cancelButton.setClass("cancel-button" /* CancelButton */);
+    this.commandBuilder?.build(this, normalizeOptionalProperties({ renderMode: this.commandsRenderMode }));
   }
   handleOk(event, textComponent) {
     event.preventDefault();
@@ -36266,11 +36593,11 @@ var select_item_exports = {};
 __export(select_item_exports, {
   selectItem: () => selectItem
 });
-var import_obsidian135 = require("obsidian");
+var import_obsidian136 = require("obsidian");
 init_css_class();
 init_plugin_context();
 init_modal();
-var ItemSelectModal = class extends import_obsidian135.FuzzySuggestModal {
+var ItemSelectModal = class extends import_obsidian136.FuzzySuggestModal {
   isSelected = false;
   items;
   itemTextFunction;
@@ -36322,142 +36649,7 @@ var suggest_modal_command_builder_exports = {};
 __export(suggest_modal_command_builder_exports, {
   SuggestModalCommandBuilder: () => SuggestModalCommandBuilder
 });
-var import_obsidian136 = require("obsidian");
-var KEYS_MAP = /* @__PURE__ */ new Map([
-  ["Enter", "\u21B5"],
-  ["UpDown", "\u2191\u2193"]
-]);
-var SuggestModalCommandBuilder = class {
-  instructions = [];
-  /**
-   * Adds an interactive checkbox to the instruction bar, bound to a modifier+key shortcut that toggles
-   * it.
-   *
-   * @param command - The checkbox command to add.
-   * @returns The builder instance for chaining.
-   */
-  addCheckbox(command) {
-    this.instructions.push({
-      command: this.buildCommand(command),
-      init: (purposeEl, scope) => {
-        const checkboxEl = purposeEl.createEl("input", { type: "checkbox" });
-        command.onInit(checkboxEl);
-        checkboxEl.addEventListener("change", () => {
-          command.onChange(checkboxEl.checked);
-        });
-        scope.register(command.modifiers ?? [], command.key, () => {
-          if (checkboxEl.disabled) {
-            return;
-          }
-          checkboxEl.checked = !checkboxEl.checked;
-          checkboxEl.trigger("change");
-        });
-      },
-      purpose: command.purpose
-    });
-    return this;
-  }
-  /**
-   * Adds a dropdown to the instruction bar, 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) {
-    this.instructions.push({
-      command: this.buildCommand(command),
-      init: (purposeEl, scope) => {
-        purposeEl.appendText(" ");
-        const dropdownComponent = new import_obsidian136.DropdownComponent(purposeEl);
-        command.onInit(dropdownComponent);
-        dropdownComponent.onChange((value) => {
-          command.onChange(value);
-        });
-        scope.register(command.modifiers ?? [], command.key, () => {
-          if (dropdownComponent.disabled) {
-            return;
-          }
-          const selectEl = dropdownComponent.selectEl;
-          selectEl.selectedIndex = (selectEl.selectedIndex + 1) % selectEl.options.length;
-          selectEl.trigger("change");
-        });
-      },
-      purpose: command.purpose
-    });
-    return this;
-  }
-  /**
-   * Adds a keyboard command to the instruction bar. 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) {
-    this.instructions.push({
-      command: this.buildCommand(command),
-      purpose: command.purpose,
-      registerScope: (scope) => {
-        if (command.onKey) {
-          scope.register(command.modifiers ?? [], command.key, command.onKey.bind(command));
-        }
-      }
-    });
-    return this;
-  }
-  /**
-   * Applies the accumulated commands to a modal. Always registers the essential navigation/action key
-   * handlers; only renders the instruction UI and registers the option-toggle shortcuts when
-   * {@link SuggestModalCommandBuilderBuildOptions.shouldShowInstructions} is `true`.
-   *
-   * @param modal - The modal to apply the commands to.
-   * @param options - The build options.
-   */
-  build(modal, options = {}) {
-    const { shouldShowInstructions = true } = options;
-    for (const instruction of this.instructions) {
-      instruction.registerScope?.(modal.scope);
-    }
-    if (!shouldShowInstructions) {
-      return;
-    }
-    modal.setInstructions(this.instructions);
-    const purposeEls = [...modal.instructionsEl.findAll(".prompt-instruction > span:nth-child(2)")];
-    for (const [index2, purposeEl] of purposeEls.entries()) {
-      this.instructions[index2]?.init?.(purposeEl, modal.scope);
-    }
-  }
-  buildCommand(entry) {
-    let command = KEYS_MAP.get(entry.key) ?? entry.key;
-    for (const modifier of entry.modifiers ?? []) {
-      command = `${this.getModifierString(modifier)} ${command}`;
-    }
-    return command;
-  }
-  getModifierString(modifier) {
-    switch (modifier) {
-      case "Alt": {
-        return "alt";
-      }
-      case "Ctrl": {
-        return "ctrl";
-      }
-      case "Meta": {
-        return import_obsidian136.Platform.isMacOS ? "cmd" : "win";
-      }
-      case "Mod": {
-        return import_obsidian136.Platform.isMacOS ? "cmd" : "ctrl";
-      }
-      case "Shift": {
-        return "shift";
-      }
-      default: {
-        return modifier;
-      }
-    }
-  }
-};
+var SuggestModalCommandBuilder = ModalCommandBuilder;
 
 // src/obsidian/note-priority.ts
 var note_priority_exports = {};
@@ -41207,6 +41399,7 @@ __export(modals_exports, {
   confirm: () => confirm_exports,
   "minimizable-modal": () => minimizable_modal_exports,
   modal: () => modal_exports,
+  "modal-command-builder": () => modal_command_builder_exports,
   prompt: () => prompt_exports,
   "select-item": () => select_item_exports,
   "select-option": () => select_option_exports,