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

package/templates/default/src/editor-suggests/sample-editor-suggest.ts.ejs

@@ -0,0 +1,42 @@
+import type {
+  Editor,
+  EditorPosition,
+  EditorSuggestContext,
+  EditorSuggestTriggerInfo,
+  TFile
+} from 'obsidian';
+
+import { EditorSuggest } from 'obsidian';
+
+export class SampleEditorSuggest extends EditorSuggest<string> {
+  private cursor: EditorPosition | null = null;
+  private editor: Editor | null = null;
+
+  public override getSuggestions(context: EditorSuggestContext): Promise<string[]> | string[] {
+    return [`${context.query} 1`, `${context.query} 2`, `${context.query} 3`];
+  }
+
+  public override onTrigger(cursor: EditorPosition, editor: Editor, file: null | TFile): EditorSuggestTriggerInfo | null {
+    this.cursor = cursor;
+    this.editor = editor;
+    const line = editor.getLine(cursor.line);
+    return line === 'Sample'
+      ? {
+        end: cursor,
+        query: `Query ${file?.name ?? ''}`,
+        start: cursor
+      }
+      : null;
+  }
+
+  public override renderSuggestion(value: string, el: HTMLElement): void {
+    el.createEl('strong', { text: value });
+  }
+
+  public override selectSuggestion(value: string, $event: KeyboardEvent | MouseEvent): void {
+    this.close();
+    if (this.editor && this.cursor) {
+      this.editor.replaceRange(`Transformed ${value} ${$event.type}`, this.cursor);
+    }
+  }
+}

package/templates/default/src/i18n/en/index.ts.ejs

@@ -0,0 +1,10 @@
+import type { BaseTranslation } from 'typesafe-i18n';
+
+<%# `satisfies` rather than an annotation: annotating widens the object to `BaseTranslation`, whose -%>
+<%# index signature erases the keys, and `TranslationFunctions<BaseTranslation>` is then indexed by -%>
+<%# `string` instead of by the messages this file actually declares. -%>
+const en = {
+  greeting: 'Hello from <%= pluginName %>!'
+} satisfies BaseTranslation;
+
+export default en;

package/templates/default/src/i18n/index.ts_i18next.ejs

@@ -0,0 +1,21 @@
+// The named exports are bound to the default instance, the stateful singleton the package documents.
+import {
+  init,
+  t as translate
+} from 'i18next';
+
+import en from './locales/en.json';
+
+export async function initI18n(): Promise<void> {
+  await init({
+    fallbackLng: 'en',
+    lng: 'en',
+    resources: {
+      en: { translation: en }
+    }
+  });
+}
+
+export function t(key: string): string {
+  return translate(key);
+}

package/templates/default/src/i18n/index.ts_typesafe-i18n.ejs

@@ -0,0 +1,14 @@
+import { i18nObject } from 'typesafe-i18n';
+
+import en from './en/index.ts';
+
+<%# `i18nObject(locale, translations)`, not `i18n(...)`. `i18n` takes `(translations, formatters)` -- both -%>
+<%# keyed BY LOCALE -- and returns a locale-keyed map, so the old `i18n<BaseTranslation>('en', { en })` -%>
+<%# passed a locale where a translation map belongs, and then destructured `t` off the result as though -%>
+<%# it were a locale name. That failed to compile (TS2339, TS2558) and, once a test finally loaded the -%>
+<%# module, handed `new PluralRules('t')` a garbage tag: `RangeError: Invalid language tag: t`. -%>
+const translate = i18nObject('en', en);
+
+export function t(key: keyof typeof en): string {
+  return translate[key]();
+}

package/templates/default/src/i18n/locales/en.json.ejs

@@ -0,0 +1,3 @@
+{
+  "greeting": <%- JSON.stringify(`Hello from ${pluginName}!`) %>
+}

package/templates/default/src/lit-elements/sample-lit-element.ts.ejs

@@ -0,0 +1,54 @@
+import {
+  css,
+  html,
+  LitElement
+} from 'lit';
+import {
+  customElement,
+  property
+} from 'lit/decorators.js';
+
+@customElement('sample-lit-element')
+export class SampleLitElement extends LitElement {
+  public static override styles = css`
+    :host {
+      display: block;
+      padding: 16px;
+    }
+    button {
+      cursor: pointer;
+    }
+  `;
+
+  @property({ type: Number })
+  public count = 0;
+
+  @property({ type: String })
+  public vaultName = '';
+
+  public override render(): unknown {
+    return html`
+      <h4>Sample Lit Element!</h4>
+      <div>
+        <span>My number is ${this.count}!</span>
+      </div>
+      <button type="button" @click=${this.increment}>Increment</button>
+      <div>Vault name: ${this.vaultName}</div>
+    `;
+  }
+
+  // An arrow property rather than a method: the template below hands `this.increment` to lit as a bare
+  // Reference, and a method detached from its object is what `@typescript-eslint/unbound-method`
+  // Forbids. Binding at the declaration is the fix lit's own docs reach for too.
+  private readonly increment = (): void => {
+    this.count++;
+  };
+}
+
+declare global {
+  // Lit's own pattern for a custom element: it is what lets `createEl('sample-lit-element')` type-check,
+  // And return a `SampleLitElement` whose properties can be set directly.
+  interface HTMLElementTagNameMap {
+    'sample-lit-element': SampleLitElement;
+  }
+}

