@scm-js/plugin-api 1.53.0 → 1.55.0

package/index.d.ts

@@ -2518,7 +2518,7 @@ export interface PluginApi {
 	readonly menu: MenuApi;
 	/** Items in the right-click menus of the map and the terrain palette. */
 	readonly contextMenu: ContextMenuApi;
-	/** Key combinations, tried before the editor's own and never while a text field has focus. */
+	/** Key combinations, tried before the editor's own, and never while a text field has focus or a dialog is open. */
 	readonly hotkeys: HotkeyApi;
 	readonly commands: CommandsApi;
 	/** Live objects one plugin holds out for others to use, found by name and watched for arriving. */
@@ -2535,7 +2535,7 @@ export interface PluginApi {
 	readonly sync: SyncApi;
 	/**
 	 * A small key-value store of the plugin's own, kept in the browser's local storage under
-	 * the plugin's id and listed with everything else in Preferences ▸ Browser storage.
+	 * the plugin's id and listed with everything else in Preferences ▸ Storage.
 	 */
 	readonly storage: StorageApi;
 	/** `console.log` with the plugin's name in front. */
@@ -4591,6 +4591,20 @@ export interface TilesetApi {
 	load(tileset?: TilesetId): Promise<boolean>;
 	raw(): LoadedTileset | null;
 }
+/**
+ * What is selected on each object layer, by index into the scenario's lists, with a
+ * setter for each; the Clipboard layer's marked area; the active layer; and the Layers
+ * panel's locks.
+ *
+ * @example
+ * // Select Player 1's units inside the marked area.
+ * const area = api.selection.markedArea();
+ * if (area) {
+ *   const mine = new Set(api.query.unitsOf(0));
+ *   api.selection.setLayer("units");
+ *   api.selection.setUnits(api.query.unitsIn(area).filter((i) => mine.has(i)));
+ * }
+ */
 export interface SelectionApi {
 	/** The Cut / Copy / Paste layer's marked rectangle, in tiles. */
 	markedArea(): Rect | null;
@@ -4950,6 +4964,7 @@ export interface DialogTransfer {
 export interface DialogSpec {
 	title: string;
 	size?: DialogSize;
+	/** A fixed height (720 CSS pixels, less on a small screen) instead of the content's own, for a body that scrolls or fills. */
 	tall?: boolean;
 	/** Fill `body` (an empty `<div>` inside the dialog); return a cleanup if you need one. */
 	mount(body: HTMLElement, dialog: DialogHandle): void | (() => void);
@@ -5112,6 +5127,24 @@ export interface MapViewSpec {
 	 * its box and presses are the map's own view's (hidden behind this one).
 	 */
 	minimap?: MapViewMinimapSpec;
+	/**
+	 * View ▸ Fog of War, the toolbar's button and its key, while the view is shown: turn the view's
+	 * own fog on or off. The toggle then shows the view's fog, as you last said it
+	 * (`MapViewHandle.setFog`), not the map's. Without `onFog` the toggle is off while the view is shown.
+	 */
+	onFog?(on: boolean): void;
+	/**
+	 * What `MapViewHandle.paintOver` draws changed — View ▸ Grid or Locations turned on or off, the
+	 * grid's settings, the map's locations, another plugin's overlay: draw over the view again. With
+	 * it the editor's Grid, Locations and Location Names toggles, and the other plugins' overlays,
+	 * stay on offer while the view is shown; without it they are off, as the view cannot show them.
+	 */
+	onRepaint?(): void;
+}
+/** Where the pointer is over a map view (`MapViewHandle.setPointer`), in map pixels. */
+export interface MapViewPointer {
+	x: number;
+	y: number;
 }
 /**
  * Where a view looks, in map pixels (32 to a tile): the point in the middle of what it shows,
@@ -5214,6 +5247,31 @@ export interface MapViewHandle extends Disposable {
 	wheel(wheel: MapViewWheel): boolean;
 	/** Make the minimap's picture again (`minimap.draw`), at most once a frame. Cheap: call it as the view's contents move. */
 	redrawMinimap(): void;
+	/**
+	 * Whether the view shows its fog now, for View ▸ Fog of War and the toolbar's button while it
+	 * is shown (`onFog`); null when it has none to show at the moment, which greys the toggle. Say
+	 * it whenever it changes, by the person's hand or yours.
+	 */
+	setFog(on: boolean | null): void;
+	/**
+	 * Where the pointer is over the view, in map pixels, for the status bar's tile and position;
+	 * null once it leaves. A view in an iframe hears the pointer and the editor does not.
+	 */
+	setPointer(at: MapViewPointer | null): void;
+	/**
+	 * Draw what the editor draws over a map onto your canvas over the view, mapped by `view` as a
+	 * map tool's or an overlay's `draw` is: the grid and the locations as View ▸ Grid, Locations and
+	 * Location Names have them, then the other plugins' visible overlays (yours are your own to draw).
+	 * Call it from your own drawing, above the view's picture and below your marks, each time you
+	 * draw; `onRepaint` says when it would draw something else. Nothing while the view is not shown.
+	 *
+	 * @example
+	 * function drawOver(ctx: CanvasRenderingContext2D, v: MapView) {
+	 *   handle.paintOver(ctx, v);
+	 *   drawMyMarks(ctx, v);
+	 * }
+	 */
+	paintOver(ctx: CanvasRenderingContext2D, view: MapView): void;
 }
 export interface PanelHandle {
 	close(): void;
@@ -5481,14 +5539,14 @@ export type OverlayAbove =
  | "everything";
 /**
  * An overlay is a picture drawn over the map that the user can turn on and off: it
- * is listed under View ▸ Overlays and in the Layers panel, stays while the user works
+ * is a tick in the View menu and a row in the Layers panel, stays while the user works
  * on any layer, and never takes the pointer — clicks go to the active layer's tools
  * as usual. It hears the pointer through `onHover`, which is how a readout follows the
  * mouse while the user places units. Register one at activation and keep the handle;
  * it goes away with the plugin.
  *
  * @example
- * // A ring twelve tiles wide round every start location, listed under View ▸ Overlays.
+ * // A ring twelve tiles wide round every start location, a tick in the View menu.
  * const overlay = api.ui.overlay({
  *   name: "Start rings",
  *   above: "objects",
@@ -5505,7 +5563,7 @@ export type OverlayAbove =
  * api.events.on("units", () => overlay.redraw());
  */
 export interface OverlaySpec {
-	/** Shown in View ▸ Overlays and the Layers panel. Unique per plugin. In English, like a menu label: shown through the plugin's registered catalogues. */
+	/** Shown in the View menu and the Layers panel. Unique per plugin. In English, like a menu label: shown through the plugin's registered catalogues. */
 	name: string;
 	/** Start visible; true by default. What the user last set for this name wins for the session. */
 	visible?: boolean;
@@ -5654,7 +5712,7 @@ export interface UiApi {
 	 */
 	mapTool(spec: MapToolSpec): MapToolHandle;
 	/**
-	 * A picture over the map the user can switch on and off (View ▸ Overlays, the Layers
+	 * A picture over the map the user can switch on and off (a tick in the View menu, the Layers
 	 * panel) and that stays while they work on any layer. It draws at every repaint and
 	 * hears the pointer, but never takes it. As many as you like; they go with the plugin.
 	 */
@@ -6256,7 +6314,8 @@ export interface ContextMenuApi {
 }
 export interface HotkeyApi {
 	/**
-	 * `"Ctrl+Shift+I"`, `"Alt+F9"`, `"F8"` — modifiers in any order, then a key name.
+	 * `"Ctrl+Shift+I"`, `"Alt+F9"`, `"F8"` — modifiers in any order, then a key name. Tried
+	 * before the editor's own keys, and never while a text field has focus or a dialog is open.
 	 *
 	 * @example
 	 * api.hotkeys.add("Ctrl+Alt+G", () => api.view.setFlags({ grid: !api.view.flags().grid }));

package/package.json

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