@punica/editor 1.0.6 → 1.0.7

package/types/punica.module.flow.shell.d.ts

@@ -0,0 +1,374 @@
+declare module 'punica' {
+  export namespace flow {
+    export namespace shell {
+      /**
+       * Flow node position in the canvas.
+       */
+      export interface FlowViewNodePosition {
+        id: string;
+        x: number;
+        y: number;
+      }
+
+      /**
+       * Flow node in the graph.
+       */
+      export interface FlowNode {
+        id: string;
+        position: { x: number; y: number };
+        label?: string;
+        data?: Record<string, unknown>;
+      }
+
+      /**
+       * Flow edge connecting two nodes.
+       */
+      export interface FlowEdge {
+        id: string;
+        source: string;
+        target: string;
+        sourceHandle?: string;
+        targetHandle?: string;
+        data?: Record<string, unknown>;
+      }
+
+      /**
+       * Complete flow graph with nodes, edges, and viewport.
+       */
+      export interface FlowGraph {
+        nodes: FlowNode[];
+        edges: FlowEdge[];
+        viewport?: FlowViewport;
+        metadata?: Record<string, unknown>;
+      }
+
+      export interface FlowViewSnapshot {
+        nodes: FlowViewNodePosition[];
+        viewport: FlowViewport;
+      }
+
+      export interface ViewportControllerOptions {
+        container: HTMLElement;
+        viewport?: FlowViewport;
+        minZoom?: number;
+        maxZoom?: number;
+        zoomStep?: number;
+        shouldStartPan?: (event: PointerEvent) => boolean;
+        onViewportChange?: (viewport: FlowViewport) => void;
+      }
+
+      /**
+       * Viewport state for pan/zoom.
+       */
+      export interface FlowViewport {
+        x: number;
+        y: number;
+        zoom: number;
+      }
+
+      /**
+       * Substrate-shipped contract for the viewport controller
+       * (flow shell renderer). Substrate used to ship a concrete
+       * `ViewportController` class; the constitutional decision (D1)
+       * moves DOM-bound implementation to extension territory. The
+       * substrate now ships the interface + a `FlowRendererProvider`
+       * injection seam — hosts/extensions implement the real DOM
+       * controller and inject it via `setRendererProvider(...)`.
+       */
+      export interface ViewportController {
+        attach(): void;
+        detach(): void;
+        getViewport(): FlowViewport;
+        setViewport(viewport: Partial<FlowViewport>): void;
+        registerDraggableNode(
+          id: string,
+          element: HTMLElement,
+          getPosition: () => { x: number; y: number },
+          setPosition: (pos: { x: number; y: number }) => void
+        ): void;
+        unregisterDraggableNode(id: string): void;
+      }
+
+      export interface ZoomControlOptions {
+        /**
+         * Container that hosts the main flow canvas. The zoom control will be
+         * rendered as an absolutely positioned overlay inside this container.
+         */
+        container: HTMLElement;
+        /**
+         * Optional position of the zoom control overlay. Defaults to 'bottom-right'.
+         */
+        position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+        /**
+         * Optional function to format the zoom value for display. Receives the
+         * current zoom factor (e.g. 1.0, 0.5, 2.0) and should return a string
+         * (e.g. "100%", "50%").
+         */
+        labelFormatter?: (zoom: number) => string;
+        /**
+         * Optional minimum and maximum zoom applied when interacting via the
+         * +/- buttons. If omitted, defaults to the same bounds as the default
+         * ViewportController (0.25 .. 3).
+         */
+        minZoom?: number;
+        maxZoom?: number;
+        /**
+         * Zoom step multiplier for +/- buttons. Defaults to 1.05.
+         */
+        zoomStep?: number;
+      }
+
+      export interface ZoomControlHandle {
+        /** Root DOM element that contains the zoom control UI. */
+        element: HTMLElement;
+        /**
+         * Updates the visual label based on the given viewport.
+         * Call this from your viewport change handler.
+         */
+        update(viewport: FlowViewport): void;
+        /** Removes all listeners and DOM nodes created by the control. */
+        dispose(): void;
+      }
+
+      /**
+       * Attaches a reusable zoom control ( - [zoom%] + ) to a flow canvas container.
+       * The control operates on the given ViewportController instance.
+       */
+      export function attachZoomControl(
+        controller: ViewportController,
+        options: ZoomControlOptions
+      ): ZoomControlHandle;
+
+      export interface MinimapNode {
+        id: string;
+        x: number;
+        y: number;
+      }
+
+      export interface MinimapOptions {
+        /**
+         * Container that hosts the main flow canvas. The minimap will be
+         * rendered as an absolutely positioned overlay inside this container.
+         */
+        container: HTMLElement;
+        /**
+         * Returns the current set of nodes that should be considered when
+         * computing the flow's bounding box in the minimap.
+         */
+        getNodes: () => MinimapNode[];
+        /**
+         * Optional position of the minimap overlay. Defaults to 'bottom-left'.
+         */
+        position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+      }
+
+      export interface MinimapHandle {
+        /** Root DOM element that contains the minimap UI. */
+        element: HTMLElement;
+        /**
+         * Recomputes and redraws the minimap based on the latest viewport
+         * and node positions. Call this from your viewport change handler.
+         */
+        update(viewport: FlowViewport): void;
+        /** Removes all listeners and DOM nodes created by the minimap. */
+        dispose(): void;
+      }
+
+      /**
+       * Attaches a reusable minimap overlay to a flow canvas container. The minimap
+       * visualises the bounding box of the flow graph and a neutral block that
+       * represents the current canvas transform. Users can click/tap on the minimap
+       * to re-centre the viewport around a given point.
+       */
+      export function attachMinimap(
+        controller: ViewportController,
+        options: MinimapOptions
+      ): MinimapHandle;
+
+      /**
+       * Merge a view snapshot (viewport + node positions) into an IPython notebook's
+       * metadata.ivy.view namespace, returning a new notebook object.
+       */
+      export function mergeViewSnapshotIntoNotebook(
+        notebook: import('punica').IPythonNotebook,
+        snapshot: FlowViewSnapshot
+      ): import('punica').IPythonNotebook;
+
+      /** Input node for the automatic layered layout (port counts drive the
+       * estimated card height used for overlap-free vertical stacking). */
+      export interface FlowLayoutNode {
+        id: string;
+        inputCount?: number;
+        outputCount?: number;
+      }
+
+      export interface FlowLayoutEdge {
+        source: string;
+        target: string;
+      }
+
+      export interface FlowLayoutOptions {
+        cardWidth?: number;
+        horizontalGap?: number;
+        verticalGap?: number;
+        marginX?: number;
+        marginY?: number;
+      }
+
+      /**
+       * Dependency-free deterministic layered (Sugiyama-lite) layout — the
+       * single choke point canvas adapters use when a document has no
+       * persisted view positions. Ranks by longest path from sources
+       * (left→right, matching port sides), reduces crossings with barycenter
+       * sweeps, stacks layers around a common midline. Cyclic graphs fall
+       * back to the legacy grid. Pure data utility (no DOM, D1-compliant).
+       * Exposed at `punica.flow.shell.computeFlowLayout`.
+       */
+      export function computeFlowLayout(
+        input: { nodes: FlowLayoutNode[]; edges: FlowLayoutEdge[] },
+        options?: FlowLayoutOptions
+      ): Record<string, { x: number; y: number }>;
+
+      /** Legacy 6-column grid position — the pre-layout fallback formula
+       * (single home; also used internally as the cycle fallback). */
+      export function gridFallbackPosition(index: number): {
+        x: number;
+        y: number;
+      };
+
+      /**
+       * Options for creating a flow canvas renderer.
+       */
+      export interface FlowRendererOptions {
+        /**
+         * Container element that will host the flow canvas.
+         */
+        container: HTMLElement;
+        /**
+         * Flow graph to render (nodes, edges, viewport).
+         */
+        graph: FlowGraph;
+        /**
+         * Optional node size configuration.
+         */
+        nodeSize?: { width: number };
+        /**
+         * Optional callback when viewport or node positions change.
+         */
+        onViewUpdate?: (snapshot: {
+          nodes: Array<{ id: string; x: number; y: number }>;
+          viewport: FlowViewport;
+        }) => void;
+        /**
+         * Optional callback when a node is selected.
+         */
+        onNodeSelect?: (
+          nodeId: string,
+          data: { label?: string; inputs?: unknown[]; outputs?: unknown[] }
+        ) => void;
+        /**
+         * Whether to attach zoom control widget. Defaults to true.
+         */
+        attachZoomControl?: boolean;
+        /**
+         * Whether to attach minimap widget. Defaults to true.
+         */
+        attachMinimap?: boolean;
+      }
+
+      /**
+       * Handle returned by createFlowRenderer for managing the renderer instance.
+       */
+      export interface FlowRendererHandle {
+        /**
+         * Update the graph being rendered.
+         */
+        updateGraph(graph: FlowGraph): void;
+        /**
+         * Get current viewport.
+         */
+        getViewport(): FlowViewport;
+        /**
+         * Set viewport.
+         */
+        setViewport(viewport: Partial<FlowViewport>): void;
+        /**
+         * Dispose the renderer and clean up all resources.
+         */
+        dispose(): void;
+      }
+
+      /**
+       * Creates a flow canvas renderer.
+       *
+       * This is the core renderer provider that extensions should use
+       * instead of implementing their own canvas rendering logic.
+       *
+       * @param options - Renderer configuration options
+       * @returns Handle for managing the renderer instance
+       */
+      export function createFlowRenderer(
+        options: FlowRendererOptions
+      ): FlowRendererHandle;
+
+      /**
+       * Substrate-shipped renderer provider contract (flow shell renderer).
+       *
+       * D1: substrate ships the interface; the DOM-bound renderer
+       * implementation lives in extension/host territory. Hosts
+       * inject a provider via `setRendererProvider(...)`; substrate
+       * `createFlowRenderer` / `attachZoomControl` / `attachMinimap`
+       * delegate through the active provider and throw loudly when
+       * none has been injected.
+       *
+       * Mirrors the data plane / FS providers `FileSystemProvider` pattern: substrate
+       * defines the contract, host owns the impl, substrate refuses
+       * to ship the DOM impl itself.
+       */
+      export interface FlowRendererProvider {
+        createRenderer(options: FlowRendererOptions): FlowRendererHandle;
+        createViewportController(
+          options: ViewportControllerOptions
+        ): ViewportController;
+        attachZoomControl(
+          controller: ViewportController,
+          options: ZoomControlOptions
+        ): ZoomControlHandle;
+        attachMinimap(
+          controller: ViewportController,
+          options: MinimapOptions
+        ): MinimapHandle;
+      }
+
+      /**
+       * Host-injection façade exposed at `punica.flow.shell.rendererProvider`.
+       * `undefined` until a host calls `setRendererProvider(...)` —
+       * substrate intentionally does NOT ship a default DOM impl
+       * (D1 + ApplicationProfile prep).
+       */
+      export const rendererProvider: FlowRendererProvider | undefined;
+
+      /**
+       * Install a host-provided renderer. Substrate validates the
+       * shape defensively and refuses incomplete providers — every
+       * factory method must be present so downstream `createFlowRenderer`
+       * / `attachZoomControl` / `attachMinimap` invocations cannot
+       * partially route through `undefined`.
+       */
+      export function setRendererProvider(provider: FlowRendererProvider): void;
+
+      /**
+       * Drop any installed renderer provider. Tests + hosts that
+       * disable rendering at runtime use this to restore the
+       * substrate's "no renderer injected" default.
+       */
+      export function resetRendererProvider(): void;
+    }
+  }
+
+  // Module-level exports for convenience
+  export type FlowNode = flow.shell.FlowNode;
+  export type FlowEdge = flow.shell.FlowEdge;
+  export type FlowGraph = flow.shell.FlowGraph;
+  export type FlowViewport = flow.shell.FlowViewport;
+}