@likec4/diagram 1.59.4 → 1.61.0

package/dist/likec4diagram/state/diagram-api.d.mts

@@ -0,0 +1,190 @@
+import { __name } from "../../_virtual/_rolldown/runtime.mjs";
+import { TogglableFeature } from "../../context/DiagramFeatures.mjs";
+import { EditorActorRef } from "../../editor/actor/machine.mjs";
+import { OpenSourceParams, RelationshipBrowserScope } from "../../LikeC4Diagram.props.mjs";
+import { OverlaysActorRef } from "../../overlays/overlaysActor.mjs";
+import { SearchActorRef } from "../../search/searchActor.mjs";
+import { Types } from "../types.mjs";
+import { AlignmentMode } from "./aligners.mjs";
+import { Context, ElementViewDisplayVariant, Events } from "./machine.setup.mjs";
+import { DiagramActorRef } from "./types.mjs";
+import * as t from "@likec4/core/types";
+import { DynamicViewDisplayVariant, NodeNotation, ViewChange } from "@likec4/core/types";
+import { PartialDeep } from "type-fest";
+type Any$1 = t.aux.AnyLayouted;
+type Unknown = t.aux.UnknownLayouted;
+type ViewId$1<A> = t.aux.ViewId<A>;
+type Fqn$1<A> = t.aux.Fqn<A>;
+type NodeId$1 = t.aux.NodeId;
+type EdgeId$1 = t.aux.EdgeId;
+export declare class DiagramApi<A extends Any$1 = Unknown> {
+  private static cache;
+  static withActor(actorRef: DiagramActorRef): DiagramApi<Unknown>;
+  /**
+   * @warning Do not use in render phase
+   */
+  readonly actor: DiagramActorRef;
+  private constructor();
+  /**
+   * @warning Do not use in render phase
+   */
+  get currentView(): t.DiagramView<A>;
+  /**
+   * Editor actor reference
+   * @warning Do not use in render phase
+   */
+  editorActor(): EditorActorRef;
+  /**
+   * Overlays actor reference
+   * @warning Do not use in render phase
+   */
+  overlays(): OverlaysActorRef;
+  /**
+   * Search actor reference
+   * @warning Do not use in render phase
+   */
+  searchActor(): SearchActorRef;
+  /**
+   * Send event to diagram actor
+   */
+  send(event: Events): void;
+  /**
+   * Navigate to view
+   * @param viewId - Target view ID
+   * @param fromNode - Node from which navigation was triggered
+   * @param focusOnElement - Element FQN to focus after navigation (from search)
+   */
+  navigateTo(viewId: ViewId$1<A>, fromNode?: NodeId$1, focusOnElement?: Fqn$1<A>): void;
+  /**
+   * Navigate back or forward in history
+   */
+  navigate(direction: 'back' | 'forward'): void;
+  /**
+   * Fit diagram to view
+   */
+  fitDiagram(duration?: number): void;
+  /**
+   * Open relationships browser
+   */
+  openRelationshipsBrowser(fqn: Fqn$1<A>, scope?: RelationshipBrowserScope): void;
+  /**
+   * If running in editor, trigger opening source file
+   */
+  openSource(params: OpenSourceParams<Unknown>): void;
+  /**
+   * Open details for a diagram node, or an explicit element/deployment subject outside the current view.
+   */
+  openNodeDetails(target: NodeId$1 | {
+    type: 'element';
+    element: Fqn$1<A>;
+  } | {
+    type: 'deployment';
+    deployment: t.aux.DeploymentFqn<A>;
+  }, fromNode?: NodeId$1): void;
+  /**
+   * @deprecated Use `openNodeDetails({ type: 'element', element: fqn }, fromNode)`.
+   */
+  openElementDetails(fqn: Fqn$1<A>, fromNode?: NodeId$1): void;
+  openRelationshipDetails(...params: [edgeId: EdgeId$1] | [source: Fqn$1<A>, target: Fqn$1<A>]): void;
+  updateNodeData(nodeId: NodeId$1, data: PartialDeep<Types.NodeData>): void;
+  updateEdgeData(edgeId: EdgeId$1, data: PartialDeep<Types.EdgeData>): void;
+  highlightNode(nodeId: NodeId$1): void;
+  highlightEdge(edgeId: EdgeId$1): void;
+  unhighlightAll(): void;
+  /**
+   * Select nodes and edges in the diagram
+   * @param target - Optional selection target. If not provided, resets selection
+   */
+  select(target?: {
+    nodes?: NodeId$1[];
+    edges?: (EdgeId$1 | t.StepPath)[];
+  }): void;
+  /**
+   * Center viewport on a given node
+   */
+  centerViewportOnNode(target: NodeId$1): void;
+  /**
+   * Center viewport on a given edge (centering on edge means including both source and target nodes in view)
+   */
+  centerViewportOnEdge(target: EdgeId$1): void;
+  /**
+   * Start editing, either node or edge
+   */
+  startEditing(subject: 'node' | 'edge'): void;
+  /**
+   * Stop editing
+   * @param wasChanged - whether there were changes made during editing
+   * @default false
+   */
+  stopEditing(wasChanged?: boolean): void;
+  /**
+   * Undo last editing operation
+   * @returns true if there was something to undo
+   */
+  undoEditing(): boolean;
+  /**
+   * Align nodes
+   */
+  align(mode: AlignmentMode): void;
+  /**
+   * Reset edge control points
+   */
+  resetEdgeControlPoints(): void;
+  /**
+   * Focus node
+   */
+  focusNode(nodeId: NodeId$1): void;
+  /**
+   * Focus on element by FQN (finds the node and focuses on it).
+   * Used by search to highlight an element on the current view.
+   */
+  focusOnElement(elementFqn: Fqn$1<A>): void;
+  /**
+   * @warning Do not use in render phase
+   */
+  getContext(): Context;
+  /**
+   * @warning Do not use in render phase
+   */
+  findDiagramNode(xynodeId: string): t.DiagramNode<A> | null;
+  /**
+   * @warning Do not use in render phase
+   */
+  findEdge(xyedgeId: string): Types.Edge | null;
+  /**
+   * @warning Do not use in render phase
+   */
+  findDiagramEdge(xyedgeId: string): t.DiagramEdge<A> | null;
+  startWalkthrough(stepId?: t.StepPath): void;
+  walkthroughStep(value?: 'next' | 'prev' | {
+    step: t.StepPath;
+  }): void;
+  stopWalkthrough(): void;
+  /**
+   * Starts comparing manual layout with the latest auto layout.
+   * Ignored if the view has no layout drifts, or the feature is disabled.
+   */
+  startCompare(): void;
+  /**
+   * Stops comparing layouts, switches back to manual layout (if auto is active)
+   */
+  endCompare(): void;
+  toggleFeature(feature: TogglableFeature, forceValue?: boolean): void;
+  highlightNotation(notation: NodeNotation, kind?: string): void;
+  unhighlightNotation(): void;
+  openSearch(searchValue?: string): void;
+  triggerChange(change: ViewChange): void;
+  /**
+   * Switch dynamic view display variant
+   */
+  switchDynamicViewVariant(variant: DynamicViewDisplayVariant): void;
+  /**
+   * Switch element view display variant ('diagram' | 'graph')
+   */
+  switchElementViewVariant(variant: ElementViewDisplayVariant): void;
+  /**
+   * Toggle sequence flow collapse/expand
+   */
+  toggleSequenceFlow(flowId: t.StepPath): void;
+}
+export {};

