@scm-js/plugin-api 1.15.0 → 1.17.0

package/index.d.ts

@@ -2409,6 +2409,16 @@ export interface EditTransaction {
 	 * Returns records converted.
 	 */
 	convertDoodads(indices: number[]): number;
+	/**
+	 * Stamp a `Clip` with its top-left tile at (tx, ty) inside this transaction — the
+	 * clipboard's paste without the clipboard: the clip can come from anywhere (`clipboard.copy`,
+	 * a library, a file), the user's own clip is left alone, and several stamps, or a stamp
+	 * and the strokes around it, make one undo step. Every part the clip carries is laid down
+	 * unless `parts` says otherwise; `mode` is `"merge"` unless given. Terrain and doodads
+	 * from another tileset are refused, as a paste refuses them, and anything off the map is
+	 * skipped, both said in the result's `notes`.
+	 */
+	paste(clip: Clip, tx: number, ty: number, options?: PasteOptionsSpec): PasteResult;
 	/** A location in the lowest free slot (pixel bounds); returns the slot, or -1 when the table is full. */
 	addLocation(bounds: Bounds, name?: string, elevationFlags?: number): number;
 	editLocation(index: number, patch: LocationPatch): boolean;
@@ -2855,6 +2865,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 +2900,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
@@ -2956,6 +2986,12 @@ export interface PluginImage {
 	width: number;
 	height: number;
 }
+export interface RenderClipOptions {
+	/** Pixels per tile; 32 (the game's own) by default. A thumbnail wants 4–8. */
+	pixelsPerTile?: number;
+	/** Which parts to draw; every part the clip carries by default. */
+	parts?: Partial<ClipParts>;
+}
 /**
  * The pictures the viewport draws, for a plugin's own lists and previews: the same
  * cached canvases, so asking for one costs nothing after the first time. Everything is
@@ -2990,6 +3026,17 @@ export interface GraphicsApi {
 	 * tile rect. Everything it needs is loaded first; null without a map or a canvas.
 	 */
 	renderRect(rect: Rect, options?: Partial<MapImageOptions>): Promise<Blob | null>;
+	/**
+	 * A `Clip` drawn as the clipboard layer's paste ghost draws it: the picture (its own
+	 * tiles, or the catalogue's for a doodad-only clip), then units, sprites and doodad
+	 * overlays with the viewport's own graphics, then location boxes — a thumbnail for a
+	 * list of clips, or the ghost under the pointer while a plugin stamps one. It is drawn
+	 * with the graphics of the clip's *own* tileset (`clip.era`), which are in memory for
+	 * the open map once loaded and otherwise not, so a clip from another tileset answers
+	 * null; so does a missing tileset or a page with no canvas. Synchronous and uncached:
+	 * keep the result while the clip and the tileset stay the same.
+	 */
+	renderClip(clip: Clip, options?: RenderClipOptions): PluginImage | null;
 	/** The colour a player's units are drawn in, `#rrggbb`. */
 	playerColor(owner: number): string;
 	/**
@@ -3393,6 +3440,14 @@ export interface ClipboardApi {
 	 * nothing to copy.
 	 */
 	copy(source?: ClipSource): Clip | null;
+	/**
+	 * The clip `copy` would take, handed back instead of put on the clipboard — for a
+	 * plugin keeping clips of its own without disturbing the user's. `parts` overrides
+	 * `parts()` for this one capture. Null when there is nothing to take.
+	 */
+	capture(source?: ClipSource, options?: {
+		parts?: Partial<ClipParts>;
+	}): Clip | null;
 	/** Copy, then remove the source's objects as one undo step (terrain and fog stay). Null when there was nothing. */
 	cut(source?: ClipSource): Clip | null;
 	/**
@@ -3659,6 +3714,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 +3939,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 +4032,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
@@ -4464,7 +4545,12 @@ export interface StorageApi {
 	 * api.storage.set("options", { ...opts, showGrid: false });
 	 */
 	get<T>(key: string, fallback: T): T;
-	set(key: string, value: unknown): void;
+	/**
+	 * Store a value. False when the browser refused the write — its storage quota is a few
+	 * megabytes for the whole editor — so a plugin keeping something the user made can say
+	 * so instead of losing it silently.
+	 */
+	set(key: string, value: unknown): boolean;
 	remove(key: string): void;
 }
 /** A slug for storage keys and log prefixes. */

package/package.json

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