@scm-js/plugin-api 1.9.0 → 1.11.0

package/index.d.ts

@@ -1810,7 +1810,20 @@ export interface Preferences {
 		checkOnStart: boolean;
 		nightly: boolean;
 	};
+	/**
+	 * What to do when an installed plugin has a newer release than the one running
+	 * (`plugins/updates.ts`). `notify` looks a few seconds after the plugins start and
+	 * raises a notice with a button to the rows offering the update; `manual` asks nothing
+	 * until **Check for update** is pressed on a row; `auto` installs what it finds, for the
+	 * plugins the user added — a default moves with the editor's own releases and is only
+	 * ever named in the notice. Every mode leaves the confirmation on a row's button alone.
+	 */
+	plugins: {
+		updates: PluginUpdateMode;
+	};
 }
+/** See `Preferences.plugins.updates`. */
+export type PluginUpdateMode = "notify" | "manual" | "auto";
 /**
  * The version a host provides; a manifest that asks for a newer one is refused. It stays
  * at 1 while the API is only used by the plugins in the scm-js organisation and grows
@@ -1827,8 +1840,9 @@ export interface Disposable {
  * builders (`document.edit` and `document.update`) are the exception, and deliberately
  * so: their operations apply as they are called and one commit closes the transaction
  * when the builder returns, so an `async` builder would commit the part of its work that
- * ran before the first `await` and leave the rest to land outside the entry, breaking
- * undo without an error. Do the awaiting *before* the call:
+ * ran before the first `await` and leave the rest with nowhere to land: the transaction
+ * is closed once the builder returns, and every call on it throws from then on. Do the
+ * awaiting *before* the call:
  *
  * ```ts
  * await api.tileset.load();                       // the async part, first
@@ -1954,6 +1968,8 @@ export interface PluginApi {
 	/** Key combinations, tried before the editor's own and never while a text field has focus. */
 	readonly hotkeys: HotkeyApi;
 	readonly commands: CommandsApi;
+	/** Live objects one plugin holds out for others to use, found by name and watched for arriving. */
+	readonly services: ServicesApi;
 	readonly events: EventsApi;
 	/**
 	 * A small key-value store of the plugin's own, kept in the browser's local storage under
@@ -2076,7 +2092,11 @@ export interface DocumentApi {
 	 * Returns an all-zero result with `changed: false` when no map is open.
 	 *
 	 * `build` is synchronous — see `Sync`. Await what you need (graphics, a pick, a
-	 * fetch) before the call, then write in one go.
+	 * fetch) before the call, then write in one go. The transaction is closed when
+	 * `build` returns; a call on it after that throws.
+	 *
+	 * A builder that throws is rolled back: what it had applied is taken off the map
+	 * again, nothing reaches the history or the modified flag, and the error reaches you.
 	 *
 	 * @example
 	 * // One undo entry called "Fill", however many operations it takes.
@@ -2093,7 +2113,11 @@ export interface DocumentApi {
 	 * transaction, the way a settings dialog's OK applies its whole form at once.
 	 * Operations apply as they are called; the commit marks the map modified and bumps
 	 * what the chrome reads. There is no undo entry: keep your own if you need one.
-	 * `build` is synchronous, as `edit`'s is.
+	 * `build` is synchronous, as `edit`'s is, and closed when it returns.
+	 *
+	 * There is nothing to roll an update back with, so a builder that throws leaves what
+	 * it wrote: the sections it touched are committed — the map is modified and the
+	 * chrome re-reads — and the error reaches you.
 	 *
 	 * @example
 	 * api.document.update("Rename", (tx) => {
@@ -2806,6 +2830,46 @@ export interface CommandsApi {
 	/** Every command registered by every plugin. */
 	list(): CommandInfo[];
 }
+export interface ServiceInfo {
+	id: string;
+	pluginId: string;
+	version: number;
+}
+export interface ServiceOptions {
+	/** The provider's version of the contract, 1 by default; a consumer that needs a newer one checks `ServiceInfo.version`. */
+	version?: number;
+}
+/**
+ * A command is one thing to do; a service is a thing to *hold* — an account another
+ * plugin signs in through, a connection, a catalogue. A plugin provides one live object
+ * under a name and every other plugin reaches it by that name, whatever order they were
+ * activated in: `watch` answers at once with what is there and again whenever the
+ * provider arrives or goes.
+ *
+ * The object's shape is the provider's to publish (a `contract.d.ts` in its repository,
+ * taken as a dev dependency and imported with `import type`, which is erased before the
+ * loader sees it); the editor never reads it. A name without a dot is namespaced under
+ * the plugin (`"account"` → `"scmjs-dev.account"`); one with a dot is taken as it is.
+ *
+ * @example
+ * // The provider:
+ * api.services.provide("account", accountService);
+ * // A consumer:
+ * api.services.watch<AccountService>("scmjs-dev.account", (account) => {
+ *   if (account) useSessionFrom(account); else useOwnSignIn();
+ * });
+ */
+export interface ServicesApi {
+	/** Hold an object out under a name. Providing the same name again replaces it; the Disposable withdraws it. */
+	provide<T extends object>(id: string, service: T, options?: ServiceOptions): Disposable;
+	/** The object under a name, or null when no plugin provides it. */
+	get<T extends object>(id: string): T | null;
+	has(id: string): boolean;
+	/** Called at once with the current object (or null) and again on every change of provider. */
+	watch<T extends object>(id: string, listener: (service: T | null, info: ServiceInfo | null) => void): Disposable;
+	/** Every service provided by every plugin. */
+	list(): ServiceInfo[];
+}
 /** A picture the editor already has: the canvas it draws from, and its size in pixels. */
 export interface PluginImage {
 	image: HTMLCanvasElement;
@@ -4068,9 +4132,11 @@ export interface WidgetsApi {
 export type TopMenu = "File" | "Edit" | "View" | "Layer" | "Scenario" | "Triggers" | "Tools" | "Plugins" | "Help";
 /**
  * A top-level menu, or a submenu by label: `"File/Import"`. A last segment that names no
- * submenu gets one of the plugin's own, at the end of the menu (`"Tools/AI"`).
+ * submenu gets one of the plugin's own, at the end of the menu (`"Tools/AI"`), and a
+ * first segment that names no top-level menu gets one made for the plugin, placed before
+ * Help (`"Account"`).
  */
-export type MenuPath = TopMenu | `${TopMenu}/${string}`;
+export type MenuPath = TopMenu | `${TopMenu}/${string}` | (string & {});
 export interface MenuItemSpec {
 	label: string;
 	/** Display only — bind the key with `hotkeys.add`. */
@@ -4174,6 +4240,8 @@ export type PluginEvent =
  | "file"
 /** A plugin registered or removed a command — how a plugin learns that one it calls by id has arrived. */
  | "commands"
+/** A plugin provided or withdrew a service — `services.watch` is the usual way to hear this for one name. */
+ | "services"
 /** The game data source changed: installed, switched to another data set, or a copy removed. `gameData.source()` says what it is now. */
  | "gameData";
 /** Why the document changed. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scm-js/plugin-api",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "description": "Type declarations for the scmJS plugin API",
   "license": "MIT",
   "types": "index.d.ts",