package/dist/likec4diagram/state/diagram-api.mjs

@@ -0,0 +1,386 @@
+import { __name } from "../../_virtual/_rolldown/runtime.mjs";
+import { findDiagramEdge, findDiagramNode, findNodeByModelFqn, typedSystem } from "./utils.mjs";
+import { invariant, nonNullable } from "@likec4/core/utils";
+
+// src/likec4diagram/state/diagram-api.ts
+var DiagramApi = class DiagramApi {
+	static cache = /* @__PURE__ */ new WeakMap();
+	static withActor(actorRef) {
+		let api = this.cache.get(actorRef);
+		if (!api) {
+			api = new DiagramApi(actorRef);
+			this.cache.set(actorRef, api);
+		}
+		return api;
+	}
+	/**
+	* @warning Do not use in render phase
+	*/
+	actor;
+	constructor(actor) {
+		this.actor = actor;
+	}
+	/**
+	* @warning Do not use in render phase
+	*/
+	get currentView() {
+		return this.actor.getSnapshot().context.view;
+	}
+	/**
+	* Editor actor reference
+	* @warning Do not use in render phase
+	*/
+	editorActor() {
+		const editorActor = typedSystem(this.actor.system).editorActorRef;
+		return nonNullable(editorActor, "Editor actor not found in actor system");
+	}
+	/**
+	* Overlays actor reference
+	* @warning Do not use in render phase
+	*/
+	overlays() {
+		const overlaysActor = typedSystem(this.actor.system).overlaysActorRef;
+		return nonNullable(overlaysActor, "Overlays actor not found in actor system");
+	}
+	/**
+	* Search actor reference
+	* @warning Do not use in render phase
+	*/
+	searchActor() {
+		const searchActor = typedSystem(this.actor.system).searchActorRef;
+		return nonNullable(searchActor, "Search actor not found in actor system");
+	}
+	/**
+	* Send event to diagram actor
+	*/
+	send(event) {
+		this.actor.send(event);
+	}
+	/**
+	* Navigate to view
+	* @param viewId - Target view ID
+	* @param fromNode - Node from which navigation was triggered
+	* @param focusOnElement - Element FQN to focus after navigation (from search)
+	*/
+	navigateTo(viewId, fromNode, focusOnElement) {
+		this.send({
+			type: "navigate.to",
+			viewId,
+			...fromNode && { fromNode },
+			...focusOnElement && { focusOnElement }
+		});
+	}
+	/**
+	* Navigate back or forward in history
+	*/
+	navigate(direction) {
+		this.send({ type: `navigate.${direction}` });
+	}
+	/**
+	* Fit diagram to view
+	*/
+	fitDiagram(duration = 350) {
+		this.send({
+			type: "xyflow.fitDiagram",
+			duration
+		});
+	}
+	/**
+	* Open relationships browser
+	*/
+	openRelationshipsBrowser(fqn, scope) {
+		this.send({
+			type: "open.relationshipsBrowser",
+			fqn,
+			...scope && { scope }
+		});
+	}
+	/**
+	* If running in editor, trigger opening source file
+	*/
+	openSource(params) {
+		this.send({
+			type: "open.source",
+			...params
+		});
+	}
+	/**
+	* Open details for a diagram node, or an explicit element/deployment subject outside the current view.
+	*/
+	openNodeDetails(target, fromNode) {
+		this.send({
+			type: "open.nodeDetails",
+			target,
+			fromNode
+		});
+	}
+	/**
+	* @deprecated Use `openNodeDetails({ type: 'element', element: fqn }, fromNode)`.
+	*/
+	openElementDetails(fqn, fromNode) {
+		this.openNodeDetails({
+			type: "element",
+			element: fqn
+		}, fromNode);
+	}
+	openRelationshipDetails(...params) {
+		if (params.length === 1) this.send({
+			type: "open.relationshipDetails",
+			params: { edgeId: params[0] }
+		});
+		else this.send({
+			type: "open.relationshipDetails",
+			params: {
+				source: params[0],
+				target: params[1]
+			}
+		});
+	}
+	updateNodeData(nodeId, data) {
+		this.send({
+			type: "update.nodeData",
+			nodeId,
+			data
+		});
+	}
+	updateEdgeData(edgeId, data) {
+		this.send({
+			type: "update.edgeData",
+			edgeId,
+			data
+		});
+	}
+	highlightNode(nodeId) {
+		this.send({
+			type: "highlight.node",
+			nodeId
+		});
+	}
+	highlightEdge(edgeId) {
+		this.send({
+			type: "highlight.edge",
+			edgeId
+		});
+	}
+	unhighlightAll() {
+		this.send({ type: "unhighlight.all" });
+	}
+	/**
+	* Select nodes and edges in the diagram
+	* @param target - Optional selection target. If not provided, resets selection
+	*/
+	select(target) {
+		const nodes = target?.nodes ?? [];
+		const edges = target?.edges ?? [];
+		if (nodes.length === 0 && edges.length === 0) {
+			this.send({ type: "xyflow.resetSelection" });
+			return;
+		}
+		this.send({
+			type: "xyflow.select",
+			nodes,
+			edges
+		});
+	}
+	/**
+	* Center viewport on a given node
+	*/
+	centerViewportOnNode(target) {
+		this.send({
+			type: "xyflow.centerViewport",
+			nodeId: target
+		});
+	}
+	/**
+	* Center viewport on a given edge (centering on edge means including both source and target nodes in view)
+	*/
+	centerViewportOnEdge(target) {
+		this.send({
+			type: "xyflow.centerViewport",
+			edgeId: target
+		});
+	}
+	/**
+	* Start editing, either node or edge
+	*/
+	startEditing(subject) {
+		const editorActor = typedSystem(this.actor.system).editorActorRef;
+		invariant(editorActor, "No editor actor found in diagram actor system");
+		editorActor.send({
+			type: "edit.move.start",
+			subject
+		});
+	}
+	/**
+	* Stop editing
+	* @param wasChanged - whether there were changes made during editing
+	* @default false
+	*/
+	stopEditing(wasChanged = false) {
+		const editorActor = typedSystem(this.actor.system).editorActorRef;
+		invariant(editorActor, "No editor actor found in diagram actor system");
+		editorActor.send({ type: wasChanged ? "edit.move.end" : "edit.move.cancel" });
+	}
+	/**
+	* Undo last editing operation
+	* @returns true if there was something to undo
+	*/
+	undoEditing() {
+		const editorActor = typedSystem(this.actor.system).editorActorRef;
+		invariant(editorActor, "No editor actor found in diagram actor system");
+		const hasUndo = editorActor.getSnapshot().context.history !== null;
+		if (hasUndo) editorActor.send({ type: "undo" });
+		return hasUndo;
+	}
+	/**
+	* Align nodes
+	*/
+	align(mode) {
+		this.send({
+			type: "layout.align",
+			mode
+		});
+	}
+	/**
+	* Reset edge control points
+	*/
+	resetEdgeControlPoints() {
+		this.send({ type: "layout.resetEdgeControlPoints" });
+	}
+	/**
+	* Focus node
+	*/
+	focusNode(nodeId) {
+		this.send({
+			type: "focus.node",
+			nodeId
+		});
+	}
+	/**
+	* Focus on element by FQN (finds the node and focuses on it).
+	* Used by search to highlight an element on the current view.
+	*/
+	focusOnElement(elementFqn) {
+		const context = this.actor.getSnapshot().context;
+		const node = findNodeByModelFqn(context.xynodes, elementFqn);
+		if (node) this.send({
+			type: "focus.node",
+			nodeId: node.id,
+			autoUnfocus: true
+		});
+	}
+	/**
+	* @warning Do not use in render phase
+	*/
+	getContext() {
+		return this.actor.getSnapshot().context;
+	}
+	/**
+	* @warning Do not use in render phase
+	*/
+	findDiagramNode(xynodeId) {
+		return findDiagramNode(this.actor.getSnapshot().context, xynodeId);
+	}
+	/**
+	* @warning Do not use in render phase
+	*/
+	findEdge(xyedgeId) {
+		return this.actor.getSnapshot().context.xyedges.find((e) => e.data.id === xyedgeId) ?? null;
+	}
+	/**
+	* @warning Do not use in render phase
+	*/
+	findDiagramEdge(xyedgeId) {
+		return findDiagramEdge(this.actor.getSnapshot().context, xyedgeId);
+	}
+	startWalkthrough(stepId) {
+		this.send({
+			type: "walkthrough.start",
+			stepId
+		});
+	}
+	walkthroughStep(value = "next") {
+		if (value === "next" || value === "prev") this.send({
+			type: "walkthrough.step",
+			direction: value
+		});
+		else this.send({
+			type: "walkthrough.step",
+			stepId: value.step
+		});
+	}
+	stopWalkthrough() {
+		this.send({ type: "walkthrough.end" });
+	}
+	/**
+	* Starts comparing manual layout with the latest auto layout.
+	* Ignored if the view has no layout drifts, or the feature is disabled.
+	*/
+	startCompare() {
+		this.send({ type: "compare.start" });
+	}
+	/**
+	* Stops comparing layouts, switches back to manual layout (if auto is active)
+	*/
+	endCompare() {
+		this.send({ type: "compare.end" });
+	}
+	toggleFeature(feature, forceValue) {
+		this.send({
+			type: "toggle.feature",
+			feature,
+			...forceValue !== void 0 && { forceValue }
+		});
+	}
+	highlightNotation(notation, kind) {
+		this.send({
+			type: "notations.highlight",
+			notation,
+			...kind && { kind }
+		});
+	}
+	unhighlightNotation() {
+		this.send({ type: "notations.unhighlight" });
+	}
+	openSearch(searchValue) {
+		this.send({
+			type: "open.search",
+			...searchValue && { search: searchValue }
+		});
+	}
+	triggerChange(change) {
+		this.send({
+			type: "trigger.change",
+			change
+		});
+	}
+	/**
+	* Switch dynamic view display variant
+	*/
+	switchDynamicViewVariant(variant) {
+		this.send({
+			type: "switch.dynamicViewVariant",
+			variant
+		});
+	}
+	/**
+	* Switch element view display variant ('diagram' | 'graph')
+	*/
+	switchElementViewVariant(variant) {
+		this.send({
+			type: "switch.elementViewVariant",
+			variant
+		});
+	}
+	/**
+	* Toggle sequence flow collapse/expand
+	*/
+	toggleSequenceFlow(flowId) {
+		this.send({
+			type: "sequence.flow.toggle",
+			flowId
+		});
+	}
+};
+
+export { DiagramApi };

