@scm-js/plugin-api 1.14.0 → 1.16.0

package/index.d.ts

@@ -1776,6 +1776,13 @@ export interface Preferences {
 	splash: boolean;
 	/** Ask before closing or replacing a map with unsaved changes. */
 	confirmClose: boolean;
+	/**
+	 * Open each map beside the ones already open, in its own tab, rather than in place of
+	 * the open one. Off is StarEdit's one map at a time: Open and New replace the map, asking
+	 * about unsaved changes first. Either way the blank map the editor starts on, untouched,
+	 * is replaced by the first map opened rather than kept beside it.
+	 */
+	multipleMaps: boolean;
 	/** What File ▸ New and the startup map start with. */
 	newMap: {
 		tileset: TilesetId;
@@ -2070,6 +2077,29 @@ export interface ResizeDocumentOptions {
 	/** Pull locations that hang past the new edge back inside; default true. */
 	clampLocations?: boolean;
 }
+/**
+ * Where a map opened or created goes. `"new"` opens it beside the open one, which stays
+ * open behind it; `"current"` opens it in place of the open one, through the unsaved-changes
+ * gate. Omitted, the editor follows its preference (several maps at once, on by default),
+ * except that the untouched blank map it started on is always replaced.
+ */
+export type OpenInto = "new" | "current";
+export interface OpenDocumentOptions {
+	into?: OpenInto;
+}
+/** One open map, as `document.list()` reports it. `active` marks the one in front — the one every other call reads and writes. */
+export interface OpenDocumentInfo {
+	/** Stable for the map's life in this session; never reused. */
+	id: number;
+	/** The scenario's name. */
+	name: string;
+	fileName: string | null;
+	tileset: TilesetId;
+	width: number;
+	height: number;
+	modified: boolean;
+	active: boolean;
+}
 /** File ▸ New's form: size, tileset, and the two strings the dialog asks for. */
 export interface NewDocumentOptions {
 	width: number;
@@ -2077,6 +2107,8 @@ export interface NewDocumentOptions {
 	tileset: TilesetId;
 	/** `Untitled Scenario` when omitted. */
 	name?: string;
+	/** Beside the open map or in place of it; see `OpenInto`. */
+	into?: OpenInto;
 	description?: string;
 	/** ISOM id of the terrain to fill with; the tileset's default ground when omitted. */
 	terrainId?: number;
@@ -2139,18 +2171,39 @@ export interface DocumentApi {
 	/** The undo and redo stacks' tops — the labels the Edit menu shows — and their depths, without moving anything. */
 	history(): DocumentHistory;
 	/**
-	 * Open a map file (`.scx` / `.scm` / `.chk`) in place of the current one, the way
-	 * File ▸ Open does: when the open map has unsaved changes and Preferences say to ask,
-	 * the Close Scenario dialog comes first and the user may cancel. Resolves true once
-	 * the file is the open document, false when the user kept the current map or the
-	 * file could not be read (the status bar says why).
+	 * The id of the map in front — the one `info()`, `scenario()` and every write are
+	 * about — or null with no map. Stable for the map's life, so a plugin can key what it
+	 * keeps per map on it. (Null too for a scenario a test put in place without the editor.)
+	 */
+	id(): number | null;
+	/**
+	 * Every open map, in the order the editor lists them, the one in front marked `active`.
+	 * Empty with no map. The list changes only through `open`, `create`, `activate` and
+	 * `close` (by any plugin or the user), each of which fires the `"document"` event.
+	 */
+	list(): OpenDocumentInfo[];
+	/**
+	 * Bring an open map to the front, as clicking its tab does: its history, selections and
+	 * view come back as they were left, and the `"document"` event fires with reason
+	 * `"switch"`. Nothing is re-read. True once it is in front (at once, when it already
+	 * was); false for an id that is not open. Call it for something the user asked for —
+	 * the map changing under someone mid-stroke is not a thing a plugin should do on its own.
 	 */
-	open(file: File | Blob | Uint8Array, fileName?: string): Promise<boolean>;
+	activate(id: number): boolean;
 	/**
-	 * A blank map in place of the current one, the way File ▸ New makes one: flat ground
-	 * of the tileset's default terrain (or `terrainId`), an ISOM lattice to match, every
-	 * section a fresh map needs. Goes through the same unsaved-changes gate as `open`.
-	 * Resolves true once the new map is the open document, false when the user kept the
+	 * Open a map file (`.scx` / `.scm` / `.chk`), the way File ▸ Open does: beside the open
+	 * map or in place of it as `options.into` (or, omitted, the editor's preference) says.
+	 * In place of a map with unsaved changes, when Preferences say to ask, the Close
+	 * Scenario dialog comes first and the user may cancel. Resolves true once the file is
+	 * the map in front, false when the user kept the current map or the file could not be
+	 * read (the status bar says why).
+	 */
+	open(file: File | Blob | Uint8Array, fileName?: string, options?: OpenDocumentOptions): Promise<boolean>;
+	/**
+	 * A blank map the way File ▸ New makes one: flat ground of the tileset's default terrain
+	 * (or `terrainId`), an ISOM lattice to match, every section a fresh map needs. Beside
+	 * the open map or in place of it as `open` decides, through the same unsaved-changes
+	 * gate. Resolves true once the new map is in front, false when the user kept the
 	 * current one.
 	 */
 	create(options: NewDocumentOptions): Promise<boolean>;
@@ -2170,10 +2223,13 @@ export interface DocumentApi {
 	/** File ▸ Save As (or Save Copy As with `copy`): the Save dialog, resolving as `save` does. */
 	saveAs(options?: SaveDocumentOptions): Promise<boolean>;
 	/**
-	 * File ▸ Close: through the same unsaved-changes gate as `open`. Resolves true once the
-	 * map is closed (`isOpen()` is then false), false when the user kept it.
+	 * File ▸ Close: the map in front, or the open map `id` names, through the same
+	 * unsaved-changes gate as `open` (a map behind is brought to the front first, so the
+	 * question is about what the user sees). Resolves true once the map is closed — another
+	 * open map is then in front, or `isOpen()` is false — false when the user kept it or no
+	 * map has that id.
 	 */
-	close(): Promise<boolean>;
+	close(id?: number): Promise<boolean>;
 	/**
 	 * A picture of the map as File ▸ Export ▸ Image draws it, as a PNG. `pixelsPerTile`
 	 * is the one dial (32 is the game's art 1:1, 1 is a minimap); the other options
@@ -2799,6 +2855,17 @@ export interface ViewApi {
 	visible(): Rect;
 	/** Scroll so a tile is in the middle of the viewport. */
 	center(x: number, y: number): void;
+	/**
+	 * Bring a tile rect onto the screen, gliding there by the shortest way rather than
+	 * jumping, and leaving the view alone when the rect is already visible. With `fit` the
+	 * view zooms out (never in) as far as the rect needs. Resolves once the view is there;
+	 * `false` when the user, or another request, moved it first — a plugin that follows its
+	 * own work around the map takes that as its cue to stop.
+	 *
+	 * @example
+	 * if (!(await api.view.reveal(rect))) following = false;
+	 */
+	reveal(rect: Rect, options?: RevealOptions): Promise<boolean>;
 	/** Scroll to an object (and select it, for a unit, sprite or location). */
 	goTo(target: GoTo): void;
 	/** The tile under the pointer, as the status bar shows it. */
@@ -2823,6 +2890,15 @@ export interface ViewApi {
 	 */
 	flash(target: FlashTarget): void;
 }
+/** How `view.reveal` brings a rect on screen. */
+export interface RevealOptions {
+	/** Zoom out to the zoom control's nearest step that fits the rect (plus the margin); never zooms in. Off by default. */
+	fit?: boolean;
+	/** Glide rather than jump. On by default. */
+	animate?: boolean;
+	/** Tiles kept clear between the rect and the viewport's edge when the view has to move. 1 by default. */
+	margin?: number;
+}
 export interface CommandSpec {
 	/**
 	 * The command's id. One without a dot is namespaced under the plugin
@@ -3603,6 +3679,15 @@ export interface PanelSpec {
 	title: string;
 	/** In CSS pixels; 260 by default. The panel is as tall as its content, up to the map's height. Ignored when docked. */
 	width?: number;
+	/** Floating only: a height in CSS pixels instead of the content's own; the body then scrolls, or fills, as its content asks. */
+	height?: number;
+	/**
+	 * Floating only: a grip at the bottom-right corner lets the user resize the panel, and
+	 * the size is remembered with the position for the session. The body is a column flex
+	 * box, so a root element with `flex: 1; min-height: 0` fills whatever size it has —
+	 * what a code editor or a long list beside the map wants.
+	 */
+	resizable?: boolean;
 	/**
 	 * Where the panel lives. `"float"` (the default) is a frame over the map the user drags
 	 * about. `"right"` puts it in the right dock as a panel of its own, under Minimap, Layers
@@ -3819,6 +3904,17 @@ export interface PickOptions {
 	/** Shown in the viewport's HUD while the user picks; also the status line. */
 	prompt?: string;
 }
+/** What `ui.pickObject` can pick. */
+export type PickObjectKind = "unit" | "location";
+export interface PickObjectOptions extends PickOptions {
+	/** Which kinds count; every kind when omitted. Under the pointer, a unit wins over a location. */
+	kinds?: PickObjectKind[];
+}
+/** What the user picked: the record's index in `document.scenario().units` or `.locations`. */
+export interface PickedObject {
+	kind: PickObjectKind;
+	index: number;
+}
 export interface PickFilesOptions {
 	/** `accept` for the file input, e.g. `"image/*"` or `".png,.jpg"`. */
 	accept?: string;
@@ -3901,6 +3997,12 @@ export interface UiApi {
 		x: number;
 		y: number;
 	} | null>;
+	/**
+	 * As `pickTile`, for an object: the user clicks a unit or a location. The viewport
+	 * outlines and names what is under the pointer as it moves; a click on nothing keeps
+	 * picking. Resolves with the kind and the record's index, or null as `pickArea` does.
+	 */
+	pickObject(options?: PickObjectOptions): Promise<PickedObject | null>;
 	/**
 	 * Decode a picture: a `File` / `Blob`, a `data:` URL, or an `http(s)` URL (fetched, and
 	 * when the site refuses cross-origin reads, loaded through an `<img>` with
@@ -4367,10 +4469,18 @@ export type DocumentChangeReason =
 /** File ▸ Close: `document.isOpen()` is now false. */
  | "close"
 /** The open map parsed again from edited bytes — a `document.sections` write, by any plugin. */
- | "replace";
+ | "replace"
+/**
+ * Another open map came to the front — a tab clicked, `document.activate`, or the map
+ * in front closed with others still open. Nothing was read or written; the map that
+ * was in front is still open behind, as it was. `id` says which map is in front now.
+ */
+ | "switch";
 export interface DocumentEvent {
 	reason: DocumentChangeReason;
 	fileName: string | null;
+	/** `document.id()` after the change: the map now in front, or null after a close. */
+	id: number | null;
 }
 /**
  * Listeners are notifications: they run after the change, in the order the plugins were

package/package.json

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