@scm-js/plugin-api 1.47.0 → 1.49.0

package/index.d.ts

@@ -5029,6 +5029,111 @@ export interface FileTypeSpec {
 	extensions: string[];
 	open(files: File[]): void | Promise<void>;
 }
+/**
+ * Another way to look at a map, shown where the map is drawn (`ui.mapView`): a replay's
+ * game played out, a 3D view, a picture of something else entirely. The editor gives the
+ * view one element for its whole life and never moves it — an iframe in it is not loaded
+ * again when the view is hidden and shown — and lays it over the map, rulers and all.
+ */
+export interface MapViewSpec {
+	/** What the switch over the map calls it ("Game"). The map itself is "Map". */
+	title: string;
+	/**
+	 * Called once, with the element the view lives in. Fill it as you like; it is as large as
+	 * the map's area and in the page from the first time the view is shown. Return a function
+	 * to be called when the view goes (the plugin stops, or `dispose`).
+	 */
+	mount(element: HTMLElement): void | (() => void);
+	/**
+	 * The view is shown in the map's place, where the map was looking: `look` is the map's view
+	 * at that moment, or the other view's (`setCamera`) when the switch came from one. Turn to
+	 * look at the same place, as near the same scale as you can, so the switch keeps the person
+	 * where they were. Not called when another map, already showing the view, comes to the front.
+	 */
+	onShow?(look: MapViewCamera): void;
+	/**
+	 * What the minimap shows while the view is shown. Without it the minimap shows the map, and
+	 * its box and presses are the map's own view's (hidden behind this one).
+	 */
+	minimap?: MapViewMinimapSpec;
+}
+/**
+ * Where a view looks, in map pixels (32 to a tile): the point in the middle of what it shows,
+ * and how much of the map that is.
+ */
+export interface MapViewCamera {
+	x: number;
+	y: number;
+	width: number;
+	height: number;
+}
+/**
+ * A map view's own minimap (`MapViewSpec.minimap`): the minimap draws the map's ground, then
+ * `draw` over it in place of the map's units, start locations and fog, and its box where the
+ * view looks (`MapViewHandle.setCamera`).
+ *
+ * @example
+ * // A replay's units as dots, and the minimap moving the game's camera.
+ * const view = api.ui.mapView({
+ *   title: "Replay",
+ *   mount: (el) => el.append(frame),
+ *   minimap: {
+ *     draw(ctx, m) {
+ *       for (const u of units) {
+ *         ctx.fillStyle = u.colour;
+ *         ctx.fillRect(m.x(u.x) - 1, m.y(u.y) - 1, Math.max(2, u.width * m.scale), Math.max(2, u.height * m.scale));
+ *       }
+ *     },
+ *     press: (x, y) => game.lookAt(x, y),
+ *   },
+ * });
+ * game.onUnits(() => view.redrawMinimap());
+ * game.onCamera((c) => view.setCamera(c));
+ */
+export interface MapViewMinimapSpec {
+	/** Draw over the map's ground, each time the minimap's picture is made while the view is shown. */
+	draw?(ctx: CanvasRenderingContext2D, minimap: MinimapView): void;
+	/**
+	 * A press on the minimap, and each move of a drag from it, at a map pixel: look there. Without
+	 * it the minimap does not move anything while the view is shown.
+	 */
+	press?(x: number, y: number): void;
+}
+/** Map pixels to minimap canvas pixels, for `MapViewMinimapSpec.draw`. */
+export interface MinimapView {
+	/** Minimap canvas pixels per map pixel. */
+	scale: number;
+	/** A map pixel's x on the minimap's canvas. */
+	x(px: number): number;
+	y(py: number): number;
+	/** The canvas's size in pixels, each side (the map is centred in it, letterboxed). */
+	size: number;
+}
+export interface MapViewHandle extends Disposable {
+	/**
+	 * Offer the view on a map (by `OpenDocumentInfo.id`; the one in front when left out), or
+	 * stop offering it there. A map that offers views has a switch over it, the map's own
+	 * view first. Nothing is offered until you say so.
+	 */
+	offer(on: boolean, documentId?: number): void;
+	/** Show the view in that map's place (offering it there if it was not), or the map again. */
+	show(on: boolean, documentId?: number): void;
+	/** Whether the view is what the map in front shows now. */
+	isShown(): boolean;
+	/**
+	 * Whether the view is shown changed for the map in front: the person used the switch,
+	 * `show` was called, or another map came to the front.
+	 */
+	onChange(listener: (shown: boolean) => void): Disposable;
+	/**
+	 * Where the view looks now, in map pixels; call it whenever that changes. The minimap draws
+	 * its box there while the view is shown, and the map, shown again, opens on the same place at
+	 * the same scale.
+	 */
+	setCamera(camera: MapViewCamera): void;
+	/** Make the minimap's picture again (`minimap.draw`), at most once a frame. Cheap: call it as the view's contents move. */
+	redrawMinimap(): void;
+}
 export interface PanelHandle {
 	close(): void;
 	isOpen(): boolean;
@@ -5409,6 +5514,17 @@ export interface UiApi {
 	 * api.ui.fileType({ name: "StarCraft replay", extensions: [".rep"], open: (files) => loadReplays(files) });
 	 */
 	fileType(spec: FileTypeSpec): Disposable;
+	/**
+	 * Another way to look at the maps you choose, in the map's place, with a switch over the
+	 * map between it and the map itself (see `MapViewSpec`). A map shows one view at a time;
+	 * each map keeps the one it was left on. Ends with the plugin, or with `dispose`.
+	 *
+	 * @example
+	 * const game = api.ui.mapView({ title: "Game", mount: (el) => { el.append(frame); } });
+	 * // A map just opened is the one in front.
+	 * if (await api.document.open(map, "replay.scx", { viewOnly: { label: "Replay" } })) game.show(true);
+	 */
+	mapView(spec: MapViewSpec): MapViewHandle;
 	/**
 	 * A cell of your own in the status bar. One line of text beside the plugin's icon, a
 	 * spinner while `busy`, a click. Keep the handle and `set` it as things move; it

package/package.json

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