@mnaoumov/create-obsidian-plugin 1.0.2 → 1.2.0

package/templates/default/src/{plugin-settings-tab.ts_demo.ejs → (settings)/plugin-settings-tab.ts_demo.ejs}

@@ -1,6 +1,6 @@
+import { PluginSettingsTabBase } from '@mnaoumov/obsidian-lib/plugin/plugin-settings-tab';
+import { SettingEx } from '@mnaoumov/obsidian-lib/setting-ex';
 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';
 
@@ -9,7 +9,7 @@ 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.
+ * the declarative form — see the `all-in-one` preset.
  */
 export class PluginSettingsTab extends PluginSettingsTabBase<PluginSettings> {
   public override displayLegacy(): void {
@@ -155,8 +155,8 @@ export class PluginSettingsTab extends PluginSettingsTabBase<PluginSettings> {
     new SettingEx(this.containerEl)
       .setName('Number setting name')
       .setDesc('Number setting description.')
-      .addNumber((number) => {
-        this.bind({ propertyName: 'numberSetting', valueComponent: number });
+      .addNumber((numberComponent) => {
+        this.bind({ propertyName: 'numberSetting', valueComponent: numberComponent });
       });
 
     new SettingEx(this.containerEl)

package/templates/default/src/{plugin-settings.ts_demo.ejs → (settings)/plugin-settings.ts_demo.ejs}

@@ -1,5 +1,5 @@
-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 type { IsoMonth } from '@mnaoumov/obsidian-lib/setting-components/month-component';
+import type { IsoWeek } from '@mnaoumov/obsidian-lib/setting-components/week-component';
 
 import { moment } from 'obsidian';
 

package/templates/default/src/demo-vault-buttons.demo-vault.integration.test.ts.ejs

@@ -1,11 +1,11 @@
-import { registerDemoVaultButtonSuite } from 'obsidian-dev-utils/script-utils/demo-vault-buttons';
+import { registerDemoVaultButtonSuite } from '@mnaoumov/obsidian-dev-toolkit/demo-vault-buttons';
 
 // Clicks every `code-button` in `demo-vault/` against a real Obsidian. A button fails at CLICK time -- a
 // Wrong `require('/demoSetup.ts')` path, or an API that changed shape under it -- so no other gate can
 // Catch it: `lint:md` reads the markdown and the coverage suite checks the authoring conventions, and
 // Neither executes anything.
 //
-// It needs the CodeScript Toolkit binary seeded into `demo-vault/.obsidian/plugins/`, which happens the
+// It needs the `CodeScript Toolkit` binary seeded into `demo-vault/.obsidian/plugins/`, which happens the
 // First time you open `demo-vault/` in Obsidian. See CONTRIBUTING.md.
 //
 // Isolation: `npx vitest run --project integration-tests:demo-vault`.

package/templates/default/src/demo-vault.no-app.integration.test.ts.ejs

@@ -1,11 +1,11 @@
+import { registerDemoVaultCoverageSuite } from '@mnaoumov/obsidian-dev-toolkit/demo-vault-coverage';
+import { getRootFolder } from '@mnaoumov/typescript-dev-toolkit/root';
 import process from 'node:process';
-import { registerDemoVaultCoverageSuite } from 'obsidian-dev-utils/script-utils/demo-vault-coverage';
-import { getRootFolder } from 'obsidian-dev-utils/script-utils/root';
 
 // Keeps the in-repo `demo-vault/` honest WITHOUT launching Obsidian. It enforces the authoring convention
 // Every vault owes its readers: an `# H1` and a prose opener on every note, Markdown links rather than
 // Wikilinks (which do not render on GitHub), no `[Docs]` line, every note reachable from `00 Start.md`,
-// And an `.obsidian/app.json` that commits none of the settings obsidian-dev-utils injects at release time.
+// And an `.obsidian/app.json` that commits none of the settings obsidian-dev-toolkit injects at release time.
 //
 // `rootFolder` alone is enough for those. Once your settings surface settles, add a reflection spec so the
 // Suite also fails when a setting is documented nowhere in the vault, or when a note names one that no

package/templates/default/src/docs-showcase.desktop.integration.test.ts.ejs

@@ -0,0 +1,77 @@
+import { readFileSync } from 'node:fs';
+import { evalInObsidian } from 'obsidian-integration-testing';
+import {
+  describe,
+  expect,
+  it
+} from 'vitest';
+
+/**
+ * The part of Obsidian's command registry this suite reads. It is not in the public API, so it is declared here
+ * rather than taken from `obsidian`.
+ */
+interface AppWithCommands {
+  readonly commands: CommandRegistry;
+}
+
+interface CommandEntry {
+  readonly callback?: () => unknown;
+}
+
+interface CommandRegistry {
+  readonly commands: Readonly<Record<string, CommandEntry | undefined>>;
+}
+
+const PLUGIN_ID = '<%= pluginId %>';
+
+interface DocsEntryRecord {
+  readonly id: string;
+  readonly source: string;
+}
+
+// The entries `src/docs/index.ts` registers, one per runnable code block of the docs, read when the suite is collected
+// So that each block is its own test.
+const ENTRY_PATTERN = /^ {4}id: "(?<Id>[^"]+)",\n(?:.*\n){2} {4}source: "(?<Source>[^"]+)"$/gm;
+const entries: DocsEntryRecord[] = [...readFileSync(new URL('docs/index.ts', import.meta.url), 'utf-8').matchAll(ENTRY_PATTERN)]
+  .map((match) => ({ id: match.groups?.['Id'] ?? '', source: match.groups?.['Source'] ?? '' }));
+
+// Runs every `Docs:` command in a real Obsidian and fails on any that throws: the showcase compiles by
+// Construction, and this is what proves each block also RUNS against the app it was written for.
+describe('Developer docs showcase', () => {
+  it('registers a command for every runnable code block', () => {
+    expect(entries.length).toBeGreaterThan(0);
+  });
+
+  for (const entry of entries) {
+    it(`runs docs-${entry.id}, and links its docs page from what it shows`, async () => {
+      const failure = await evalInObsidian({
+        async callback({ app, commandId, source }): Promise<string> {
+          const untypedApp: unknown = app;
+          const command = (untypedApp as AppWithCommands).commands.commands[commandId];
+          if (!command?.callback) {
+            return `There is no command ${commandId}.`;
+          }
+          // The previous block's Notices are still up, and two blocks under one heading share a page.
+          for (const notice of activeDocument.querySelectorAll('.notice')) {
+            notice.remove();
+          }
+          try {
+            await command.callback();
+            // A Notice, a modal and a settings tab are each where some command puts the link; nothing else links the docs.
+            const links = [...activeDocument.querySelectorAll('a')].map((link) => link.getAttribute('href'));
+            return links.includes(source) ? '' : `Nothing ${commandId} showed links ${source}.`;
+          } catch (error) {
+            return error instanceof Error ? error.message : String(error);
+          } finally {
+            // A block that opens a modal leaves it open; close it so it does not sit over the next one.
+            for (const modalContainer of activeDocument.querySelectorAll('.modal-container')) {
+              modalContainer.remove();
+            }
+          }
+        },
+        input: { commandId: `${PLUGIN_ID}:docs-${entry.id}`, source: entry.source }
+      });
+      expect(failure).toBe('');
+    });
+  }
+});

package/templates/default/src/editor-extensions/{sample-state-field.ts_dev-utils.ejs → sample-state-field.ts_framework.ejs}

@@ -3,7 +3,7 @@ import type {
   Transaction
 } from '@codemirror/state';
 import type { DecorationSet } from '@codemirror/view';
-import type { StateFieldSpec } from 'obsidian-dev-utils/codemirror/state-field-spec';
+import type { StateFieldSpec } from '@mnaoumov/obsidian-lib/codemirror/state-field-spec';
 
 import {
   RangeSetBuilder,

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

@@ -49,6 +49,6 @@ 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;
+    readonly 'sample-lit-element': SampleLitElement;
   }
 }

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

@@ -6,8 +6,8 @@ import {
 } from 'obsidian';
 
 interface SampleItem {
-  icon: string;
-  name: string;
+  readonly icon: string;
+  readonly name: string;
 }
 
 const SAMPLE_ITEMS: readonly SampleItem[] = [

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

@@ -1,4 +1,6 @@
+<%- render('bug-report-type-import') -%>
 import { Plugin as ObsidianPlugin } from 'obsidian';
+<%- render('bug-report-import') -%>
 
 import { Plugin } from './plugin.ts';
 
@@ -6,4 +8,5 @@ describe('<%= pluginShortName %>', () => {
   it('extends the Obsidian Plugin class', () => {
     expect(Plugin.prototype).toBeInstanceOf(ObsidianPlugin);
   });
+<%- render('bug-report-test') -%>
 });

package/templates/default/src/plugin.test.ts_jest@bug-report-import_has-bug-report-command.ejs

@@ -0,0 +1,4 @@
+import {
+  App,
+  Plugin as PluginHost
+} from 'obsidian-test-mocks/obsidian';

package/templates/default/src/plugin.test.ts_jest@bug-report-test_has-bug-report-command.ejs

@@ -0,0 +1,16 @@
+
+  // The plugin's own `onload` runs here, so this proves the command is registered, not only imported.
+  it('registers the Report a bug command', async () => {
+    const manifest: PluginManifest = {
+      author: 'test',
+      description: 'test',
+      id: 'test-plugin',
+      minAppVersion: '0.0.0',
+      name: 'Test Plugin',
+      version: '0.0.0'
+    };
+    const plugin = new Plugin(App.createConfigured__().asOriginalType__(), manifest);
+    await plugin.onload();
+    expect(PluginHost.fromOriginalType2__(plugin).commands__.has('report-bug')).toBe(true);
+    plugin.unload();
+  });

package/templates/default/src/plugin.test.ts_jest@bug-report-type-import_has-bug-report-command.ejs

@@ -0,0 +1,2 @@
+import type { PluginManifest } from 'obsidian';
+

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

@@ -1,4 +1,6 @@
+<%- render('bug-report-type-import') -%>
 import { Plugin as ObsidianPlugin } from 'obsidian';
+<%- render('bug-report-import') -%>
 import {
   describe,
   expect,
@@ -11,4 +13,5 @@ describe('<%= pluginShortName %>', () => {
   it('extends the Obsidian Plugin class', () => {
     expect(Plugin.prototype).toBeInstanceOf(ObsidianPlugin);
   });
+<%- render('bug-report-test') -%>
 });

package/templates/default/src/plugin.test.ts_vitest@bug-report-import_has-bug-report-command.ejs

@@ -0,0 +1,4 @@
+import {
+  App,
+  Plugin as PluginHost
+} from 'obsidian-test-mocks/obsidian';

package/templates/default/src/plugin.test.ts_vitest@bug-report-test_has-bug-report-command.ejs

@@ -0,0 +1,16 @@
+
+  // The plugin's own `onload` runs here, so this proves the command is registered, not only imported.
+  it('registers the Report a bug command', async () => {
+    const manifest: PluginManifest = {
+      author: 'test',
+      description: 'test',
+      id: 'test-plugin',
+      minAppVersion: '0.0.0',
+      name: 'Test Plugin',
+      version: '0.0.0'
+    };
+    const plugin = new Plugin(App.createConfigured__().asOriginalType__(), manifest);
+    await plugin.onload();
+    expect(PluginHost.fromOriginalType2__(plugin).commands__.has('report-bug')).toBe(true);
+    plugin.unload();
+  });

package/templates/default/src/plugin.test.ts_vitest@bug-report-type-import_has-bug-report-command.ejs

@@ -0,0 +1,2 @@
+import type { PluginManifest } from 'obsidian';
+

package/templates/default/src/preact-components/{sample-preact-component.tsx_dev-utils.ejs → sample-preact-component.tsx_framework.ejs}

@@ -16,7 +16,7 @@ const UNSET_APP: unknown = undefined;
 export const AppContext = createContext<App>(UNSET_APP as App);
 
 export interface SamplePreactComponentProps {
-  startCount: number;
+  readonly startCount: number;
 }
 
 export function SamplePreactComponent(props: SamplePreactComponentProps): JSX.Element {

package/templates/default/src/preact-components/sample-preact-component.tsx_standalone.ejs

@@ -16,7 +16,7 @@ const UNSET_APP: unknown = undefined;
 export const AppContext = createContext<App>(UNSET_APP as App);
 
 export interface SamplePreactComponentProps {
-  startCount: number;
+  readonly startCount: number;
 }
 
 export function SamplePreactComponent(props: SamplePreactComponentProps): JSX.Element {

package/templates/default/src/react-components/{sample-react-component.tsx_dev-utils.ejs → sample-react-component.tsx_framework.ejs}

@@ -1,10 +1,10 @@
 import type { JSX } from 'react';
 
-import { useApp } from 'obsidian-dev-utils/obsidian/react/app-context';
+import { useApp } from '@mnaoumov/obsidian-lib/react/app-context';
 import { useState } from 'react';
 
 export interface SampleReactComponentProps {
-  startCount: number;
+  readonly startCount: number;
 }
 
 export function SampleReactComponent(props: SampleReactComponentProps): JSX.Element {

package/templates/default/src/react-components/sample-react-component.tsx_standalone.ejs

@@ -16,7 +16,7 @@ const UNSET_APP: unknown = undefined;
 export const AppContext = createContext<App>(UNSET_APP as App);
 
 export interface SampleReactComponentProps {
-  startCount: number;
+  readonly startCount: number;
 }
 
 export function SampleReactComponent(props: SampleReactComponentProps): JSX.Element {

package/templates/default/src/solid-components/{sample-solid-component.tsx_dev-utils.ejs → sample-solid-component.tsx_framework.ejs}

@@ -16,7 +16,7 @@ const UNSET_APP: unknown = undefined;
 export const AppContext = createContext<App>(UNSET_APP as App);
 
 export interface SampleSolidComponentProps {
-  startCount: number;
+  readonly startCount: number;
 }
 
 export function SampleSolidComponent(props: SampleSolidComponentProps): JSX.Element {

package/templates/default/src/solid-components/sample-solid-component.tsx_standalone.ejs

@@ -16,7 +16,7 @@ const UNSET_APP: unknown = undefined;
 export const AppContext = createContext<App>(UNSET_APP as App);
 
 export interface SampleSolidComponentProps {
-  startCount: number;
+  readonly startCount: number;
 }
 
 export function SampleSolidComponent(props: SampleSolidComponentProps): JSX.Element {

package/templates/default/src/styles/css-modules.d.ts.ejs

@@ -1,4 +1,10 @@
-declare module '*.module.css' {
-  const classes: Record<string, string>;
-  export default classes;
+// A CSS module's default export is its scoped class names, keyed by the names the stylesheet uses.
+// TypeScript resolves an import against the FIRST declared pattern among equally long prefixes, so a
+// `declare module '*.css'` read before a `'*.module.css'` one types every CSS module as `any`, and the
+// typed lint rules then reject each use of its class names. It is spelled `*module.css`, without the
+// dot, because the same pattern string would merge with obsidian-dev-toolkit's declaration into a
+// duplicate default export.
+declare module '*module.css' {
+  const classNames: Readonly<Record<string, string>>;
+  export default classNames;
 }

package/templates/default/src/styles/{main.css_dev-utils.ejs → main.css_framework.ejs}

@@ -1,11 +1,11 @@
 <%- render('content') -%>
 /**
  * You can remove this file if you don't need any styles
- * See default library styles: https://github.com/mnaoumov/obsidian-dev-utils/blob/main/src/styles/main.scss
- * See available library css classes: https://github.com/mnaoumov/obsidian-dev-utils/blob/main/src/obsidian/css-class.ts
+ * See default library styles: https://github.com/mnaoumov/obsidian-lib/blob/main/src/styles/main.scss
+ * See available library css classes: https://github.com/mnaoumov/obsidian-lib/blob/main/src/css-class.ts
  */
 
-.<%= pluginId %>.obsidian-dev-utils {
+.<%= pluginId %>.obsidian-lib {
   /* Override library styles */
 }
 

package/templates/default/src/styles/main.module.css.ejs

@@ -1,3 +1,5 @@
-.<%= pluginId %> {
-  /* Add your plugin styles here */
+/* A CSS module: the build scopes every class name in it, and importing it gives the scoped names.
+   `sample-css-module-command.ts` applies this one. */
+.sampleNotice {
+  color: var(--text-accent);
 }

package/templates/default/src/styles/{main.scss_dev-utils.ejs → main.scss_framework.ejs}

@@ -1,10 +1,10 @@
 /**
  * You can remove this file if you don't need any styles
- * See default library styles: https://github.com/mnaoumov/obsidian-dev-utils/blob/main/src/styles/main.scss
- * See available library css classes: https://github.com/mnaoumov/obsidian-dev-utils/blob/main/src/obsidian/css-class.ts
+ * See default library styles: https://github.com/mnaoumov/obsidian-lib/blob/main/src/styles/main.scss
+ * See available library css classes: https://github.com/mnaoumov/obsidian-lib/blob/main/src/css-class.ts
  */
 
-.<%= pluginId %>.obsidian-dev-utils {
+.<%= pluginId %>.obsidian-lib {
   /* Override library styles */
 }
 

package/templates/default/src/styles/sample-css-module-command.ts.ejs

@@ -0,0 +1,30 @@
+import type { Plugin } from 'obsidian';
+
+import { Notice } from 'obsidian';
+
+import classNames from './main.module.css';
+
+/**
+ * Registers the command that shows a notice styled by the sample CSS module.
+ *
+ * This is not decoration, and deleting it does more than remove a command. A CSS module is a JavaScript
+ * module that exports its scoped class names, and a bundler drops an import whose names nothing reads --
+ * vite does, together with the CSS -- so with no real use of the class names the build emits no
+ * `styles.css` while staying green. Whatever replaces this sample, keep something in `src/` applying a
+ * class from the module.
+ */
+export function registerSampleCssModuleCommand(plugin: Plugin): void {
+  plugin.addCommand({
+    callback: () => {
+      showStyledNotice();
+    },
+    id: 'sample-css-module',
+    name: 'Sample CSS module'
+  });
+}
+
+function showStyledNotice(): void {
+  new Notice(createFragment((fragment) => {
+    fragment.createSpan({ cls: classNames['sampleNotice'] ?? '', text: 'Styled by a CSS module' });
+  }));
+}

package/templates/default/src/svelte-components/sample-svelte-component.d.ts.ejs

@@ -1,7 +1,7 @@
 export interface SampleSvelteComponentExports {
-  increment: () => void;
+  readonly increment: () => void;
 }
 
 export interface SampleSvelteComponentProps {
-  startCount: number;
+  readonly startCount: number;
 }

package/templates/default/src/views/{sample-react-view.tsx_dev-utils.ejs → sample-react-view.tsx_framework.ejs}

@@ -1,7 +1,7 @@
 import type { Root } from 'react-dom/client';
 
+import { AppContext } from '@mnaoumov/obsidian-lib/react/app-context';
 import { ItemView } from 'obsidian';
-import { AppContext } from 'obsidian-dev-utils/obsidian/react/app-context';
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
 

package/templates/default/src/views/sample-view.ts.ejs

@@ -1,3 +1,4 @@
+import { appendCodeBlock } from '@mnaoumov/obsidian-lib/html-element';
 import { ItemView } from 'obsidian';
 
 export const SAMPLE_VIEW_TYPE = '<%= pluginShortName %>-SampleView';
@@ -14,7 +15,7 @@ export class SampleView extends ItemView {
   public override onOpen(): Promise<void> {
     const container = this.contentEl;
     container.empty();
-    container.createEl('h4', { text: '<%= pluginName %>' });
+    appendCodeBlock(container.createEl('h4'), '<%= pluginName %>');
 
     const vaultName = this.app.vault.getName();
     container.createEl('p', { text: `Vault: ${vaultName}` });

package/templates/default/src/wasm/answer.ts_wasm-adapter.ejs

@@ -0,0 +1,18 @@
+import bytes from './module.wasm';
+
+/**
+ * Instantiates the sample WebAssembly module and calls its one export.
+ *
+ * obsidian-dev-toolkit's `wasm` build option inlines the module into `main.js` and makes its import the module's
+ * bytes, whichever bundler builds the plugin.
+ */
+export async function getWasmAnswer(): Promise<number> {
+  // `compile` then `instantiate`, rather than `instantiate(bytes)` in one call: `WebAssembly.Module` is
+  // Declared as an EMPTY interface, so a `Uint8Array` satisfies it too and the one-call form resolves to
+  // The overload taking an already-compiled module -- whose result is a bare `Instance` with no
+  // `instance` property on it, which is TS2339 rather than anything about WebAssembly.
+  const compiled = await WebAssembly.compile(bytes);
+  const instance = await WebAssembly.instantiate(compiled);
+  const answer = instance.exports['answer'] as () => number;
+  return answer();
+}