Update plugin API

.gitignore

@@ -1,4 +1,4 @@
 dist/
 node_modules/
 publish/
-joplin-plugin-quick-links.code-workspace
+joplin-plugin-quick-links.code-workspace

api/Global.d.ts

@@ -1,14 +1,14 @@
 import Plugin from '../Plugin';
 import Joplin from './Joplin';
+/**
+ * @ignore
+ */
 /**
  * @ignore
  */
 export default class Global {
  private joplin_;
- private requireWhiteList_;
  constructor(implementation: any, plugin: Plugin, store: any);
  get joplin(): Joplin;
- private requireWhiteList;
- require(filePath: string): any;
  get process(): any;
 }

api/Joplin.d.ts

@@ -49,4 +49,17 @@ export default class Joplin {
  get views(): JoplinViews;
  get interop(): JoplinInterop;
  get settings(): JoplinSettings;
+ /**
+ * It is not possible to bundle native packages with a plugin, because they
+ * need to work cross-platforms. Instead access to certain useful native
+ * packages is provided using this function.
+ *
+ * Currently these packages are available:
+ *
+ * - [sqlite3](https://www.npmjs.com/package/sqlite3)
+ * - [fs-extra](https://www.npmjs.com/package/fs-extra)
+ *
+ * [View the demo plugin](https://github.com/laurent22/joplin/tree/dev/packages/app-cli/tests/support/plugins/nativeModule)
+ */
+ require(_path: string): any;
 }

api/JoplinCommands.d.ts

@@ -19,6 +19,34 @@ import { Command } from './types';
  *
  * To view what arguments are supported, you can open any of these files
  * and look at the `execute()` command.
