chore: routine joplin plugin framework update

GENERATOR_DOC.md

@@ -1,27 +1,22 @@
-# generator-joplin
+# Plugin development
 
-Scaffolds out a new Joplin plugin
+This documentation describes how to create a plugin, and how to work with the plugin builder framework and API.
 
 ## Installation
 
 First, install [Yeoman](http://yeoman.io) and generator-joplin using [npm](https://www.npmjs.com/) (we assume you have pre-installed [node.js](https://nodejs.org/)).
 
 ```bash
-npm install -g yo
+npm install -g yo@4.3.1
 npm install -g generator-joplin
 ```
 
 Then generate your new project:
 
 ```bash
-yo joplin
+yo --node-package-manager npm joplin
 ```
 
-## Development
-
-To test the generator for development purposes, follow the instructions there: https://yeoman.io/authoring/#running-the-generator
-This is a template to create a new Joplin plugin.
-
 ## Structure
 
 The main two files you will want to look at are:
@@ -39,6 +34,10 @@ To build the plugin, simply run `npm run dist`.
 
 The project is setup to use TypeScript, although you can change the configuration to use plain JavaScript.
 
+## Updating the manifest version number
+
+You can run `npm run updateVersion` to bump the patch part of the version number, so for example 1.0.3 will become 1.0.4. This script will update both the package.json and manifest.json version numbers so as to keep them in sync.
+
 ## Publishing the plugin
 
 To publish the plugin, add it to npmjs.com by running `npm publish`. Later on, a script will pick up your plugin and add it automatically to the Joplin plugin repository as long as the package satisfies these conditions:
@@ -67,6 +66,13 @@ By default, the compiler (webpack) is going to compile `src/index.ts` only (as w
 
 To get such an external script file to compile, you need to add it to the `extraScripts` array in `plugin.config.json`. The path you add should be relative to /src. For example, if you have a file in "/src/webviews/index.ts", the path should be set to "webviews/index.ts". Once compiled, the file will always be named with a .js extension. So you will get "webviews/index.js" in the plugin package, and that's the path you should use to reference the file.
 
+## More information
+
+- [Joplin Plugin API](https://joplinapp.org/api/references/plugin_api/classes/joplin.html)
+- [Joplin Data API](https://joplinapp.org/help/api/references/rest_api)
+- [Joplin Plugin Manifest](https://joplinapp.org/api/references/plugin_manifest/)
+- Ask for help on the [forum](https://discourse.joplinapp.org/) or our [Discord channel](https://discord.gg/VSj7AFHvpq)
+
 ## License
 
 MIT © Laurent Cozic

api/Joplin.d.ts

@@ -73,4 +73,8 @@ export default class Joplin {
      */
     require(_path: string): any;
     versionInfo(): Promise<import("./types").VersionInfo>;
+    /**
+     * Tells whether the current theme is a dark one or not.
+     */
+    shouldUseDarkColors(): Promise<boolean>;
 }

api/JoplinClipboard.d.ts

@@ -1,3 +1,4 @@
+import { ClipboardContent } from './types';
 export default class JoplinClipboard {
     private electronClipboard_;
     private electronNativeImage_;
@@ -26,4 +27,19 @@ export default class JoplinClipboard {
      * For example [ 'text/plain', 'text/html' ]
      */
     availableFormats(): Promise<string[]>;
+    /**
+     * Writes multiple formats to the clipboard simultaneously.
+     * This allows setting both text/plain and text/html at the same time.
+     *
+     * <span class="platform-desktop">desktop</span>
+     *
+     * @example
+     * ```typescript
+     * await joplin.clipboard.write({
+     *   text: 'Plain text version',
+     *   html: '<strong>HTML version</strong>'
+     * });
+     * ```
+     */
+    write(content: ClipboardContent): Promise<void>;
 }

api/JoplinCommands.d.ts

@@ -14,7 +14,7 @@ import Plugin from '../Plugin';
  * now, are not well documented. You can find the list directly on GitHub
  * though at the following locations:
  *
- * * [Main screen commands](https://github.com/laurent22/joplin/tree/dev/packages/app-desktop/gui/MainScreen/commands)
+ * * [Main screen commands](https://github.com/laurent22/joplin/tree/dev/packages/app-desktop/gui/WindowCommandsAndDialogs/commands)
  * * [Global commands](https://github.com/laurent22/joplin/tree/dev/packages/app-desktop/commands)
  * * [Editor commands](https://github.com/laurent22/joplin/tree/dev/packages/app-desktop/gui/NoteEditor/editorCommandDeclarations.ts)
  *
@@ -25,8 +25,13 @@ import Plugin from '../Plugin';
  * commands can be found in these places:
  *
  * * [Global commands](https://github.com/laurent22/joplin/tree/dev/packages/app-mobile/commands)
+ * * [Note screen commands](https://github.com/laurent22/joplin/tree/dev/packages/app-mobile/components/screens/Note/commands)
  * * [Editor commands](https://github.com/laurent22/joplin/blob/dev/packages/app-mobile/components/NoteEditor/commandDeclarations.ts)
  *
+ * Additionally, certain global commands have the same implementation on both platforms:
+ *
+ * * [Shared global commands](https://github.com/laurent22/joplin/tree/dev/packages/lib/commands)
+ *
  * ## Executing editor commands
  *
  * There might be a situation where you want to invoke editor commands

api/JoplinSettings.d.ts

@@ -42,21 +42,27 @@ export default class JoplinSettings {
      */
     values(keys: string[] | string): Promise<Record<string, unknown>>;
     /**
-     * @deprecated Use joplin.settings.values()
+     * Gets a setting value (only applies to setting you registered from your plugin).
      *
-     * Gets a setting value (only applies to setting you registered from your plugin)
+     * Note: If you want to retrieve all your plugin settings, for example when the plugin starts,
+     * it is recommended to use the `values()` function instead - it will be much faster than
+     * calling `value()` multiple times.
      */
     value(key: string): Promise<any>;
     /**
      * Sets a setting value (only applies to setting you registered from your plugin)
      */
     setValue(key: string, value: any): Promise<void>;
     /**
-     * Gets a global setting value, including app-specific settings and those set by other plugins.
+     * Gets global setting values, including app-specific settings and those set by other plugins.
      *
      * The list of available settings is not documented yet, but can be found by looking at the source code:
      *
-     * https://github.com/laurent22/joplin/blob/dev/packages/lib/models/Setting.ts#L142
+     * https://github.com/laurent22/joplin/blob/dev/packages/lib/models/settings/builtInMetadata.ts
+     */
+    globalValues(keys: string[]): Promise<any[]>;
+    /**
+     * @deprecated Use joplin.settings.globalValues()
      */
     globalValue(key: string): Promise<any>;
     /**

api/JoplinViews.d.ts

@@ -9,8 +9,17 @@ import JoplinViewsEditors from './JoplinViewsEditor';
 /**
  * This namespace provides access to view-related services.
  *
- * All view services provide a `create()` method which you would use to create the view object, whether it's a dialog, a toolbar button or a menu item.
- * In some cases, the `create()` method will return a [[ViewHandle]], which you would use to act on the view, for example to set certain properties or call some methods.
+ * ## Creating a view
+ *
+ * All view services provide a `create()` method which you would use to create the view object,
+ * whether it's a dialog, a toolbar button or a menu item. In some cases, the `create()` method will
+ * return a [[ViewHandle]], which you would use to act on the view, for example to set certain
+ * properties or call some methods.
+ *
+ * ## The `webviewApi` object
+ *
+ * Within a view, you can use the global object `webviewApi` for various utility functions, such as
+ * sending messages or displaying context menu. Refer to [[WebviewApi]] for the full documentation.
  */
 export default class JoplinViews {
     private store;

api/JoplinViewsDialogs.d.ts

@@ -43,6 +43,9 @@ export default class JoplinViewsDialogs {
      * Displays a message box with OK/Cancel buttons. Returns the button index that was clicked - "0" for OK and "1" for "Cancel"
      */
     showMessageBox(message: string): Promise<number>;
+    /**
+     * Displays a Toast notification in the corner of the application screen.
+     */
     showToast(toast: Toast): Promise<void>;
     /**
      * Displays a dialog to select a file or a directory. Same options and

api/JoplinViewsEditor.d.ts

@@ -1,5 +1,18 @@
 import Plugin from '../Plugin';
-import { ActivationCheckCallback, ViewHandle, UpdateCallback } from './types';
+import { ActivationCheckCallback, ViewHandle, UpdateCallback, EditorPluginCallbacks } from './types';
+interface SaveNoteOptions {
+    /**
+     * The ID of the note to save. This should match either:
+     * - The ID of the note currently being edited
+     * - The ID of a note that was very recently open in the editor.
+     *
+     * This property is present to ensure that the note editor doesn't write
+     * to the wrong note just after switching notes.
+     */
+    noteId: string;
+    /** The note's new content. */
+    body: string;
+}
 /**
  * Allows creating alternative note editors. You can create a view to handle loading and saving the
  * note, and do your own rendering.
@@ -41,10 +54,18 @@ export default class JoplinViewsEditors {
     private store;
     private plugin;
     private activationCheckHandlers_;
+    private unhandledActivationCheck_;
     constructor(plugin: Plugin, store: any);
     private controller;
+    /**
+     * Registers a new editor plugin. Joplin will call the provided callback to create new editor views
+     * associated with the plugin as necessary (e.g. when a new editor is created in a new window).
+     */
+    register(viewId: string, callbacks: EditorPluginCallbacks): Promise<void>;
     /**
      * Creates a new editor view
+     *
+     * @deprecated
      */
     create(id: string): Promise<ViewHandle>;
     /**
@@ -60,14 +81,21 @@ export default class JoplinViewsEditors {
      */
     onMessage(handle: ViewHandle, callback: Function): Promise<void>;
     /**
-     * Emitted when the editor can potentially be activated - this for example when the current note
-     * is changed, or when the application is opened. At that point should can check the current
-     * note and decide whether your editor should be activated or not. If it should return `true`,
-     * otherwise return `false`.
+     * Saves the content of the editor, without calling `onUpdate` for editors in the same window.
+     */
+    saveNote(handle: ViewHandle, props: SaveNoteOptions): Promise<void>;
+    /**
+     * Emitted when the editor can potentially be activated - this is for example when the current
+     * note is changed, or when the application is opened. At that point you should check the
+     * current note and decide whether your editor should be activated or not. If it should, return
+     * `true`, otherwise return `false`.
+     *
+     * @deprecated - `onActivationCheck` should be provided when the editor is first created with
+     * 	`editor.register`.
      */
     onActivationCheck(handle: ViewHandle, callback: ActivationCheckCallback): Promise<void>;
     /**
-     * Emitted when the editor content should be updated. This for example when the currently
+     * Emitted when your editor content should be updated. This is for example when the currently
      * selected note changes, or when the user makes the editor visible.
      */
     onUpdate(handle: ViewHandle, callback: UpdateCallback): Promise<void>;
@@ -86,3 +114,4 @@ export default class JoplinViewsEditors {
      */
     isVisible(handle: ViewHandle): Promise<boolean>;
 }
+export {};

api/JoplinViewsPanels.d.ts

@@ -80,5 +80,9 @@ export default class JoplinViewsPanels {
      * Tells whether the panel is visible or not
      */
     visible(handle: ViewHandle): Promise<boolean>;
+    /**
+     * Assuming that the current panel is an editor plugin view, returns
+     * whether the editor plugin view supports editing the current note.
+     */
     isActive(handle: ViewHandle): Promise<boolean>;
 }

api/JoplinWorkspace.d.ts

@@ -80,6 +80,8 @@ export default class JoplinWorkspace {
     filterEditorContextMenu(handler: FilterHandler<EditContextMenuFilterObject>): void;
     /**
      * Gets the currently selected note. Will be `null` if no note is selected.
+     *
+     * On desktop, this returns the selected note in the focused window.
      */
     selectedNote(): Promise<any>;
     /**
@@ -93,5 +95,12 @@ export default class JoplinWorkspace {
      * Gets the IDs of the selected notes (can be zero, one, or many). Use the data API to retrieve information about these notes.
      */
     selectedNoteIds(): Promise<string[]>;
+    /**
+     * Gets the last hash (note section ID) from cross-note link targeting specific section.
+     * New hash is available after `onNoteSelectionChange()` is triggered.
+     * Example of cross-note link where `hello-world` is a hash: [Other Note Title](:/9bc9a5cb83f04554bf3fd3e41b4bb415#hello-world).
+     * Method returns empty value when a note was navigated with method other than cross-note link containing valid hash.
+     */
+    selectedNoteHash(): Promise<string>;
 }
 export {};