package/dist/likec4diagram/state/hotkeyActor.d.mts

@@ -0,0 +1,6 @@
+import { __name } from "../../_virtual/_rolldown/runtime.mjs";
+import { AnyEventObject, CallbackActorLogic, NonReducibleUnknown } from "xstate";
+export type HotKeyEvent = {
+  type: 'key.esc' | `key.arrow.${'left' | 'right' | 'up' | 'down'}`;
+};
+export interface HotkeyActorLogic extends CallbackActorLogic<AnyEventObject, NonReducibleUnknown, HotKeyEvent> {}

package/dist/likec4diagram/state/hotkeyActor.mjs

@@ -0,0 +1,64 @@
+import { __name } from "../../_virtual/_rolldown/runtime.mjs";
+import { isEventFromSearch } from "../../utils/search-event.mjs";
+import { getHotkeyHandler } from "@mantine/hooks";
+import { fromCallback } from "xstate";
+
+// src/likec4diagram/state/hotkeyActor.ts
+const hotkeyActorLogic = fromCallback(({ sendBack }) => {
+	const escHandler = getHotkeyHandler([[
+		"Escape",
+		(event) => {
+			event.stopPropagation();
+			sendBack({ type: "key.esc" });
+		},
+		{ preventDefault: true }
+	]]);
+	const arrowshandler = getHotkeyHandler([
+		[
+			"ArrowLeft",
+			(event) => {
+				event.stopPropagation();
+				sendBack({ type: "key.arrow.left" });
+			},
+			{ preventDefault: true }
+		],
+		[
+			"ArrowUp",
+			(event) => {
+				event.stopPropagation();
+				sendBack({ type: "key.arrow.up" });
+			},
+			{ preventDefault: true }
+		],
+		[
+			"ArrowRight",
+			(event) => {
+				event.stopPropagation();
+				sendBack({ type: "key.arrow.right" });
+			},
+			{ preventDefault: true }
+		],
+		[
+			"ArrowDown",
+			(event) => {
+				event.stopPropagation();
+				sendBack({ type: "key.arrow.down" });
+			},
+			{ preventDefault: true }
+		]
+	]);
+	const onEsc = (event) => {
+		if (!isEventFromSearch(event)) escHandler(event);
+	};
+	const onArrows = (event) => {
+		if (!isEventFromSearch(event)) arrowshandler(event);
+	};
+	document.body.addEventListener("keydown", onEsc);
+	document.body.addEventListener("keydown", onArrows, { capture: true });
+	return () => {
+		document.body.removeEventListener("keydown", onEsc);
+		document.body.removeEventListener("keydown", onArrows, { capture: true });
+	};
+});
+
+export { hotkeyActorLogic };