+ *
+ * ## Executing editor commands
+ *
+ * There might be a situation where you want to invoke editor commands
+ * without using a {@link JoplinContentScripts | contentScript}. For this
+ * reason Joplin provides the built in `editor.execCommand` command.
+ *
+ * `editor.execCommand` should work with any core command in both the
+ * [CodeMirror](https://codemirror.net/doc/manual.html#execCommand) and
+ * [TinyMCE](https://www.tiny.cloud/docs/api/tinymce/tinymce.editorcommands/#execcommand) editors,
+ * as well as most functions calls directly on a CodeMirror editor object (extensions).
+ *
+ * * [CodeMirror commands](https://codemirror.net/doc/manual.html#commands)
+ * * [TinyMCE core editor commands](https://www.tiny.cloud/docs/advanced/editor-command-identifiers/#coreeditorcommands)
+ *
+ * `editor.execCommand` supports adding arguments for the commands.
+ *
+ * ```typescript
+ * await joplin.commands.execute('editor.execCommand', {
+ * name: 'madeUpCommand', // CodeMirror and TinyMCE
+ * args: [], // CodeMirror and TinyMCE
+ * ui: false, // TinyMCE only
+ * value: '', // TinyMCE only
+ * });
+ * ```
+ *
+ * [View the example using the CodeMirror editor](https://github.com/laurent22/joplin/blob/dev/packages/app-cli/tests/support/plugins/codemirror_content_script/src/index.ts)
+ *
  */
 export default class JoplinCommands {
  /**

api/JoplinPlugins.d.ts

@@ -23,4 +23,21 @@ export default class JoplinPlugins {
  * @deprecated Use joplin.contentScripts.register()
  */
  registerContentScript(type: ContentScriptType, id: string, scriptPath: string): Promise<void>;
+ /**
+ * Gets the plugin own data directory path. Use this to store any
+ * plugin-related data. Unlike [[installationDir]], any data stored here
+ * will be persisted.
+ */
+ dataDir(): Promise<string>;
+ /**
+ * Gets the plugin installation directory. This can be used to access any
+ * asset that was packaged with the plugin. This directory should be
+ * considered read-only because any data you store here might be deleted or
+ * re-created at any time. To store new persistent data, use [[dataDir]].
+ */
+ installationDir(): Promise<string>;
+ /**
+ * @deprecated Use joplin.require()
+ */
+ require(_path: string): any;
 }

api/JoplinSettings.d.ts

@@ -22,11 +22,18 @@ export default class JoplinSettings {
  private get keyPrefix();
  private namespacedKey;
  /**
- * Registers a new setting. Note that registering a setting item is dynamic and will be gone next time Joplin starts.
+ * Registers new settings.
+ * Note that registering a setting item is dynamic and will be gone next time Joplin starts.
  * What it means is that you need to register the setting every time the plugin starts (for example in the onStart event).
  * The setting value however will be preserved from one launch to the next so there is no risk that it will be lost even if for some
  * reason the plugin fails to start at some point.
  */
+ registerSettings(settings: Record<string, SettingItem>): Promise<void>;
+ /**
+ * @deprecated Use joplin.settings.registerSettings()
+ *
+ * Registers a new setting.
+ */
  registerSetting(key: string, settingItem: SettingItem): Promise<void>;
  /**
  * Registers a new setting section. Like for registerSetting, it is dynamic and needs to be done every time the plugin starts.

api/JoplinWorkspace.d.ts

@@ -35,7 +35,7 @@ export default class JoplinWorkspace {
  */
  onNoteContentChange(callback: Function): Promise<void>;
  /**
- * Called when the content of a note changes.
+ * Called when the content of the current note changes.
  */
  onNoteChange(handler: ItemChangeHandler): Promise<Disposable>;
  /**

api/types.ts

@@ -27,11 +27,12 @@ export interface Command {
  execute(...args: any[]): Promise<any | void>;
 
  /**
- * Defines whether the command should be enabled or disabled, which in turns affects
- * the enabled state of any associated button or menu item.
+ * Defines whether the command should be enabled or disabled, which in turns
+ * affects the enabled state of any associated button or menu item.
  *
- * The condition should be expressed as a "when-clause" (as in Visual Studio Code). It's a simple boolean expression that evaluates to
- * `true` or `false`. It supports the following operators:
+ * The condition should be expressed as a "when-clause" (as in Visual Studio
+ * Code). It's a simple boolean expression that evaluates to `true` or
+ * `false`. It supports the following operators:
  *
  * Operator | Symbol | Example
  * -- | -- | --
@@ -40,7 +41,15 @@ export interface Command {
  * Or | \|\| | "noteIsTodo \|\| noteTodoCompleted"
  * And | && | "oneNoteSelected && !inConflictFolder"
  *
- * Currently the supported context variables aren't documented, but you can [find the list here](https://github.com/laurent22/joplin/blob/dev/packages/lib/services/commands/stateToWhenClauseContext.ts).
+ * Joplin, unlike VSCode, also supports parenthesis, which allows creating
+ * more complex expressions such as `cond1 || (cond2 && cond3)`. Only one
+ * level of parenthesis is possible (nested ones aren't supported).
+ *
+ * Currently the supported context variables aren't documented, but you can
+ * find the list below:
+ *
+ * - [Global When Clauses](https://github.com/laurent22/joplin/blob/dev/packages/lib/services/commands/stateToWhenClauseContext.ts)
+ * - [Desktop app When Clauses](https://github.com/laurent22/joplin/blob/dev/packages/app-desktop/services/commands/stateToWhenClauseContext.ts)
  *
  * Note: Commands are enabled by default unless you use this property.
  */
@@ -330,16 +339,57 @@ export enum SettingItemType {
 export interface SettingItem {
  value: any;
  type: SettingItemType;
- public: boolean;
- label: string;
 
+ label: string;
  description?: string;
- isEnum?: boolean;
+
+ /**
+ * A public setting will appear in the Configuration screen and will be
+ * modifiable by the user. A private setting however will not appear there,
+ * and can only be changed programmatically. You may use this to store some
+ * values that you do not want to directly expose.
+ */
+ public: boolean;
+
+ /**
+ * You would usually set this to a section you would have created
+ * specifically for the plugin.
+ */
  section?: string;
- options?: any;
+
+ /**
+ * To create a setting with multiple options, set this property to `true`.
+ * That setting will render as a dropdown list in the configuration screen.
+ */
+ isEnum?: boolean;
+
+ /**
+ * This property is required when `isEnum` is `true`. In which case, it
+ * should contain a map of value => label.
+ */
+ options?: Record<any, any>;
+
+ /**
+ * Reserved property. Not used at the moment.
+ */
  appTypes?: string[];
+
+ /**
+ * Set this to `true` to store secure data, such as passwords. Any such
+ * setting will be stored in the system keychain if one is available.
+ */
  secure?: boolean;
+
+ /**
+ * An advanced setting will be moved under the "Advanced" button in the
+ * config screen.
+ */
  advanced?: boolean;
+
+ /**
+ * Set the min, max and step values if you want to restrict an int setting
+ * to a particular range.
+ */
  minimum?: number;
  maximum?: number;
  step?: number;