package/templates/default/src/main.test.ts.ejs

@@ -0,0 +1,11 @@
+<%- render('test-imports') -%>
+import Plugin from './main.ts';
+import { Plugin as PluginClass } from './plugin.ts';
+
+describe('main', () => {
+  // Obsidian loads a plugin by instantiating the default export of `main.js`, so this re-export is the
+  // One line of wiring the whole plugin hangs off.
+  it('exports the plugin class as the default export Obsidian loads', () => {
+    expect(Plugin).toBe(PluginClass);
+  });
+});

package/templates/default/src/main.test.ts@test-imports_vitest.ejs

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

package/templates/default/src/main.ts.ejs

@@ -0,0 +1,4 @@
+<% const styleImports = render('import'); -%>
+<%- styleImports -%>
+<%- styleImports ? '\n' : '' -%>
+export { Plugin as default } from './plugin.ts';

package/templates/default/src/main.ts@import_css-modules.ejs

@@ -0,0 +1 @@
+import './styles/main.module.css'; // Do not delete this line if you want to have a styles.css file in your build output.

package/templates/default/src/main.ts@import_css.ejs

@@ -0,0 +1 @@
+import './styles/main.css'; // Do not delete this line if you want to have a styles.css file in your build output.

package/templates/default/src/main.ts@import_postcss.ejs

@@ -0,0 +1 @@
+import './styles/main.css'; // Do not delete this line if you want to have a styles.css file in your build output.

package/templates/default/src/main.ts@import_scss.ejs

@@ -0,0 +1 @@
+import './styles/main.scss'; // Do not delete this line if you want to have a styles.css file in your build output.

package/templates/default/src/main.ts@import_tailwind.ejs

@@ -0,0 +1 @@
+import './styles/tailwind.generated.css'; // Compiled from ./styles/main.css by `npm run build:styles`. Do not delete this line if you want to have a styles.css file in your build output.

package/templates/default/src/modals/sample-form-modal.ts.ejs

@@ -0,0 +1,35 @@
+import {
+  Modal,
+  Notice,
+  Setting
+} from 'obsidian';
+
+export class SampleFormModal extends Modal {
+  private name = '';
+
+  public override onOpen(): void {
+    this.contentEl.createEl('h2', { text: 'Sample form' });
+
+    new Setting(this.contentEl)
+      .setName('Name')
+      .setDesc('Enter your name')
+      .addText((text) => {
+        text
+          .setPlaceholder('Your name')
+          .onChange((value) => {
+            this.name = value;
+          });
+      });
+
+    new Setting(this.contentEl)
+      .addButton((button) => {
+        button
+          .setButtonText('Submit')
+          .setCta()
+          .onClick(() => {
+            new Notice(`Hello, ${this.name || 'world'}!`);
+            this.close();
+          });
+      });
+  }
+}

package/templates/default/src/modals/sample-suggest-modal.ts.ejs

@@ -0,0 +1,37 @@
+import type { FuzzyMatch } from 'obsidian';
+
+import {
+  FuzzySuggestModal,
+  Notice
+} from 'obsidian';
+
+interface SampleItem {
+  icon: string;
+  name: string;
+}
+
+const SAMPLE_ITEMS: readonly SampleItem[] = [
+  { icon: '📝', name: 'Note' },
+  { icon: '📁', name: 'Folder' },
+  { icon: '🔖', name: 'Bookmark' },
+  { icon: '📌', name: 'Pin' },
+  { icon: '🏷️', name: 'Tag' }
+];
+
+export class SampleSuggestModal extends FuzzySuggestModal<SampleItem> {
+  public override getItems(): SampleItem[] {
+    return [...SAMPLE_ITEMS];
+  }
+
+  public override getItemText(item: SampleItem): string {
+    return item.name;
+  }
+
+  public override onChooseItem(item: SampleItem, $event: KeyboardEvent | MouseEvent): void {
+    new Notice(`Selected: ${item.icon} ${item.name} (${$event.type})`);
+  }
+
+  public override renderSuggestion(match: FuzzyMatch<SampleItem>, el: HTMLElement): void {
+    el.createSpan({ text: `${match.item.icon} ${match.item.name}` });
+  }
+}

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

