@scm-js/plugin-api 1.46.0 → 1.48.0

package/index.d.ts

@@ -38,9 +38,9 @@ export type CombineMode =
 "overlay"
 /** Every occurrence's records are kept, in file order. */
  | "append"
-/** Only the last occurrence is used. */
+/** Only the last occurrence is used — of those at least the section's minimum length. */
  | "last"
-/** Only the first occurrence is used. */
+/** Only the first occurrence is used — of those at least the section's minimum length. */
  | "first";
 /**
  * The byte encodings a map's text can be in, and how to tell which one a file used.
@@ -1466,6 +1466,8 @@ export interface SectionKnowledge {
 	size: number | null;
 	/** The record length of a list section, or null. */
 	stride: number | null;
+	/** The shortest copy the game takes, for a "last" or "first" section; shorter ones are passed over. Null when any length is taken. */
+	minimum: number | null;
 	/** Whether the editor decodes the section into its model and re-encodes it on save. */
 	modelled: boolean;
 }
@@ -4982,7 +4984,11 @@ 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. */
+	/**
+	 * Floating: a height in CSS pixels instead of the content's own; the body then scrolls, or
+	 * fills, as its content asks. Bottom dock: the strip's starting height (160 by default),
+	 * which the user can then drag.
+	 */
 	height?: number;
 	/**
 	 * Floating only: a grip at the bottom-right corner lets the user resize the panel, and
@@ -4997,9 +5003,11 @@ export interface PanelSpec {
 	 * 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.
+	 * panel in it. `"bottom"` puts it in a strip under the map, as wide as the map, which
+	 * the user makes taller or shorter by dragging its top edge — the place for a timeline,
+	 * a console or anything read along the width of the map. Several bottom panels stack.
 	 */
-	dock?: "float" | "right";
+	dock?: "float" | "right" | "bottom";
 	/** A docked panel that takes the dock's spare height (a transcript, a long list); off by default. */
 	grow?: boolean;
 	/** Floating only: the body runs edge to edge, without the panel's padding — for content that draws its own frame. */
@@ -5009,6 +5017,51 @@ export interface PanelSpec {
 	/** The panel closed, whichever way. */
 	onClose?: () => void;
 }
+/**
+ * A kind of file a plugin opens (`ui.fileType`): replays, a mod's own data. A file whose
+ * name ends in one of `extensions`, dropped on the editor or picked in File ▸ Open, goes
+ * to `open` instead of being read as a map. Several dropped at once arrive together.
+ */
+export interface FileTypeSpec {
+	/** What the files are, for File ▸ Open's list of types ("StarCraft replay"). */
+	name: string;
+	/** With the dot, any case: `[".rep"]`. */
+	extensions: string[];
+	open(files: File[]): void | Promise<void>;
+}
+/**
+ * Another way to look at a map, shown where the map is drawn (`ui.mapView`): a replay's
+ * game played out, a 3D view, a picture of something else entirely. The editor gives the
+ * view one element for its whole life and never moves it — an iframe in it is not loaded
+ * again when the view is hidden and shown — and lays it over the map, rulers and all.
+ */
+export interface MapViewSpec {
+	/** What the switch over the map calls it ("Game"). The map itself is "Map". */
+	title: string;
+	/**
+	 * Called once, with the element the view lives in. Fill it as you like; it is as large as
+	 * the map's area and in the page from the first time the view is shown. Return a function
+	 * to be called when the view goes (the plugin stops, or `dispose`).
+	 */
+	mount(element: HTMLElement): void | (() => void);
+}
+export interface MapViewHandle extends Disposable {
+	/**
+	 * Offer the view on a map (by `OpenDocumentInfo.id`; the one in front when left out), or
+	 * stop offering it there. A map that offers views has a switch over it, the map's own
+	 * view first. Nothing is offered until you say so.
+	 */
+	offer(on: boolean, documentId?: number): void;
+	/** Show the view in that map's place (offering it there if it was not), or the map again. */
+	show(on: boolean, documentId?: number): void;
+	/** Whether the view is what the map in front shows now. */
+	isShown(): boolean;
+	/**
+	 * Whether the view is shown changed for the map in front: the person used the switch,
+	 * `show` was called, or another map came to the front.
+	 */
+	onChange(listener: (shown: boolean) => void): Disposable;
+}
 export interface PanelHandle {
 	close(): void;
 	isOpen(): boolean;
@@ -5375,10 +5428,31 @@ export interface UiApi {
 	} | null>;
 	dialog(spec: DialogSpec): DialogHandle;
 	/**
-	 * 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.
+	 * Open a panel: floating over the map, docked at the right with the built-in panels, or
+	 * in the strip under the map (`spec.dock`). As many as you like; each closes with the plugin.
 	 */
 	panel(spec: PanelSpec): PanelHandle;
+	/**
+	 * Claim a kind of file: dropped on the editor or picked in File ▸ Open, a file with one of
+	 * `spec.extensions` is handed to `spec.open` instead of being opened as a map. A plugin
+	 * that claims what another already has is not given it (the first stays); none can claim
+	 * the editor's own `.scm`, `.scx` or `.chk`. Ends with the plugin, or with `dispose`.
+	 *
+	 * @example
+	 * api.ui.fileType({ name: "StarCraft replay", extensions: [".rep"], open: (files) => loadReplays(files) });
+	 */
+	fileType(spec: FileTypeSpec): Disposable;
+	/**
+	 * Another way to look at the maps you choose, in the map's place, with a switch over the
+	 * map between it and the map itself (see `MapViewSpec`). A map shows one view at a time;
+	 * each map keeps the one it was left on. Ends with the plugin, or with `dispose`.
+	 *
+	 * @example
+	 * const game = api.ui.mapView({ title: "Game", mount: (el) => { el.append(frame); } });
+	 * // A map just opened is the one in front.
+	 * if (await api.document.open(map, "replay.scx", { viewOnly: { label: "Replay" } })) game.show(true);
+	 */
+	mapView(spec: MapViewSpec): MapViewHandle;
 	/**
 	 * 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

package/package.json

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