@scm-js/plugin-api 1.45.0 → 1.47.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;
 }
@@ -2565,6 +2567,8 @@ export interface DocumentInfo {
 	version: number;
 	fileName: string | null;
 	modified: boolean;
+	/** Open to look at only (`OpenDocumentOptions.viewOnly`): every write throws and it is never saved. */
+	viewOnly: boolean;
 }
 /** What one `document.edit` changed, per list. */
 export interface EditResult {
@@ -2741,6 +2745,20 @@ export interface ResizeDocumentOptions {
 export type OpenInto = "new" | "current";
 export interface OpenDocumentOptions {
 	into?: OpenInto;
+	/**
+	 * Open the map to look at, not to change — a replay's map, a preview. It always opens
+	 * beside the open map (`into` is ignored), so nothing is replaced and nothing is asked.
+	 * Panning, zooming, the layers and selecting work; every tool, menu and dialog that
+	 * would change it is off, and every write throws — `edit`, `update`, `sections` (except
+	 * `replaceFile(…, { asOpened: true })`, a reading of the file rather than an edit), `resize`,
+	 * `changeTileset`, `extras`, the clipboard's `cut` and `paste`, `save` and `saveAs` unless
+	 * as a copy, `sync.start`. It is never kept in Open Recent, and closing it asks nothing. File ▸ Edit a Copy
+	 * opens an ordinary copy. `label` is what the tab and the status bar call it ("Replay");
+	 * `true` is the plain "View only".
+	 */
+	viewOnly?: boolean | {
+		label?: string;
+	};
 }
 /** One open map, as `document.list()` reports it. `active` marks the one in front — the one every other call reads and writes. */
 export interface OpenDocumentInfo {
@@ -2754,6 +2772,8 @@ export interface OpenDocumentInfo {
 	height: number;
 	modified: boolean;
 	active: boolean;
+	/** Open to look at only; see `OpenDocumentOptions.viewOnly`. */
+	viewOnly: boolean;
 }
 /** File ▸ New's form: size, tileset, and the two strings the dialog asks for. */
 export interface NewDocumentOptions {
@@ -2869,11 +2889,14 @@ export interface DocumentApi {
 	 * In place of a map with unsaved changes, when Preferences say to ask, the Close
 	 * Scenario dialog comes first and the user may cancel. Resolves true once the file is
 	 * the map in front, false when the user kept the current map or the file could not be
-	 * read (the status bar says why).
+	 * read (the status bar says why). `options.viewOnly` opens it to look at only.
 	 *
 	 * @example
 	 * const [file] = await api.ui.pickFiles({ accept: ".scx,.scm,.chk" });
 	 * if (file) await api.document.open(file, file.name, { into: "new" });
+	 * @example
+	 * // A replay's map, to draw over and not to change.
+	 * await api.document.open(chk, "Lost Temple.scx", { viewOnly: { label: "Replay" } });
 	 */
 	open(file: File | Blob | Uint8Array, fileName?: string, options?: OpenDocumentOptions): Promise<boolean>;
 	/**
@@ -4961,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
@@ -4976,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. */
@@ -4988,6 +5017,18 @@ 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>;
+}
 export interface PanelHandle {
 	close(): void;
 	isOpen(): boolean;
@@ -5354,10 +5395,20 @@ 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;
 	/**
 	 * 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.45.0",
+  "version": "1.47.0",
   "description": "Type declarations for the scmJS plugin API",
   "license": "MIT",
   "types": "index.d.ts",