@tellegen/svelte 0.3.0 → 0.4.0

package/dist/controller.svelte.d.ts

@@ -1,7 +1,7 @@
 import { type TellegenApiClient } from './api.js';
 import type { BranchRatingDeltas, Network, NetworkBus, SensitivityColumn, Solution } from './api.js';
 import { CaseState, LocalCase, MulticonductorCase, type AppState, type DemandRangeMode, type SolvableCase } from './state.svelte.js';
-import { type EngineTransport, type McPfOptions, type McPfResult, type McStudySnapshot, type BrowserStudy, type Formulation, type PowerIoDiagnostic, type SensTarget } from '@tellegen/engine';
+import { type EngineTransport, type McPfDetail, type McPfDetailQuery, type McPfOptions, type McPfSummary, type McStudySnapshot, type BrowserStudy, type Formulation, type IngestedCase, type PowerIoDiagnostic, type SensTarget } from '@tellegen/engine';
 /** A parsed geographic sidecar awaiting application: the canonical `.geo.json`
  * layer document from the engine's tolerant reader, its source file name, and
  * the reader's notes on records it could not use. */
@@ -28,12 +28,40 @@ type DemandRangeAnchor = {
 };
 export interface ControllerOptions {
     api?: TellegenApiClient;
-    apiBase?: string;
+    /** Backend base path. `null` means there is no backend: no client is
+     * created and nothing is ever fetched. */
+    apiBase?: string | null;
+    /** Whether `load()` fetches the bundled cases. Default `true`. With
+     * `false`, `load()` only marks the shell loaded and frames the map. */
+    loadDefaultCases?: boolean;
     mcTransport?: Pick<EngineTransport, 'solveMcModule' | 'applyMcGeo'> & Partial<Pick<EngineTransport, 'solveMcStudy' | 'applyMcStudyGeo' | 'createMcPfSession'>>;
 }
