@scm-js/plugin-api 1.16.0 → 1.18.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;
@@ -2738,6 +2748,22 @@ export interface TriggersApi {
 	 * deactivation; call `refresh()` after a rebuild so the editors ask `locate` again.
 	 */
 	claim(spec: TriggerClaimSpec): TriggerClaimHandle;
+	/**
+	 * Every plugin's claims as located in `list` (TRIG as it stands, when omitted), first
+	 * run first — what an editor of the trigger list needs to fence or lock the generated
+	 * runs. A claim whose `locate` finds nothing, or throws, is left out.
+	 */
+	claims(list?: TriggerRecord[]): TriggerClaimRange[];
+}
+/** One claimed run as `triggers.claims` located it. */
+export interface TriggerClaimRange {
+	pluginId: string;
+	/** `TriggerClaimSpec.label`: what generated the run, as a sentence would use it. */
+	label: string;
+	/** The badge word the trigger list shows; the plugin's id by default. */
+	badge: string;
+	start: number;
+	count: number;
 }
 /**
  * A run of triggers a plugin generates and owns. It is found by *content*: the
@@ -2976,6 +3002,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
@@ -3010,6 +3042,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;
 	/**
@@ -3413,6 +3456,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;
 	/**
@@ -3655,6 +3706,19 @@ export interface DialogSpec {
 	 * (a code editor dismissing its own popups), judged by the element it landed on.
 	 */
 	keepOpenOnEscape?: (target: EventTarget | null) => boolean;
+	/**
+	 * Offer a slot of this dialog's own, so other plugins can add to it with `ui.dialogSlot`
+	 * the way they add to a built-in dialog: `id` is what they name (`"<plugin>.<name>"`),
+	 * `fields` the working copy lent to them, read live, and `payload` what the dialog was
+	 * opened with. The Text Trigger Editor plugin offers `"trigedit.text"` with a `text` field.
+	 */
+	slot?: DialogSlotOffer;
+}
+/** A slot a plugin dialog offers to other plugins; see `DialogSpec.slot`. */
+export interface DialogSlotOffer {
+	id: string;
+	payload?: Record<string, unknown>;
+	fields?: Record<string, DialogField>;
 }
 export interface DialogHandle {
 	close(): void;
@@ -3736,10 +3800,15 @@ export interface StatusItemHandle {
  * not yet applied to the map — so a slot's button can fill it in and leave OK to them.
  *
  * - `mapProperties`: `name`, `description`.
- * - `textTriggerEditor`: `text` (the whole editor); `payload.briefing` says which list.
  * - `triggerEditor`, `stringEditor`, `playerSettings`, `missionBriefing`: no fields, a slot only.
+ *
+ * A plugin's own dialog can offer a slot too (`DialogSpec.slot`), under an id of its
+ * choosing — `"trigedit.text"` is the Text Trigger Editor's, lending `text` with
+ * `payload.briefing` — and another plugin adds to it with the same `dialogSlot` call.
  */
-export type SlottedDialogId = "mapProperties" | "textTriggerEditor" | "triggerEditor" | "stringEditor" | "playerSettings" | "missionBriefing";
+export type SlottedDialogId = "mapProperties" | "triggerEditor" | "stringEditor" | "playerSettings" | "missionBriefing";
+/** A slot id: one of the editor's dialogs, or the id a plugin dialog offers (`"<plugin>.<name>"` by convention). */
+export type DialogSlotId = SlottedDialogId | (string & {});
 /** A form field a dialog lends to a slot: read it, set it, hear it change. */
 export interface DialogField {
 	get(): string;
@@ -3747,7 +3816,7 @@ export interface DialogField {
 }
 /** What a slot's `mount` is handed: which dialog, its payload, its fields, and a way to close it. */
 export interface DialogSlotHost {
-	readonly dialog: SlottedDialogId;
+	readonly dialog: DialogSlotId;
 	readonly payload: Readonly<Record<string, unknown>>;
 	readonly fields: Readonly<Record<string, DialogField>>;
 	close(): void;
@@ -3956,8 +4025,9 @@ export interface UiApi {
 	/**
 	 * Add to a built-in dialog. `mount` runs in a row at the left of the dialog's footer each
 	 * time that dialog opens, with the dialog's working-copy fields to read and fill
-	 * (`SlottedDialogId` lists which dialogs and fields). Returns the registration; it
-	 * leaves with `dispose()` or the plugin.
+	 * (`SlottedDialogId` lists which dialogs and fields) — or to another plugin's dialog,
+	 * by the id its `DialogSpec.slot` offers. Returns the registration; it leaves with
+	 * `dispose()` or the plugin.
 	 *
 	 * @example
 	 * api.ui.dialogSlot("mapProperties", {
@@ -3968,7 +4038,7 @@ export interface UiApi {
 	 *   },
 	 * });
 	 */
-	dialogSlot(dialog: SlottedDialogId, spec: DialogSlotSpec): Disposable;
+	dialogSlot(dialog: DialogSlotId, spec: DialogSlotSpec): Disposable;
 	/**
 	 * Take over the pointer on the map until `stop()`, Esc, a right-click, a map change
 	 * or another tool. One tool runs at a time — starting one stops the previous — and a
@@ -4510,7 +4580,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.16.0",
+  "version": "1.18.0",
   "description": "Type declarations for the scmJS plugin API",
   "license": "MIT",
   "types": "index.d.ts",