@@ -0,0 +1,49 @@
+import type { DataHandler } from 'obsidian-dev-utils/obsidian/data-handler';
+import type { PluginEventMap } from 'obsidian-dev-utils/obsidian/plugin/plugin-event-source';
+
+import { AsyncEvents } from 'obsidian-dev-utils/async-events';
+import { noopAsync } from 'obsidian-dev-utils/function';
+import { strictProxy } from 'obsidian-dev-utils/strict-proxy';
+<%- render('test-imports') -%>
+
+import { PluginSettingsComponent } from './plugin-settings-component.ts';
+import {
+  PluginSettings,
+  TypedItem
+} from './plugin-settings.ts';
+
+describe('PluginSettingsComponent', () => {
+  it('takes its defaults from the PluginSettings class', () => {
+    // `strictProxy` throws on any member the component touches, so this also proves that constructing
+    // The component reads nothing from `data.json` or the plugin's events.
+    const component = new PluginSettingsComponent({
+      dataHandler: strictProxy<DataHandler>({}),
+      pluginEventSource: strictProxy<AsyncEvents<PluginEventMap>>({})
+    });
+    expect(component.defaultSettings).toBeInstanceOf(PluginSettings);
+  });
+
+  // `data.json` is JSON, so a `TypedItem` is stored as its name and has to come back as the same instance
+  // On load -- otherwise the dropdown shows nothing selected after a restart. This drives the component
+  // Through the lifecycle Obsidian does: `load()` reads `data.json`, and writes it back normalized.
+  it('loads a typed setting saved by name as the same item, and saves it back by name', async () => {
+    const savedRecords: unknown[] = [];
+    const component = new PluginSettingsComponent({
+      dataHandler: {
+        loadData(): Promise<unknown> {
+          return Promise.resolve({ typedDropdownSetting: TypedItem.Baz.name });
+        },
+        saveData(data: unknown): Promise<void> {
+          savedRecords.push(data);
+          return noopAsync();
+        }
+      },
+      pluginEventSource: new AsyncEvents<PluginEventMap>()
+    });
+
+    await component.loadWithPromises();
+
+    expect(component.settings.typedDropdownSetting).toBe(TypedItem.Baz);
+    expect(savedRecords.at(-1)).toMatchObject({ typedDropdownSetting: TypedItem.Baz.name });
+  });
+});

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

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

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

@@ -0,0 +1,41 @@
+import type { DataHandler } from 'obsidian-dev-utils/obsidian/data-handler';
+import type { PluginEventMap } from 'obsidian-dev-utils/obsidian/plugin/plugin-event-source';
+
+import { AsyncEvents } from 'obsidian-dev-utils/async-events';
+import { noopAsync } from 'obsidian-dev-utils/function';
+<%- render('test-imports') -%>
+
+import { PluginSettingsComponent } from './plugin-settings-component.ts';
+import { PluginSettings } from './plugin-settings.ts';
+
+describe('PluginSettingsComponent', () => {
+  it('takes its defaults from the PluginSettings class', async () => {
+    const component = createComponent(undefined);
+    await component.loadWithPromises();
+    expect(component.settings).toBeInstanceOf(PluginSettings);
+  });
+
+  // This drives the component through the lifecycle Obsidian does: `load()` reads `data.json`, and a
+  // Value the user saved there has to win over the class default.
+  it('loads a saved setting from data.json over its default', async () => {
+    const component = createComponent({ textSetting: 'Saved text' });
+    await component.loadWithPromises();
+    expect(component.settings.textSetting).toBe('Saved text');
+  });
+});
+
+function createComponent(data: unknown): PluginSettingsComponent {
+  const dataHandler: DataHandler = {
+    loadData(): Promise<unknown> {
+      return Promise.resolve(data);
+    },
+    saveData(): Promise<void> {
+      return noopAsync();
+    }
+  };
+
+  return new PluginSettingsComponent({
+    dataHandler,
+    pluginEventSource: new AsyncEvents<PluginEventMap>()
+  });
+}

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

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

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

