@mudlet/mudlet-web 0.3.0 → 0.4.0

package/dist-lib/scripting/MxpFrameManager.d.ts

@@ -0,0 +1,118 @@
+/**
+ * MXP `<FRAME>` window layout — a port of Mudlet 4.21's `TMxpFrameManager`
+ * (src/TMxpFrameManager.cpp).
+ *
+ * MXP lets a server carve the client window into named sub-windows and then
+ * redirect text into them with `<DEST>`. Mudlet lays those out itself rather
+ * than handing them to the OS window manager: internal frames are tiled against
+ * the edges of the main console, each one shrinking the console's usable area
+ * by adding to a set of "MXP borders", and frames declared inside an open
+ * `<DEST>` nest inside that destination frame instead. `TITLE` gives a frame a
+ * tab header, and `DOCK`+`ALIGN=CLIENT` (a CMUD extension, not MXP 1.0) adds a
+ * frame as another tab of an existing one.
+ *
+ * This class owns the same bookkeeping — the frame records, the accumulated
+ * borders, the parent/child hierarchy and the tab groups — and drives the UI
+ * through {@link MxpFrameHost} so the geometry is testable without a DOM.
+ * mudix maps a frame's console onto a mini-console (an overlay panel with
+ * script-controlled geometry); the tab strip is window chrome rendered by
+ * ScriptWindow, and child frames nest by portalling into the parent panel's
+ * viewport, so their coordinates are parent-relative.
+ */
+import type { MxpTabPage } from '../ui/windows/types';
+/** Height in px of a frame's tab strip. Must match `.mxp-frame-tabs` in ScriptWindow.css. */
+export declare const MXP_TAB_BAR_HEIGHT = 24;
+/** Pixel insets carved out of the main console by edge-aligned frames. */
+export interface MxpBorders {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/** Rectangle, in main-viewport coordinates, that top-level frames tile inside. */
+export interface MxpArea {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Everything the layout needs from the app. Implemented by ScriptingAPI. */
+export interface MxpFrameHost {
+    /** The region top-level frames may tile in: the main window minus whatever
+     *  `setBorder*` has reserved. A GUI package that docks itself to an edge
+     *  (Geyser's `Adjustable.Container{attached=…}`) reserves its strip that
+     *  way, and a server laying out frames must not tile over it. MXP's own
+     *  borders are excluded — the manager tracks those itself. */
+    consoleArea(): MxpArea;
+    /** Character cell `[width, height]` in px for the main output font, backing `Nc` sizes. */
+    charCellSize(): [number, number];
+    /** Create (or reposition) a frame's console. `parent` nests it inside that
+     *  frame's viewport, making x/y parent-relative. */
+    placeFrameConsole(name: string, x: number, y: number, width: number, height: number, parent?: string): void;
+    /** Open an `EXTERNAL` frame as a free-floating window with its own titlebar. */
+    openExternalFrame(name: string, title: string, width: number, height: number): void;
+    destroyFrameConsole(name: string): void;
+    showFrameConsole(name: string): void;
+    raiseFrameConsole(name: string): void;
+    setFrameScrolling(name: string, enabled: boolean): void;
+    /** Install/replace a frame's tab strip. An empty `pages` list removes it. */
+    setFrameTabs(name: string, pages: MxpTabPage[], active: string): void;
+    /** Publish the accumulated borders so the main console shrinks around the frames. */
+    setMxpBorders(borders: MxpBorders): void;
+}
+export declare class MxpFrameManager {
+    private readonly host;
+    private readonly frames;
+    private borders;
+    constructor(host: MxpFrameHost);
+    /**
+     * `<FRAME name …>`. `dest` is the `<DEST>` frame open at the time the tag
+     * was parsed, which nests this frame inside it. Returns false when the tag
+     * could not be honoured (bad name, frame budget exhausted) — Mudlet renders
+     * the raw tag text in that case.
+     */
+    createFrame(name: string, attrs: Record<string, string>, dest?: string): boolean;
+    /** `ACTION=close`. Closing an unknown frame succeeds — it is already closed,
+     *  and reporting failure would leak the raw tag into the output. */
+    closeFrame(name: string): boolean;
+    /** `ACTION=focus` — raise an existing frame. False when there is none. */
+    focusFrame(name: string): boolean;
+    /** `ACTION=open` on a frame that already exists: show and raise, no re-layout. */
+    showFrame(name: string): boolean;
+    /** MXP frames do not survive a reconnect — Mudlet's `resetAllFrames`. */
+    resetAllFrames(): void;
+    has(name: string): boolean;
+    frameNames(): string[];
+    /** Current MXP borders. Exposed for tests and for the initial UI read. */
+    getBorders(): MxpBorders;
+    /**
+     * The common case: a frame tiled against an edge of the main console, or —
+     * when declared inside an open `<DEST>` — stacked inside that frame.
+     */
+    private layoutInternalFrame;
+    /** `EXTERNAL` — a window of its own. The browser has no OS child windows,
+     *  so this becomes a free-floating panel with a real titlebar. */
+    private layoutExternalFrame;
+    /** `DOCK=other ALIGN=CLIENT` — join `other`'s tab strip as another page. */
+    private layoutTabFrame;
+    /** Usable area inside a frame, i.e. its rect minus its own tab strip. */
+    private contentSize;
+    /** Push a frame's strip to the UI. `active` switches the visible page;
+     *  omitting it keeps whichever page is showing, so a tab arriving or closing
+     *  never yanks the reader off the one they were watching. */
+    private publishTabs;
+    /** Bring `name` to the front of whichever tab strip holds it, if any. */
+    private selectTabFor;
+    /**
+     * `WIDTH`/`HEIGHT`/`LEFT`/`TOP` accept `40c` (character cells), `25%` of the
+     * container, or `350px`/`350` (pixels). Anything unparseable is 0, matching
+     * Mudlet — the caller's minimums then take over.
+     */
+    private calcSize;
+    /**
+     * Rebuild the borders from the frames that are left. Called after a close so
+     * the main console reclaims the space; surviving frames keep the geometry
+     * they were given (Mudlet does not re-tile them either).
+     */
+    private recalculateBorders;
+}