@likec4/diagram 1.59.4 → 1.60.0

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

@@ -0,0 +1,173 @@
+import { __name } from "../../_virtual/_rolldown/runtime.mjs";
+import { Types } from "../types.mjs";
+import { OverlaysActorRef } from "../../overlays/overlaysActor.mjs";
+import { SearchActorRef } from "../../search/searchActor.mjs";
+import { EditorActorRef } from "../../editor/actor/machine.mjs";
+import { TogglableFeature } from "../../context/DiagramFeatures.mjs";
+import { AlignmentMode } from "./aligners.mjs";
+import { OpenSourceParams, RelationshipBrowserScope } from "../../LikeC4Diagram.props.mjs";
+import { Context, ElementViewDisplayVariant, Events } from "./machine.setup.mjs";
+import { DiagramActorRef } from "./types.mjs";
+import { RefObject } from "react";
+import * as t from "@likec4/core/types";
+import { DynamicViewDisplayVariant, NodeNotation, ViewChange } from "@likec4/core/types";
+import { PartialDeep } from "type-fest";
+//#region src/likec4diagram/state/diagram-api.d.ts
+type Any$1 = t.aux.Any;
+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: RefObject<DiagramActorRef>): DiagramApi;
+  /**
+   * React ref to the diagram actor
+   */
+  readonly ref: RefObject<DiagramActorRef>;
+  private constructor();
+  /**
+   * @warning Do not use in render phase
+   */
+  get actor(): DiagramActorRef;
+  /**
+   * @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 element details card
+   */
+  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(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;
+  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;
+}
+//#endregion

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

@@ -0,0 +1,362 @@
+import { __name } from "../../_virtual/_rolldown/runtime.mjs";
+import { findDiagramEdge, findDiagramNode, findNodeByModelFqn, typedSystem } from "./utils.mjs";
+import { DefaultWeakMap, invariant, nonNullable } from "@likec4/core/utils";
+
+//#region src/likec4diagram/state/diagram-api.ts
+var DiagramApi = class DiagramApi {
+	static cache = new DefaultWeakMap((ref) => new DiagramApi(ref));
+	static withActor(actorRef) {
+		return this.cache.get(actorRef);
+	}
+	/**
+	* React ref to the diagram actor
+	*/
+	ref;
+	constructor(actorRef) {
+		this.ref = actorRef;
+	}
+	/**
+	* @warning Do not use in render phase
+	*/
+	get actor() {
+		return this.ref.current;
+	}
+	/**
+	* @warning Do not use in render phase
+	*/
+	get currentView() {
+		return this.ref.current.getSnapshot().context.view;
+	}
+	/**
+	* Editor actor reference
+	* @warning Do not use in render phase
+	*/
+	editorActor() {
+		const editorActor = typedSystem(this.ref.current.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.ref.current.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.ref.current.system).searchActorRef;
+		return nonNullable(searchActor, "Search actor not found in actor system");
+	}
+	/**
+	* Send event to diagram actor
+	*/
+	send(event) {
+		this.ref.current.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 element details card
+	*/
+	openElementDetails(fqn, fromNode) {
+		this.send({
+			type: "open.elementDetails",
+			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(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.ref.current.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.ref.current.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.ref.current.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.ref.current.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.ref.current.getSnapshot().context;
+	}
+	/**
+	* @warning Do not use in render phase
+	*/
+	findDiagramNode(xynodeId) {
+		return findDiagramNode(this.ref.current.getSnapshot().context, xynodeId);
+	}
+	/**
+	* @warning Do not use in render phase
+	*/
+	findEdge(xyedgeId) {
+		return this.ref.current.getSnapshot().context.xyedges.find((e) => e.data.id === xyedgeId) ?? null;
+	}
+	/**
+	* @warning Do not use in render phase
+	*/
+	findDiagramEdge(xyedgeId) {
+		return findDiagramEdge(this.ref.current.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" });
+	}
+	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
+		});
+	}
+};
+
+//#endregion
+export { DiagramApi };

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

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

package/dist/likec4diagram/state/hotkeyActor.mjs

@@ -0,0 +1,58 @@
+import { __name } from "../../_virtual/_rolldown/runtime.mjs";
+import { getHotkeyHandler } from "@mantine/hooks";
+import { fromCallback } from "xstate";
+
+//#region 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 }
+		]
+	]);
+	document.body.addEventListener("keydown", escHandler);
+	document.body.addEventListener("keydown", arrowshandler, { capture: true });
+	return () => {
+		document.body.removeEventListener("keydown", escHandler);
+		document.body.removeEventListener("keydown", arrowshandler, { capture: true });
+	};
+});
+
+//#endregion
+export { hotkeyActorLogic };