@@ -0,0 +1,87 @@
+import type {
+  PluginSettingsComponentBaseOnSaveSettingsParams,
+  ReadonlyPluginSettingsState
+} from 'obsidian-dev-utils/obsidian/components/plugin-settings-component';
+import type { DataHandler } from 'obsidian-dev-utils/obsidian/data-handler';
+import type { PluginEventSource } from 'obsidian-dev-utils/obsidian/plugin/plugin-event-source';
+import type { MaybeReturn } from 'obsidian-dev-utils/type';
+import type { GenericObject } from 'obsidian-dev-utils/type-guards';
+
+import { Notice } from 'obsidian';
+import { PluginSettingsComponentBase } from 'obsidian-dev-utils/obsidian/components/plugin-settings-component';
+
+import {
+  PluginSettings,
+  TypedItem
+} from './plugin-settings.ts';
+
+interface PluginSettingsComponentConstructorParams {
+  readonly dataHandler: DataHandler;
+  readonly pluginEventSource: PluginEventSource;
+}
+
+interface SerializedSettings {
+  typedDropdownSetting: string;
+  typedMultipleDropdownSetting: string[];
+}
+
+export class PluginSettingsComponent extends PluginSettingsComponentBase<PluginSettings> {
+  public constructor(params: PluginSettingsComponentConstructorParams) {
+    super({
+      ...params,
+      pluginSettingsClass: PluginSettings
+    });
+  }
+
+  protected override async onLoadRecord(record: GenericObject): Promise<void> {
+    await super.onLoadRecord(record);
+    const serializedSettings = record as Partial<SerializedSettings>;
+    const pluginSettings = record as Partial<PluginSettings>;
+
+    if (serializedSettings.typedDropdownSetting) {
+      pluginSettings.typedDropdownSetting = TypedItem.deserialize(serializedSettings.typedDropdownSetting);
+    }
+
+    if (serializedSettings.typedMultipleDropdownSetting) {
+      pluginSettings.typedMultipleDropdownSetting = serializedSettings.typedMultipleDropdownSetting.map((name) => TypedItem.deserialize(name));
+    }
+  }
+
+  protected override async onLoadSettings(loadedState: ReadonlyPluginSettingsState<PluginSettings>, isInitialLoad: boolean): Promise<void> {
+    await super.onLoadSettings(loadedState, isInitialLoad);
+    if (loadedState.effectiveValues.textSetting === 'bar') {
+      new Notice('Sample text setting is bar');
+    }
+  }
+
+  // eslint-disable-next-line obsidian-dev-utils/params-options-name-match -- Override must keep the base param type.
+  protected override async onSaveSettings(params: PluginSettingsComponentBaseOnSaveSettingsParams<PluginSettings>): Promise<void> {
+    await super.onSaveSettings(params);
+    if (params.newState.effectiveValues.textSetting === 'baz' && params.oldState.effectiveValues.textSetting === 'bar') {
+      new Notice('Sample text setting is changed from bar to baz');
+    }
+  }
+
+  protected override async onSavingRecord(record: GenericObject): Promise<void> {
+    await super.onSavingRecord(record);
+    const serializedSettings = record as Partial<SerializedSettings>;
+    const pluginSettings = record as Partial<PluginSettings>;
+
+    if (pluginSettings.typedDropdownSetting) {
+      serializedSettings.typedDropdownSetting = pluginSettings.typedDropdownSetting.name;
+    }
+
+    if (pluginSettings.typedMultipleDropdownSetting) {
+      serializedSettings.typedMultipleDropdownSetting = pluginSettings.typedMultipleDropdownSetting.map((item) => item.name);
+    }
+  }
+
+  protected override registerValidators(): void {
+    super.registerValidators();
+    this.registerValidator('textSetting', (value): MaybeReturn<string> => {
+      if (value === 'foo') {
+        return 'Foo is not allowed';
+      }
+    });
+  }
+}

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

@@ -0,0 +1,27 @@
+import type { DataHandler } from 'obsidian-dev-utils/obsidian/data-handler';
+import type { PluginEventSource } from 'obsidian-dev-utils/obsidian/plugin/plugin-event-source';
+
+import { PluginSettingsComponentBase } from 'obsidian-dev-utils/obsidian/components/plugin-settings-component';
+
+import { PluginSettings } from './plugin-settings.ts';
+
+interface PluginSettingsComponentConstructorParams {
+  readonly dataHandler: DataHandler;
+  readonly pluginEventSource: PluginEventSource;
+}
+
+/**
+ * Owns the plugin's settings: loading them from `data.json`, saving them back, and telling the rest of
+ * the plugin when they change.
+ *
+ * Override `onLoadRecord` here to migrate settings written by an older version of the plugin, and
+ * `onLoadSettings` / `onSaveSettings` to react to a value changing.
+ */
+export class PluginSettingsComponent extends PluginSettingsComponentBase<PluginSettings> {
+  public constructor(params: PluginSettingsComponentConstructorParams) {
+    super({
+      ...params,
+      pluginSettingsClass: PluginSettings
+    });
+  }
+}