@mnaoumov/create-obsidian-plugin 0.0.0-stage → 1.0.0

package/templates/default/src/plugin-settings-tab.ts_demo.ejs

@@ -0,0 +1,286 @@
+import { Notice } from 'obsidian';
+import { PluginSettingsTabBase } from 'obsidian-dev-utils/obsidian/plugin/plugin-settings-tab';
+import { SettingEx } from 'obsidian-dev-utils/obsidian/setting-ex';
+
+import type { PluginSettings } from './plugin-settings.ts';
+
+import { TypedItem } from './plugin-settings.ts';
+
+/**
+ * Built imperatively via `displayLegacy()` rather than declaratively via `getSettingDefinitionItems()`,
+ * because this tab exists to show off every `SettingEx` component there is. A real plugin should prefer
+ * the declarative form — see the `enhanced` preset.
+ */
+export class PluginSettingsTab extends PluginSettingsTabBase<PluginSettings> {
+  public override displayLegacy(): void {
+    this.containerEl.empty();
+
+    new SettingEx(this.containerEl)
+      .setName('Button setting name')
+      .setDesc('Button setting description.')
+      .addButton((button) => {
+        button.setButtonText('Button text')
+          .onClick(() => {
+            new Notice('Button clicked');
+          });
+      });
+
+    new SettingEx(this.containerEl)
+      .setName('Checkbox setting name')
+      .setDesc('Checkbox setting description.')
+      .addCheckbox((checkbox) => {
+        this.bind({ propertyName: 'checkboxSetting', valueComponent: checkbox });
+      });
+
+    new SettingEx(this.containerEl)
+      .setName('Code highlighter setting name')
+      .setDesc('Code highlighter setting description.')
+      .addCodeHighlighter((codeHighlighter) => {
+        codeHighlighter.setLanguage('javascript');
+        this.bind({ propertyName: 'codeHighlighterSetting', valueComponent: codeHighlighter });
+      });
+
+    new SettingEx(this.containerEl)
+      .setName('Color setting name')
+      .setDesc('Color setting description.')
+      .addColorPicker((color) => {
+        this.bind({ propertyName: 'colorSetting', valueComponent: color });
+      });
+
+    new SettingEx(this.containerEl)
+      .setName('Date setting name')
+      .setDesc('Date setting description.')
+      .addDate((date) => {
+        this.bind({ propertyName: 'dateSetting', valueComponent: date });
+      });
+
+    new SettingEx(this.containerEl)
+      .setName('Date time setting name')
+      .setDesc('Date time setting description.')
+      .addDateTime((dateTime) => {
+        this.bind({ propertyName: 'dateTimeSetting', valueComponent: dateTime });
+      });
+
+    new SettingEx(this.containerEl)
+      .setName('Dropdown setting name')
+      .setDesc('Dropdown setting description.')
+      .addDropdown((dropdown) => {
+        dropdown.addOptions({
+          Value1: 'Display 1',
+          Value2: 'Display 2',
+          Value3: 'Display 3'
+        });
+        this.bind({ propertyName: 'dropdownSetting', valueComponent: dropdown });
+      });
+
+    new SettingEx(this.containerEl)
+      .setName('Email setting name')
+      .setDesc('Email setting description.')
+      .addEmail((email) => {
+        this.bind({ propertyName: 'emailSetting', valueComponent: email });
+      });
+
+    new SettingEx(this.containerEl)
+      .setName('Extra button setting name')
+      .setDesc('Extra button setting description.')
+      .addExtraButton((extraButton) => {
+        extraButton
+          .onClick(() => {
+            new Notice('Extra button clicked');
+          });
+      });
+
+    new SettingEx(this.containerEl)
+      .setName('File setting name')
+      .setDesc('File setting description.')
+      .addFile((file) => {
+        file.onChange((value) => {
+          new Notice(`File selected: ${value?.name ?? '(None)'}`);
+        });
+      });
+
+    new SettingEx(this.containerEl)
+      .setName('Moment format setting name')
+      .setDesc('Moment format setting description.')
+      .addMomentFormat((momentFormat) => {
+        this.bind({ propertyName: 'momentFormatSetting', valueComponent: momentFormat });
+      });
+
+    new SettingEx(this.containerEl)
+      .setName('Month setting name')
+      .setDesc('Month setting description.')
+      .addMonth((month) => {
+        this.bind({ propertyName: 'monthSetting', valueComponent: month });
+      });
+
+    new SettingEx(this.containerEl)
+      .setName('Multiple dropdown setting name')
+      .setDesc('Multiple dropdown setting description.')
+      .addMultipleDropdown((multipleDropdown) => {
+        multipleDropdown.addOptions({
+          Value1: 'Display 1',
+          Value2: 'Display 2',
+          Value3: 'Display 3',
+          Value4: 'Display 4',
+          Value5: 'Display 5'
+        });
+
+        this.bind({ propertyName: 'multipleDropdownSetting', valueComponent: multipleDropdown });
+      });
+
+    new SettingEx(this.containerEl)
+      .setName('Multiple email setting name')
+      .setDesc('Multiple email setting description.')
+      .addMultipleEmail((multipleEmail) => {
+        this.bind({ propertyName: 'multipleEmailSetting', valueComponent: multipleEmail });
+      });
+
+    new SettingEx(this.containerEl)
+      .setName('Multiple file setting name')
+      .setDesc('Multiple file setting description.')
+      .addMultipleFile((multipleFile) => {
+        multipleFile.onChange((value) => {
+          const fileNames = value.map((file) => file.name);
+          new Notice(`Files selected: ${fileNames.join(', ')}`);
+        });
+      });
+
+    new SettingEx(this.containerEl)
+      .setName('Multiple text setting name')
+      .setDesc('Multiple text setting description.')
+      .addMultipleText((multipleText) => {
+        this.bind({ propertyName: 'multipleTextSetting', valueComponent: multipleText });
+      });
+
+    new SettingEx(this.containerEl)
+      .setName('Number setting name')
+      .setDesc('Number setting description.')
+      .addNumber((number) => {
+        this.bind({ propertyName: 'numberSetting', valueComponent: number });
+      });
+
+    new SettingEx(this.containerEl)
+      .setName('Progress bar setting name')
+      .setDesc('Progress bar setting description.')
+      .addProgressBar((progressBar) => {
+        progressBar.setValue(this.pluginSettingsComponent.settings.progressBarSetting);
+      });
+
+    new SettingEx(this.containerEl)
+      .setName('Search setting name')
+      .setDesc('Search setting description.')
+      .addSearch((search) => {
+        this.bind({ propertyName: 'searchSetting', valueComponent: search });
+      });
+
+    new SettingEx(this.containerEl)
+      .setName('Slider setting name')
+      .setDesc('Slider setting description.')
+      .addSlider((slider) => {
+        this.bind({ propertyName: 'sliderSetting', valueComponent: slider });
+      });
+
+    new SettingEx(this.containerEl)
+      .setName('Text setting name')
+      .setDesc('Text setting description.')
+      .addText((text) => {
+        this.bind({ propertyName: 'textSetting', valueComponent: text });
+      });
+
+    new SettingEx(this.containerEl)
+      .setName('Text area setting name')
+      .setDesc('Text area setting description.')
+      .addTextArea((textArea) => {
+        this.bind({ propertyName: 'textAreaSetting', valueComponent: textArea });
+      });
+
+    new SettingEx(this.containerEl)
+      .setName('Time setting name')
+      .setDesc('Time setting description.')
+      .addTime((time) => {
+        this.bind({ propertyName: 'timeSetting', valueComponent: time });
+      });
+
+    new SettingEx(this.containerEl)
+      .setName('Toggle setting name')
+      .setDesc('Toggle setting description.')
+      .addToggle((toggle) => {
+        this.bind({ propertyName: 'toggleSetting', valueComponent: toggle });
+      });
+
+    new SettingEx(this.containerEl)
+      .setName('Tri-state checkbox setting name')
+      .setDesc('Tri-state checkbox setting description.')
+      .addTriStateCheckbox((triStateCheckbox) => {
+        this.bind({ propertyName: 'triStateCheckboxSetting', valueComponent: triStateCheckbox });
+      });
+
+    new SettingEx(this.containerEl)
+      .setName('Typed dropdown setting name')
+      .setDesc('Typed dropdown setting description.')
+      .addTypedDropdown((typedDropdown) => {
+        const map = new Map<TypedItem, string>([
+          [TypedItem.Bar, 'Display Bar'],
+          [TypedItem.Baz, 'Display Baz'],
+          [TypedItem.Foo, 'Display Foo']
+        ]);
+        typedDropdown.addOptions(map);
+        this.bind({
+          onChanged(newValue, oldValue) {
+            console.warn('Typed Dropdown setting changed', { newValue, oldValue });
+          },
+          propertyName: 'typedDropdownSetting',
+          valueComponent: typedDropdown
+        });
+      });
+
+    new SettingEx(this.containerEl)
+      .setName('Typed multiple dropdown setting name')
+      .setDesc('Typed multiple dropdown setting description.')
+      .addTypedMultipleDropdown((typedMultipleDropdown) => {
+        const map = new Map<TypedItem, string>([
+          [TypedItem.Bar, 'Display Bar'],
+          [TypedItem.Baz, 'Display Baz'],
+          [TypedItem.Foo, 'Display Foo']
+        ]);
+        typedMultipleDropdown.addOptions(map);
+        this.bind({
+          onChanged(newValue, oldValue) {
+            console.warn('Typed Multiple Dropdown setting changed', { newValue, oldValue });
+          },
+          propertyName: 'typedMultipleDropdownSetting',
+          valueComponent: typedMultipleDropdown
+        });
+      });
+
+    new SettingEx(this.containerEl)
+      .setName('URL setting name')
+      .setDesc('URL setting description.')
+      .addUrl((url) => {
+        this.bind({ propertyName: 'urlSetting', valueComponent: url });
+      });
+
+    new SettingEx(this.containerEl)
+      .setName('Week setting name')
+      .setDesc('Week setting description.')
+      .addWeek((week) => {
+        this.bind({ propertyName: 'weekSetting', valueComponent: week });
+      });
+
+    new SettingEx(this.containerEl)
+      .setName('Advanced text setting name')
+      .setDesc('Advanced text setting description.')
+      .addText((text) => {
+        this.bind({
+          componentToPluginSettingsValueConverter: (uiValue: string) => uiValue.replace(' (converted)', ''),
+          onChanged: () => {
+            new Notice('Advanced text setting changed');
+          },
+          pluginSettingsToComponentValueConverter: (pluginSettingsValue: string) => `${pluginSettingsValue} (converted)`,
+          propertyName: 'textSetting',
+          valueComponent: text
+        })
+          .setPlaceholder('Enter a value');
+      });
+  }
+}

