@scm-js/plugin-api 1.5.0 → 1.7.0

package/index.d.ts

@@ -2745,6 +2745,16 @@ export interface ViewApi {
 	/** Grid spacing in map pixels (32 = one tile). */
 	gridSize(): number;
 	setGridSize(size: 8 | 16 | 32 | 64 | 128): void;
+	/**
+	 * Highlight something on the map for a moment: the rect an edit filled, the units it
+	 * placed, the location it moved. Fades by itself; several may run at once. Nothing to
+	 * clean up.
+	 *
+	 * @example
+	 * const r = api.document.edit("Fill", (tx) => tx.fillFlat(rect, terrain));
+	 * if (r.changed) api.view.flash({ rect });
+	 */
+	flash(target: FlashTarget): void;
 }
 export interface CommandSpec {
 	/**
@@ -3447,6 +3457,13 @@ export interface DialogHandle {
 	isOpen(): boolean;
 	/** Change the title strip's text. */
 	setTitle(title: string): void;
+	/**
+	 * Say the dialog is working: a ring and `label` at the left of the footer, and every
+	 * footer button disabled until `setBusy(false)`. A button's own `run` already does this
+	 * for as long as its promise is pending — this is for work the buttons did not start,
+	 * such as the first load, or a search that runs as the user types.
+	 */
+	setBusy(label: string | false): void;
 }
 /**
  * A panel floats over the map and does not block it: the user keeps drawing, scrolling
@@ -3455,8 +3472,19 @@ export interface DialogHandle {
  */
 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. */
+	/** 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;
+	/**
+	 * 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
+	 * and Properties, with the same head and hide button the built-in panels have — the
+	 * choice for anything the user keeps open while working, such as an assistant or a
+	 * readout. A docked panel shows the dock even when the user has hidden every built-in
+	 * panel in it.
+	 */
+	dock?: "float" | "right";
+	/** A docked panel that takes the dock's spare height (a transcript, a long list); off by default. */
+	grow?: boolean;
 	/** Fill `body` (an empty `<div>` inside the panel); return a cleanup if you need one. */
 	mount(body: HTMLElement, panel: PanelHandle): void | (() => void);
 	/** The panel closed, whichever way. */
@@ -3467,6 +3495,85 @@ export interface PanelHandle {
 	isOpen(): boolean;
 	setTitle(title: string): void;
 }