+/** Input to `Controller.openBalancedModule` and `replaceLocalCase`: a
+ * balanced (transmission) powerio module, either as its JSON text or as the
+ * payload the engine's `ingestCase` already produced for it. */
+export interface OpenBalancedModuleInput {
+    /** Case label; also the stem of the `.pio.json` file name the shell shows. */
+    name: string;
+    /** Module JSON, ingested through the engine. Ignored when `payload` is set. */
+    moduleJson?: string;
+    /** An already ingested balanced payload; skips the engine round trip. */
+    payload?: IngestedCase;
+    /** A `.geo.json` layer document, for a module that carries no coordinates. */
+    geoLayer?: string;
+    /** Overrides the formulation the module declares. */
+    formulation?: Formulation;
+    /** Default `true`: add the case, make it active, and start its browser
+     * solve. With `false` the prepared case is returned and not added. */
+    activate?: boolean;
+    /** Default `true`: fly the map to the case when it is activated. */
+    frame?: boolean;
+}
 export declare class Controller {
     app: AppState;
-    api: TellegenApiClient;
+    /** `null` when the controller was created with `apiBase: null`; every
+     * server path then reports "compute off" instead of fetching. */
+    api: TellegenApiClient | null;
+    readonly loadDefaultCases: boolean;
     mcTransport: Pick<EngineTransport, 'solveMcModule' | 'applyMcGeo'> & Partial<Pick<EngineTransport, 'solveMcStudy' | 'applyMcStudyGeo' | 'createMcPfSession'>>;
     abort: AbortController | null;
     sensitivity429Until: number;
@@ -196,7 +224,11 @@ export declare class Controller {
     removeBackendCase: (c: CaseState, event?: MouseEvent) => Promise<void>;
     activateLocal: (c: LocalCase) => void;
     removeLocalCase: (c: LocalCase, event?: MouseEvent) => Promise<void>;
-    addAndActivateLocal: (c: LocalCase) => void;
+    /** Add a prepared local case, make it active, frame it (unless `frame` is
+     * false) and start its browser solve. */
+    addAndActivateLocal: (c: LocalCase, options?: {
+        frame?: boolean;
+    }) => void;
     placeLocalCase: (lon: number, lat: number) => Promise<void>;
     /** Write the case's on-screen layout into its network payload
      * (`Bus.location` with `synthetic` provenance — the engine also accepts
@@ -291,6 +323,9 @@ export declare class Controller {
      * the first matching PowerWorld display. A failed geographic join keeps the
      * parsed case and returns the user-facing placement error. */
     private prepareDroppedLocal;
+    /** A case that still has no geometry gets a connectivity layout as its
+     * diagram, so it can render and solve without a placement step. */
+    private placeTopologyAsDiagram;
     /** Retain diagram geometry separately from the electrical case's geographic data. */
     private fillFromDisplaySibling;
     setCaseDisplayMode: (c: LocalCase, mode: "geographic" | "diagram") => void;
@@ -304,10 +339,21 @@ export declare class Controller {
     /** Retain parsed electrical inputs and draw each declared coordinate space directly. */
     private addMultiCase;
     /** Compute terminal quantities only for the retained input and current case revision. */
-    solveMultiCase: (c: MulticonductorCase, options?: McPfOptions, signal?: AbortSignal) => Promise<McPfResult>;
+    solveMultiCase: (c: MulticonductorCase, options?: McPfOptions, signal?: AbortSignal) => Promise<McPfSummary>;
     /** Materialize the current retained operating point only when a portable
      * snapshot is actually needed (save/export/geography). */
     snapshotMultiCase: (c: MulticonductorCase) => Promise<McStudySnapshot>;
+    /** One bus's terminals and a page of equipment ports for the displayed
+     * operating point, from the live session or the stored full result. Null
+     * when the operating point changed before the page arrived. */
+    multiResultDetail: (c: MulticonductorCase, query: McPfDetailQuery) => Promise<McPfDetail | null>;
+    /** Every terminal's identity, voltage, and injected current, as numeric
+     * arrays of interleaved `[re, im]` values. */
+    multiTerminalTable: (c: MulticonductorCase) => Promise<{
+        ids: Array<[string, string]>;
+        voltages: Float64Array;
+        currents: Float64Array;
+    } | null>;
     /** Apply coordinates atomically to the explicitly selected conductor-resolved case. */
     applyMultiGeoLayers: (c: MulticonductorCase, layers: GeoLayerFile[]) => Promise<void>;
     /** Stage an absolute load-branch P/Q edit and coalesce rapid UI changes into
@@ -338,6 +384,20 @@ export declare class Controller {
     /** Build a local case from a balanced PowerIO ingest payload without activating
      * it yet; co-dropped placement data is applied before the first solve. */
     private localFromBalancedPayload;
+    /** Ingest module text through the engine and require a balanced network. */
+    private ingestBalancedModule;
+    /** Open a balanced powerio module from memory, the programmatic twin of
+     * dropping a `.pio.json` file: ingest (unless `payload` is given), apply an
+     * optional geographic layer, lay out a module without coordinates as a
+     * diagram, then add and activate it. Resolves to the new case; throws when
+     * the module is not a balanced network or the geographic layer matches
+     * nothing. */
+    openBalancedModule: (input: OpenBalancedModuleInput) => Promise<LocalCase>;
+    /** Swap a local case for a new module in place: same slot in the case list,
+     * same formulation unless `input.formulation` says otherwise, same display
+     * mode when the new case supports it, and the selected bus kept when the
+     * new case has it. The previous case's Study is freed. */
+    replaceLocalCase: (previous: LocalCase, input: OpenBalancedModuleInput) => Promise<LocalCase>;
     /** Build (or reuse) the case's Study and commit it at the current edit state, so a
      * save or export captures exactly what is on screen. Null (with an error set) when no
      * PowerIO module or Study is available. */