package/templates/default/src/plugin-settings-tab.ts_enhanced.ejs

@@ -0,0 +1,26 @@
+import type { SettingDefinitionItem } from 'obsidian';
+
+import { PluginSettingsTabBase } from 'obsidian-dev-utils/obsidian/plugin/plugin-settings-tab';
+
+import type { PluginSettings } from './plugin-settings.ts';
+
+/**
+ * The settings tab is declarative: return one definition per row from `getSettingDefinitionItems()` and
+ * Obsidian renders them. `bind` wires a component to a settings property in both directions, so there is
+ * no read/write plumbing to maintain.
+ */
+export class PluginSettingsTab extends PluginSettingsTabBase<PluginSettings> {
+  protected override getSettingDefinitionItems(): SettingDefinitionItem[] {
+    return [
+      this.settingEx({
+        desc: 'Text setting description.',
+        name: 'Text setting name',
+        render: (setting) => {
+          setting.addText((text) => {
+            this.bind({ propertyName: 'textSetting', valueComponent: text });
+          });
+        }
+      })
+    ];
+  }
+}

package/templates/default/src/plugin-settings.test.ts_demo.ejs

@@ -0,0 +1,14 @@
+<%- render('test-imports') -%>
+import { TypedItem } from './plugin-settings.ts';
+
+describe('TypedItem', () => {
+  it('deserializes a saved name back to the same instance', () => {
+    expect(TypedItem.deserialize(TypedItem.Bar.name)).toBe(TypedItem.Bar);
+  });
+
+  // A `data.json` edited by hand, or written by a version of the plugin that had another item, must not
+  // Load as a silently wrong value.
+  it('rejects a name it does not know', () => {
+    expect(() => TypedItem.deserialize('Unknown')).toThrow('Unknown item: Unknown');
+  });
+});

