@scm-js/plugin-api 1.12.0 → 1.14.0

package/index.d.ts

@@ -1638,6 +1638,8 @@ export interface DoodadPlacementOptions {
 	placeAnywhere: boolean;
 	/** Keep the left column on an even tile, as StarEdit always does. */
 	snapToGrid: boolean;
+	/** Place as plain terrain: the tiles (both sections) and any overlay sprite, no DD2 record — a placement and a conversion in one. */
+	asTerrain: boolean;
 }
 export interface DoodadVerdict {
 	ok: boolean;
@@ -2344,6 +2346,13 @@ export interface EditTransaction {
 	/** Stamp a doodad (a `dddata.bin` id) at a tile; returns its record index, or -1 when unknown or off the map. */
 	placeDoodad(doodadId: number, tx: number, ty: number, owner?: number): number;
 	removeDoodads(indices: number[]): number;
+	/**
+	 * Make doodads plain terrain: their records go, their tiles stay (in TILE as well as
+	 * MTXM, so the cells are ground to every tool from here on) and an overlay stays as an
+	 * ordinary sprite. The way to touch up a ramp or a cliff piece tile by tile.
+	 * Returns records converted.
+	 */
+	convertDoodads(indices: number[]): number;
 	/** 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;
@@ -4112,6 +4121,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
@@ -4156,6 +4238,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";
 /**

package/package.json

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