+/**
+ * One cell in the status bar (`ui.statusItem`): a line of text with the plugin's icon,
+ * a spinner while `busy`, and a click. It is how a plugin that works in the background
+ * stays visible without a panel — "AI · working 12 s", "3 problems", "Synced".
+ */
+export interface StatusItemSpec {
+	text: string;
+	/** The tooltip. */
+	title?: string;
+	/** Show a spinner in the cell. */
+	busy?: boolean;
+	/** Paint the cell as a warning. */
+	warn?: boolean;
+	onClick?: () => void;
+}
+export interface StatusItemHandle {
+	/** Change any of the fields; the cell redraws. */
+	set(patch: Partial<StatusItemSpec>): void;
+	remove(): void;
+	isShown(): boolean;
+}
+/**
+ * The dialogs a plugin may add to (`ui.dialogSlot`), and the fields each one exposes to
+ * the slot. A field is the dialog's *working copy* — what the person sees in the form,
+ * 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.
+ */
+export type SlottedDialogId = "mapProperties" | "textTriggerEditor" | "triggerEditor" | "stringEditor" | "playerSettings" | "missionBriefing";
+/** A form field a dialog lends to a slot: read it, set it, hear it change. */
+export interface DialogField {
+	get(): string;
+	set(value: string): void;
+}
+/** 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 payload: Readonly<Record<string, unknown>>;
+	readonly fields: Readonly<Record<string, DialogField>>;
+	close(): void;
+}
+/**
+ * Something a plugin mounts *inside* a built-in dialog — a button in Map Properties
+ * that suggests a name, one in the Text Trigger Editor that explains the text. The slot
+ * is a row at the left of the dialog's footer; fill it with the widgets, and it looks like
+ * part of the dialog. `mount` runs every time the dialog opens, with a cleanup on close.
+ */
+export interface DialogSlotSpec {
+	mount(body: HTMLElement, host: DialogSlotHost): void | (() => void);
+}
+/**
+ * What `view.flash` highlights: a tile rect, or units / locations by index. The
+ * highlight fades over `ms` (600 by default) and never blocks or takes the pointer; it is
+ * the shared way to say "this just changed" or "look here", so every plugin's flash looks
+ * the same. `kind` picks the colour: `"change"` (gold, the default) or `"attention"` (teal).
+ */
+export type FlashTarget = {
+	rect: Rect;
+	kind?: FlashKind;
+	ms?: number;
+} | {
+	units: number[];
+	kind?: FlashKind;
+	ms?: number;
+} | {
+	locations: number[];
+	kind?: FlashKind;
+	ms?: number;
+} | {
+	tiles: {
+		x: number;
+		y: number;
+	}[];
+	kind?: FlashKind;
+	ms?: number;
+};
+export type FlashKind = "change" | "attention";
 /** The pointer over the map, in the map's own units. A tile is 32 × 32 pixels. */
 export interface MapPointer {
 	/** Map pixels. Kept inside the map while a button is held, as the built-in brushes do. */
@@ -3610,8 +3717,33 @@ export interface UiApi {
 		fileName: string;
 	} | null>;
 	dialog(spec: DialogSpec): DialogHandle;
-	/** Open a floating panel over the map. As many as you like; each closes with the plugin. */
+	/**
+	 * Open a panel: floating over the map, or docked at the right with the built-in panels
+	 * (`spec.dock`). As many as you like; each closes with the plugin.
+	 */
 	panel(spec: PanelSpec): PanelHandle;
+	/**
+	 * A cell of your own in the status bar. One line of text beside the plugin's icon, a
+	 * spinner while `busy`, a click. Keep the handle and `set` it as things move; it
+	 * leaves with `remove()` or the plugin.
+	 */
+	statusItem(spec: StatusItemSpec): StatusItemHandle;
+	/**
+	 * 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.
+	 *
+	 * @example
+	 * api.ui.dialogSlot("mapProperties", {
+	 *   mount(body, dlg) {
+	 *     body.append(api.ui.widgets.button("Suggest a name", { onClick: async () => {
+	 *       dlg.fields.name.set(await suggestName(dlg.fields.description.get()));
+	 *     } }));
+	 *   },
+	 * });
+	 */
+	dialogSlot(dialog: SlottedDialogId, 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
@@ -3719,8 +3851,18 @@ export interface ButtonOptions extends WidgetOptions {
 	primary?: boolean;
 	danger?: boolean;
 	ghost?: boolean;
+	/** Start off waiting: a ring in front of the label, and the button disabled. */
+	busy?: boolean;
 	onClick?: (event: MouseEvent) => void;
 }
+/** The `<button>`, with the one call that puts it in and out of its waiting state. */
+export type ButtonElement = HTMLButtonElement & {
+	/**
+	 * A ring in front of the label while `busy`, and the button disabled — so the press
+	 * that started the work cannot be repeated, and says why it cannot.
+	 */
+	setBusy(busy: boolean): void;
+};
 export interface CheckboxOptions extends WidgetOptions {
 	value?: boolean;
 	/** A radio button instead; give the group a `name`. */
@@ -3775,13 +3917,80 @@ export interface ListOptions<T> {
 	className?: string;
 	onPick?: (value: T, index: number) => void;
 }
+export interface SpinnerOptions extends WidgetOptions {
+	/** `"sm"` 10px, `"md"` 14px (the default), `"lg"` 20px. */
+	size?: "sm" | "md" | "lg";
+	/** Text beside the ring. Without it you get the bare ring, to put beside your own. */
+	label?: string;
+}
+export interface ProgressBarOptions extends WidgetOptions {
+	/** How far along to start: 0…1, or null (the default) for the sliding bar that means "no idea how long". */
+	value?: number | null;
+	/** A line under the bar — what is being waited for, or how much of it is done. */
+	label?: string;
+	/** The percentage at the end of the bar; on for a bar that knows how far along it is. */
+	percent?: boolean;
+	/** Width in CSS pixels; it fills the width it is given by default. */
+	width?: number;
+}
+export type ProgressBarElement = HTMLElement & {
+	/**
+	 * How far along: 0…1, or null for the sliding bar. `label` replaces the line under it.
+	 * Cheap to call often — it repaints only when the bar actually moves.
+	 */
+	set(value: number | null, label?: string): void;
+};
+export interface StatusLineOptions extends WidgetOptions {
+	/** What it says before anything has happened. */
+	text?: string;
+}
+/**
+ * The line along the bottom of a dialog: what happened, what is happening, how far
+ * along it is, and the Cancel that stops it — in one place, so a dialog has one voice.
+ * It is a live region, so a screen reader hears the outcome (but not every byte of a
+ * download: the bar's own movement is not announced).
+ */
+export type StatusLineElement = HTMLElement & {
+	/** A finished line. `kind` colours it; nothing means plain. */
+	set(text: string, kind?: "ok" | "warn" | "error"): void;
+	/** Waiting, with no idea how long: a ring and the text. */
+	busy(text: string): void;
+	/** Waiting with a share done (0…1), or null for the sliding bar. */
+	progress(text: string, value: number | null): void;
+	/** A Cancel beside the line that calls `stop`; null takes it away. */
+	cancel(stop: (() => void) | null): void;
+	/** Back to an empty line. */
+	clear(): void;
+};
+export interface SkeletonOptions extends WidgetOptions {
+	/** CSS width, `"100%"` by default. */
+	width?: string;
+	/** Height in CSS pixels: 10 for a line, 44 for a block. */
+	height?: number;
+	/** How many lines, stacked; 1 by default. The last is drawn short, as text ends short. */
+	lines?: number;
+	/** A block — the place a thumbnail or a picture will take — rather than a line of text. */
+	block?: boolean;
+}
+export interface BusyOptions {
+	/** What is being waited for, over the covered box. */
+	label?: string;
+	/** Dim what is already there rather than leaving it at full strength; true by default. */
+	dim?: boolean;
+}
+export interface BusyHandle {
+	/** Change the label without lifting the cover. */
+	set(label: string): void;
+	/** Uncover the box. Safe to call twice. */
+	done(): 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
  * anything they do not cover.
  */
 export interface WidgetsApi {
-	button(label: string, options?: ButtonOptions): HTMLButtonElement;
+	button(label: string, options?: ButtonOptions): ButtonElement;
 	checkbox(label: string, options?: CheckboxOptions): CheckboxElement;
 	text(options?: TextFieldOptions): HTMLInputElement;
 	number(options?: NumberFieldOptions): HTMLInputElement;
@@ -3796,6 +4005,29 @@ export interface WidgetsApi {
 	hint(text: string): HTMLElement;
 	separator(): HTMLElement;
 	list<T>(items: ListItem<T>[], options?: ListOptions<T>): HTMLElement;
+	/** A turning ring: on its own to put beside your own text, or with a `label` beside it. */
+	spinner(options?: SpinnerOptions): HTMLElement;
+	/**
+	 * A bar, with the percentage and a line under it. `set(0…1)` moves it; `set(null)`
+	 * gives the sliding bar for work whose length is not known. Use it where the wait has
+	 * a size — a download, a pass over every trigger — and a spinner where it does not.
+	 */
+	progressBar(options?: ProgressBarOptions): ProgressBarElement;
+	/** The dialog's bottom line: `set`, `busy`, `progress` and a `cancel` button. */
+	statusLine(options?: StatusLineOptions): StatusLineElement;
+	/**
+	 * A grey stand-in for content that has not arrived, in the shape it will take. Rows of
+	 * these in the list you are about to fill say more than an empty box does, and the list
+	 * does not jump when the answer lands.
+	 */
+	skeleton(options?: SkeletonOptions): HTMLElement;
+	/**
+	 * Cover a box while what is in it is being replaced: dimmed, deaf to clicks, with a
+	 * ring and a label over it. `done()` uncovers it. Give it the box, not the page — the
+	 * search field that starts the work should stay live so the user can change their mind.
+	 * Calling it again on a covered box only changes the label.
+	 */
+	busy(target: HTMLElement, options?: BusyOptions | string): BusyHandle;
 }
 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.5.0",
+  "version": "1.7.0",
   "description": "Type declarations for the scmJS plugin API",
   "license": "MIT",
   "types": "index.d.ts",