package/templates/default/src/plugin-settings.test.ts_demo@test-imports_vitest.ejs

@@ -0,0 +1,6 @@
+import {
+  describe,
+  expect,
+  it
+} from 'vitest';
+

package/templates/default/src/plugin-settings.ts_demo.ejs

@@ -0,0 +1,64 @@
+import type { IsoMonth } from 'obsidian-dev-utils/obsidian/setting-components/month-component';
+import type { IsoWeek } from 'obsidian-dev-utils/obsidian/setting-components/week-component';
+
+import { moment } from 'obsidian';
+
+export class TypedItem {
+  public static readonly Bar = new TypedItem('Bar');
+  public static readonly Baz = new TypedItem('Baz');
+  public static readonly Foo = new TypedItem('Foo');
+
+  public constructor(public readonly name: string) {}
+
+  public static deserialize(name: string): TypedItem {
+    const items = [this.Bar, this.Baz, this.Foo];
+    const item = items.find((candidate) => candidate.name === name);
+
+    if (item === undefined) {
+      throw new Error(`Unknown item: ${name}`);
+    }
+
+    return item;
+  }
+}
+
+/* eslint-disable no-magic-numbers -- Magic numbers are OK in settings defaults: the value IS the documentation. */
+export class PluginSettings {
+  public checkboxSetting = true;
+  public codeHighlighterSetting = `function foo() {
+  console.log('bar');
+}`;
+
+  public colorSetting = '#123456';
+  public dateSetting = new Date();
+  public dateTimeSetting = new Date();
+  public dropdownSetting = 'Value2';
+  public emailSetting = 'defaultEmail@example.com';
+  public momentFormatSetting = 'YYYY-MM-DD';
+  public monthSetting: IsoMonth = {
+    month: 2,
+    year: 2025
+  };
+
+  public multipleDropdownSetting: readonly string[] = ['Value2', 'Value5'];
+  public multipleEmailSetting: readonly string[] = ['defaultEmail@example.com', 'defaultEmail2@example.com'];
+  public multipleTextSetting: readonly string[] = ['defaultText1', 'defaultText2', 'defaultText3'];
+  public numberSetting = 123;
+  public progressBarSetting = 50;
+  public searchSetting = 'defaultSearch';
+  public sliderSetting = 50;
+  public textAreaSetting = 'defaultTextArea';
+  public textSetting = 'defaultText';
+  public timeSetting: moment.Duration = moment.duration({ hours: 12, minutes: 34 });
+  public toggleSetting = true;
+  public triStateCheckboxSetting: boolean | null = null;
+  public typedDropdownSetting: TypedItem = TypedItem.Foo;
+  public typedMultipleDropdownSetting: readonly TypedItem[] = [TypedItem.Bar, TypedItem.Baz];
+  public urlSetting = 'https://example.com';
+
+  public weekSetting: IsoWeek = {
+    weekNumber: 6,
+    year: 2025
+  };
+}
+/* eslint-enable no-magic-numbers -- Magic numbers are OK in settings defaults: the value IS the documentation. */

package/templates/default/src/plugin-settings.ts_enhanced.ejs

@@ -0,0 +1,3 @@
+export class PluginSettings {
+  public textSetting = 'defaultText';
+}

package/templates/default/src/plugin.test.ts_jest.ejs

@@ -0,0 +1,9 @@
+import { Plugin as ObsidianPlugin } from 'obsidian';
+
+import { Plugin } from './plugin.ts';
+
+describe('<%= pluginShortName %>', () => {
+  it('extends the Obsidian Plugin class', () => {
+    expect(Plugin.prototype).toBeInstanceOf(ObsidianPlugin);
+  });
+});

package/templates/default/src/plugin.test.ts_vitest.ejs

@@ -0,0 +1,14 @@
+import { Plugin as ObsidianPlugin } from 'obsidian';
+import {
+  describe,
+  expect,
+  it
+} from 'vitest';
+
+import { Plugin } from './plugin.ts';
+
+describe('<%= pluginShortName %>', () => {
+  it('extends the Obsidian Plugin class', () => {
+    expect(Plugin.prototype).toBeInstanceOf(ObsidianPlugin);
+  });
+});