@tumaet/apollon 4.8.0 → 4.9.0

package/dist/index.d.ts

@@ -1,8 +1,10 @@
+import { CSSProperties } from 'react';
 import { Edge } from '@xyflow/react';
 import { EdgeProps } from '@xyflow/react';
 import { JSX } from 'react';
 import { Node as Node_2 } from '@xyflow/react';
 import { NodeProps } from '@xyflow/react';
+import { ReactNode } from 'react';
 import { XYPosition } from '@xyflow/react';
 
 declare function Activity({ id, width, height, data, parentId, }: NodeProps<Node_2<DefaultNodeProps>>): JSX.Element | null;
@@ -21,6 +23,21 @@ declare function ActivityMergeNode({ id, width, height, data, parentId, }: NodeP
 
 declare function ActivityObjectNode({ id, width, height, data, parentId, }: NodeProps<Node_2<DefaultNodeProps>>): JSX.Element | null;
 
+declare function ActivitySwimlane({ id, width, height, data, parentId, }: NodeProps<Node_2<ActivitySwimlaneProps>>): JSX.Element | null;
+
+/**
+ * Activity-partition (swimlane) container. Lanes are equal divisions along the
+ * primary axis (columns when vertical, rows when horizontal). Elements dropped
+ * into the swimlane become its children and move with it; which lane an element
+ * belongs to is expressed by where the modeller places it, matching the UML
+ * activity-partition notation where partition membership is positional rather
+ * than stored per element.
+ */
+declare type ActivitySwimlaneProps = DefaultNodeProps & {
+    orientation: "vertical" | "horizontal";
+    lanes: SwimlaneLane[];
+};
+
 declare namespace Apollon {
     export {
         UMLDiagramType,
@@ -82,8 +99,8 @@ export declare class ApollonEditor {
     private readonly metadataStore;
     private readonly popoverStore;
     private readonly assessmentSelectionStore;
-    private readonly alignmentGuidesStore;
-    private readonly edgeGeometryStore;
+    private readonly overlayStore;
+    private readonly hostRegionEls;
     private subscribers;
     constructor(element: HTMLElement, options?: Apollon.ApollonOptions);
     private setReactFlowInstance;
@@ -102,10 +119,62 @@ export declare class ApollonEditor {
         x: number;
         y: number;
     }): XYPosition | null;
+    /**
+     * Zoom/pan so the whole diagram fits, capped at `maxZoom: 1.0`. Retries up to
+     * 10 animation frames until every node is measured.
+     * @param options.padding - Scalar fraction (default `0.15`), or per-side px
+     *   that adds to a 16px gutter. A per-side object forces the inset-aware path.
+     * @param options.duration - Animation duration in ms (default `200`).
+     * @param options.respectInsets - Pad the fit by reserved overlay insets
+     *   (header, rails, …). Default `true`.
+     */
     fitView(options?: {
-        padding?: number;
+        padding?: number | Partial<Record<OverlaySide, number>>;
         duration?: number;
+        /** Pad the fit by the reserved overlay insets (header, rails, …). */
+        respectInsets?: boolean;
     }): void;
+    /**
+     * Register a floating control, returning a disposer. Re-using an id replaces
+     * (idempotent / StrictMode-safe). Pick a façade: a React host →
+     * `<ApollonControl>`; a non-React host (or one that needs its own React
+     * root/context) → `getRegionElement` + `createPortal`; a one-off imperative
+     * widget → `addControl`.
+     * @param control - id, target region, a `render` thunk, and optional layout
+     *   options ({@link OverlayControlInput}).
+     * @returns A disposer that unregisters this control; safe to call twice.
+     * @throws If `id` is empty or `region` is not a known region — mistakes fail
+     *   loudly at the edge, not silently in the renderer.
+     */
+    addControl(control: OverlayControlInput): () => void;
+    /**
+     * Patch a registered control's options/renderer (a no-op if absent).
+     * @param id - The control's immutable id (an `id` in `patch` is ignored).
+     * @param patch - Partial options/renderer merged over the existing control.
+     */
+    updateControl(id: string, patch: Partial<OverlayControlInput>): void;
+    /**
+     * @param id - A control id.
+     * @returns `true` if a control with this id is currently registered.
+     */
+    hasControl(id: string): boolean;
+    /**
+     * A stable DOM node anchored in `region`, for hosts that render their own
+     * React into it (via `createPortal`) to keep host context. Auto-measured, so
+     * the diagram makes room for whatever the host mounts. Lifetime = the editor;
+     * `releaseRegionElement` unregisters it. Reserved id: `apollon:host:<region>`.
+     * @param region - The region to anchor the node in.
+     * @returns The same node for the lifetime of one acquire; `releaseRegionElement`
+     *   drops it and the next call returns a fresh node.
+     * @throws If `region` is not a known region.
+     */
+    getRegionElement(region: OverlayRegion): HTMLElement;
+    /**
+     * Release a region acquired via {@link getRegionElement} (unregister + drop
+     * the cached node); a later `getRegionElement(region)` creates a fresh node.
+     * @param region - The region whose host node to release.
+     */
+    releaseRegionElement(region: OverlayRegion): void;
     set diagramType(type: UMLDiagramType);
     destroy(): void;
     /** Renders a model to SVG via a hidden, off-screen mount. */
@@ -529,6 +598,7 @@ declare const diagramNodeTypes: {
     activityMergeNode: typeof ActivityMergeNode;
     activityForkNode: typeof ActivityForkNode;
     activityForkNodeHorizontal: typeof ActivityForkNodeHorizontal;
+    activitySwimlane: typeof ActivitySwimlane;
     useCase: typeof UseCase;
     useCaseActor: typeof UseCaseActor;
     useCaseSystem: typeof UseCaseSystem;
@@ -653,6 +723,14 @@ export declare const getNodeAssessmentDataByNodeElementId: (nodeElementId: strin
  */
 export declare function importDiagram(data: any | V3UMLModel): UMLModel;
 
+/**
+ * How much room a control reserves so the diagram "makes way" (fed into
+ * `fitView` padding, MapLibre-style). `"auto"` measures the control via the
+ * shared ResizeObserver on the region's dominant axis; an object mixes explicit
+ * px with per-side `"auto"` (e.g. `{ top: "auto" }`).
+ */
+export declare type InsetContribution = "auto" | Partial<Record<OverlaySide, number | "auto">>;
+
 export declare type InteractiveElements = {
     elements: {
         [id: string]: boolean;
@@ -703,6 +781,43 @@ export declare interface OrthogonalEdgeData {
     points: IPoint_2[];
 }
 
+/** The public registration payload (options + renderer). */
+export declare type OverlayControlInput = OverlayControlOptions & {
+    render: () => ReactNode;
+};
+
+export declare interface OverlayControlOptions {
+    /** Stable id. Re-adding the same id REPLACES (idempotent, StrictMode-safe). */
+    id: string;
+    /** Which band/corner the control is anchored in. */
+    region: OverlayRegion;
+    /** Reserve viewport room. Default: reserves nothing (the control floats). */
+    inset?: InsetContribution;
+    /** Stacking within a region; lower renders toward the region's anchor edge. */
+    order?: number;
+    /** When false the region frame stays pointer-transparent here too. Default true. */
+    interactive?: boolean;
+    /** Wraps the control in a `role="group"` with this aria-label. No focus
+     *  management is imposed. */
+    groupLabel?: string;
+    /** Hide without unregistering (reserves no inset while hidden). Default true. */
+    visible?: boolean;
+    /** Extra class on the control's wrapper element. */
+    className?: string;
+    /** Inline styles merged onto the control's wrapper element. */
+    style?: CSSProperties;
+}
+
+/**
+ * Where a control is anchored. The six React Flow `<Panel>` corners are
+ * screen-space and rendered through React Flow; `header`/`left-rail`/`right-rail`
+ * are library-owned bands; `on-canvas` pans/zooms with the diagram.
+ */
+export declare type OverlayRegion = "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right" | "header" | "left-rail" | "right-rail" | "on-canvas";
+
+/** One of the four edges a control can sit against / reserve room on. */
+export declare type OverlaySide = "top" | "right" | "bottom" | "left";
+
 declare function Package({ id, width, height, data, parentId, }: NodeProps<Node_2<DefaultNodeProps>>): JSX.Element | null;
 
 declare function PetriNetPlace({ id, width, height, data, }: NodeProps<Node_2<PetriNetPlaceProps>>): JSX.Element | null;
@@ -776,6 +891,19 @@ export declare type SVG = {
 
 export declare type SvgExportMode = "web" | "compat";
 
+/** A single partition (lane) inside an activity swimlane. */
+declare type SwimlaneLane = {
+    id: string;
+    name: string;
+    /**
+     * Lane's extent along the swimlane's primary axis, in absolute flow px. The
+     * last lane is elastic (fills the remainder), so resizing the swimlane only
+     * changes the last lane. Optional: lanes without it divide the space equally,
+     * so existing saved swimlanes render as equal lanes until a separator moves.
+     */
+    size?: number;
+};
+
 declare function SyntaxTreeNonterminal({ id, width, height, data, parentId, }: NodeProps<Node_2<DefaultNodeProps>>): JSX.Element | null;
 
 declare function SyntaxTreeTerminal({ id, width, height, data, parentId, }: NodeProps<Node_2<DefaultNodeProps>>): JSX.Element | null;