@scm-js/plugin-api 1.13.0 → 1.15.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.
 	 */
-	open(file: File | Blob | Uint8Array, fileName?: string): Promise<boolean>;
+	list(): OpenDocumentInfo[];
 	/**
-	 * 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
+	 * 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.
+	 */
+	activate(id: number): boolean;
+	/**
+	 * 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
@@ -4121,6 +4177,79 @@ export interface BusyHandle {
 	/** Uncover the box. Safe to call twice. */
 	done(): void;
 }
+export interface StepsOptions extends WidgetOptions {
+	/**
+	 * While the list is `running`, show only its last this many rows; the rest come back
+	 * when it stops. For a list that grows past what a panel can hold while it is watched.
+	 * 0, the default, shows every row.
+	 */
+	tail?: number;
+}
+export interface StepOptions {
+	/** A character in front of the label, in the list's own vocabulary: ✎ for a change, ▸ for a read. */
+	icon?: string;
+	/** The row's tooltip. */
+	title?: string;
+	/** Begin running (a ring) rather than pending (a hollow mark). */
+	running?: boolean;
+}
+/** One row of a `steps` list. Each state takes the detail shown dim after the label. */
+export type StepHandle = {
+	readonly element: HTMLElement;
+	/** Rename the row (a step named before its arguments were known), and its tooltip. */
+	set(label: string, title?: string): void;
+	start(detail?: string): void;
+	done(detail?: string): void;
+	fail(detail?: string): void;
+	skip(detail?: string): void;
+	/** Change the detail and nothing else — a clock ticking beside a running step. */
+	detail(text: string): void;
+	/** Something under the label — a thumbnail, a line of output. */
+	append(node: Node): void;
+};
+/**
+ * A list of steps: one row per unit of work, each pending, running, done, failed or
+ * skipped, with a detail after its label and a mark at its end. What a builder shows
+ * while it builds, and what a tool-using assistant shows while it works.
+ */
+export type StepsElement = HTMLElement & {
+	add(label: string, options?: StepOptions): StepHandle;
+	/**
+	 * A line between rows that is not a step — an assistant's words between its tool
+	 * calls. `at` puts it before the row at that index; without it, at the end.
+	 */
+	note(content: string | Node, at?: number): HTMLElement;
+	/** Rows and notes so far, for `note`'s `at`. */
+	size(): number;
+	/** Steps so far (rows, not notes). */
+	count(): number;
+	/** Whether work is running: while it is, the `tail` window applies. */
+	running(on: boolean): void;
+};
+export interface FoldOptions extends WidgetOptions {
+	/** The line to begin with. */
+	text?: string;
+	/** Open to begin with. */
+	open?: boolean;
+	/** Start with a ring for a mark. */
+	busy?: boolean;
+}
+/**
+ * A block that folds to one line: a mark, the line, a control at its end, and a body.
+ * For work worth a line when it is done and a list while it runs — one turn of an
+ * assistant, a pass over the map — and for anything long that most readers skip, such
+ * as a model's reasoning.
+ */
+export type FoldElement = HTMLDetailsElement & {
+	/** Where the content goes. */
+	readonly body: HTMLElement;
+	/** The line: text, or text and nodes. */
+	set(...content: (string | Node)[]): void;
+	/** The mark in front of the line: `"busy"` for a ring, a character (✓, ✗) in a colour, or null for none. */
+	mark(sym: string | null, kind?: "ok" | "warn" | "error"): void;
+	/** A control at the end of the line — an Undo — whose click does not fold the block; null takes it away. */
+	action(node: HTMLElement | null): void;
+};
 /**
  * Buttons, fields, forms and lists in the editor's own styles, as plain DOM. A plugin
  * dialog built from these looks like a built-in one; `el` is the escape hatch for
@@ -4165,6 +4294,10 @@ export interface WidgetsApi {
 	 * Calling it again on a covered box only changes the label.
 	 */
 	busy(target: HTMLElement, options?: BusyOptions | string): BusyHandle;
+	/** A list of steps, each pending → running → done / failed / skipped, with a detail. */
+	steps(options?: StepsOptions): StepsElement;
+	/** A block folded to one line — a mark, a line that can change, a control at its end — over a body. */
+	fold(options?: FoldOptions): FoldElement;
 }
 export type TopMenu = "File" | "Edit" | "View" | "Layer" | "Scenario" | "Triggers" | "Tools" | "Plugins" | "Help";
 /**
@@ -4290,10 +4423,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.13.0",
+  "version": "1.15.0",
   "description": "Type declarations for the scmJS plugin API",
   "license": "MIT",
   "types": "index.d.ts",