@scm-js/plugin-api 1.15.0 → 1.16.0

package/index.d.ts

@@ -2855,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. */
@@ -2879,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
@@ -3659,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
@@ -3875,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;
@@ -3957,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

package/package.json

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