@istar-ts/core 0.15.0-beta.0 → 0.15.0-beta.2

package/dist/index.d.cts

@@ -625,6 +625,34 @@ export declare const ACTOR_PADDING = 10;
  * what it actually draws.
  */
 export declare function actorBounds<EK extends string, LK extends string>(model: IstarModel<EK, LK>, actorId: string, metamodel?: Metamodel<EK, LK>, defaultSizeOf?: (kind: EK) => Size): Box;
+/** Space kept between a suggested box and any existing element (`suggestPosition`). */
+export declare const SUGGEST_MARGIN = 20;
+export interface SuggestPositionOptions<EK extends string> {
+  /** The kind of element being placed; its metamodel size is what must not overlap. */
+  readonly kind: EK;
+  /** Place inside this actor's boundary (`actorBounds`), growing it if full. */
+  readonly containerId?: string;
+  /** Prefer a spot adjacent to this element's id, or to this point. */
+  readonly near?: string | Point;
+  readonly metamodel?: Metamodel<EK, string>;
+  /** See `actorBounds`' `defaultSizeOf`. */
+  readonly defaultSizeOf?: (kind: EK) => Size;
+}
+/**
+ * A free spot for a new element of `kind`, overlapping no existing element (sizes from the
+ * metamodel, or `defaultSizeOf` for a host with its own size overrides, as in `actorBounds`).
+ *
+ * Scans a deterministic, fixed-order set of candidates — rings around `near` when given, else
+ * the container's interior, else rings around the origin — and returns the first whose padded
+ * box (`SUGGEST_MARGIN`) overlaps nothing; same input always yields the same output. However
+ * dense the model, the result never overlaps: once every ring candidate is taken, it falls back
+ * to a point past the right edge of every obstacle (`guaranteedFreePoint`).
+ *
+ * Inside `containerId`, the candidate stays within the actor's current boundary (`actorBounds`)
+ * when there is room, or goes just past its last child when the boundary is full — the boundary
+ * grows from there, same as any other inner element (`actorBounds`).
+ */
+export declare function suggestPosition<EK extends string, LK extends string>(model: IstarModel<EK, LK>, options: SuggestPositionOptions<EK>): Point;
 //#endregion
 //#region src/file-metamodel.d.ts
 /** The top-level key of the block in piStar JSON. */

package/dist/index.d.ts

@@ -625,6 +625,34 @@ export declare const ACTOR_PADDING = 10;
  * what it actually draws.
  */
 export declare function actorBounds<EK extends string, LK extends string>(model: IstarModel<EK, LK>, actorId: string, metamodel?: Metamodel<EK, LK>, defaultSizeOf?: (kind: EK) => Size): Box;
+/** Space kept between a suggested box and any existing element (`suggestPosition`). */
+export declare const SUGGEST_MARGIN = 20;
+export interface SuggestPositionOptions<EK extends string> {
+  /** The kind of element being placed; its metamodel size is what must not overlap. */
+  readonly kind: EK;
+  /** Place inside this actor's boundary (`actorBounds`), growing it if full. */
+  readonly containerId?: string;
+  /** Prefer a spot adjacent to this element's id, or to this point. */
+  readonly near?: string | Point;
+  readonly metamodel?: Metamodel<EK, string>;
+  /** See `actorBounds`' `defaultSizeOf`. */
+  readonly defaultSizeOf?: (kind: EK) => Size;
+}
+/**
+ * A free spot for a new element of `kind`, overlapping no existing element (sizes from the
+ * metamodel, or `defaultSizeOf` for a host with its own size overrides, as in `actorBounds`).
+ *
+ * Scans a deterministic, fixed-order set of candidates — rings around `near` when given, else
+ * the container's interior, else rings around the origin — and returns the first whose padded
+ * box (`SUGGEST_MARGIN`) overlaps nothing; same input always yields the same output. However
+ * dense the model, the result never overlaps: once every ring candidate is taken, it falls back
+ * to a point past the right edge of every obstacle (`guaranteedFreePoint`).
+ *
+ * Inside `containerId`, the candidate stays within the actor's current boundary (`actorBounds`)
+ * when there is room, or goes just past its last child when the boundary is full — the boundary
+ * grows from there, same as any other inner element (`actorBounds`).
+ */
+export declare function suggestPosition<EK extends string, LK extends string>(model: IstarModel<EK, LK>, options: SuggestPositionOptions<EK>): Point;
 //#endregion
 //#region src/file-metamodel.d.ts
 /** The top-level key of the block in piStar JSON. */

package/dist/index.js

@@ -811,6 +811,146 @@ function actorBounds(model, actorId, metamodel = metamodelOf(model), defaultSize
 		height: maxY - minY
 	};
 }
+/** Space kept between a suggested box and any existing element (`suggestPosition`). */
+const SUGGEST_MARGIN = 20;
+/** Step between candidate positions on the grid `suggestPosition` scans. */
+const SUGGEST_STEP = 40;
+/** How many rings out `suggestPosition` scans before falling back to `guaranteedFreePoint`. */
+const SUGGEST_MAX_RING = 25;
+function boxesOverlap(a, b) {
+	return a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y;
+}
+function padded(box, margin) {
+	return {
+		x: box.x - margin,
+		y: box.y - margin,
+		width: box.width + margin * 2,
+		height: box.height + margin * 2
+	};
+}
+function firstFreeCandidate(candidates, size, obstacles, fallback) {
+	for (const point of candidates) {
+		const box = {
+			x: point.x,
+			y: point.y,
+			width: size.width,
+			height: size.height
+		};
+		if (!obstacles.some((obstacle) => boxesOverlap(padded(box, 20), obstacle))) return point;
+	}
+	return fallback;
+}
+/**
+* A point guaranteed to overlap no obstacle, however dense the model: past the right edge of
+* every obstacle's box, so no obstacle can reach it regardless of its y (`suggestPosition`'s
+* last-resort fallback, once every ring candidate is taken).
+*/
+function guaranteedFreePoint(obstacles, referenceY) {
+	if (obstacles.length === 0) return {
+		x: 0,
+		y: referenceY
+	};
+	return {
+		x: Math.max(...obstacles.map((box) => box.x + box.width)) + 20,
+		y: referenceY
+	};
+}
+/** Candidate positions in expanding square rings around `center`, in a fixed scan order. */
+function ringCandidates(center, maxRing) {
+	const points = [center];
+	for (let ring = 1; ring <= maxRing; ring++) {
+		const offset = ring * SUGGEST_STEP;
+		for (let dx = -offset; dx <= offset; dx += SUGGEST_STEP) {
+			points.push({
+				x: center.x + dx,
+				y: center.y - offset
+			});
+			points.push({
+				x: center.x + dx,
+				y: center.y + offset
+			});
+		}
+		for (let dy = -offset + SUGGEST_STEP; dy <= offset - SUGGEST_STEP; dy += SUGGEST_STEP) {
+			points.push({
+				x: center.x - offset,
+				y: center.y + dy
+			});
+			points.push({
+				x: center.x + offset,
+				y: center.y + dy
+			});
+		}
+	}
+	return points;
+}
+function modelBoxes(model, defaultSizeOf) {
+	const boxes = [];
+	for (const element of model.elements.values()) {
+		const base = defaultSizeOf(element.kind);
+		const width = element.display?.width ?? base.width;
+		const height = element.display?.height ?? base.height;
+		boxes.push({
+			x: element.x,
+			y: element.y,
+			width,
+			height
+		});
+	}
+	return boxes;
+}
+/**
+* A free spot for a new element of `kind`, overlapping no existing element (sizes from the
+* metamodel, or `defaultSizeOf` for a host with its own size overrides, as in `actorBounds`).
+*
+* Scans a deterministic, fixed-order set of candidates — rings around `near` when given, else
+* the container's interior, else rings around the origin — and returns the first whose padded
+* box (`SUGGEST_MARGIN`) overlaps nothing; same input always yields the same output. However
+* dense the model, the result never overlaps: once every ring candidate is taken, it falls back
+* to a point past the right edge of every obstacle (`guaranteedFreePoint`).
+*
+* Inside `containerId`, the candidate stays within the actor's current boundary (`actorBounds`)
+* when there is room, or goes just past its last child when the boundary is full — the boundary
+* grows from there, same as any other inner element (`actorBounds`).
+*/
+function suggestPosition(model, options) {
+	const metamodel = options.metamodel ?? metamodelOf(model);
+	const defaultSizeOf = options.defaultSizeOf ?? ((kind) => metamodelSizeOf(metamodel, kind));
+	const size = defaultSizeOf(options.kind);
+	const obstacles = modelBoxes(model, defaultSizeOf);
+	const near = typeof options.near === "string" ? model.elements.get(options.near) : options.near;
+	const nearPoint = near ? "kind" in near ? {
+		x: near.x,
+		y: near.y
+	} : near : void 0;
+	if (options.containerId) {
+		const bounds = actorBounds(model, options.containerId, metamodel, defaultSizeOf);
+		const candidates = ringCandidates(nearPoint ?? {
+			x: bounds.x + 10,
+			y: bounds.y + 10
+		}, SUGGEST_MAX_RING).filter((point) => point.x >= bounds.x + 10 && point.y >= bounds.y + 10 && point.x + size.width <= bounds.x + bounds.width - 10 && point.y + size.height <= bounds.y + bounds.height - 10);
+		if (candidates.length > 0) {
+			const sentinel = {
+				x: NaN,
+				y: NaN
+			};
+			const found = firstFreeCandidate(candidates, size, obstacles, sentinel);
+			if (found !== sentinel) return found;
+		}
+		const pastLastChild = {
+			x: bounds.x + bounds.width + 10,
+			y: bounds.y + 10
+		};
+		return firstFreeCandidate(ringCandidates(pastLastChild, SUGGEST_MAX_RING), size, obstacles, guaranteedFreePoint(obstacles, pastLastChild.y));
+	}
+	const start = nearPoint ?? (obstacles.length > 0 ? {
+		x: Math.max(...obstacles.map((box) => box.x + box.width)) + 20,
+		y: 0
+	} : {
+		x: 0,
+		y: 0
+	});
+	return firstFreeCandidate(ringCandidates(start, SUGGEST_MAX_RING), size, obstacles, guaranteedFreePoint(obstacles, start.y));
+}
 //#endregion
 //#region src/constraints.ts
 const OK = { ok: true };
@@ -3152,6 +3292,6 @@ function buildDefaultPalette() {
 /** The palette data of iStar 2.0, as piStar's toolbar presents it. */
 const DEFAULT_PALETTE = buildDefaultPalette();
 //#endregion
-export { ACTOR_KINDS, ACTOR_LINK_KINDS, ACTOR_PADDING, CONTRIBUTION_LABELS, DEFAULT_DIAGRAM, DEFAULT_ELEMENT_SIZE, DEFAULT_PALETTE, DEPENDENCY_LINK_KINDS, DIAGNOSTIC_SEVERITIES, DIAGRAM_LAYOUT_KEY, DSM3_FILE_KEYS, DSM3_TOOL, ELEMENT_KINDS, FILE_METAMODEL_KEY, HUB_ENTRY_KEY, ISTAR_2_0, ISTAR_2_0_DECLARATION, ISTAR_PREFIX, ISTAR_VERSION, LINK_KINDS, LINK_KIND_INFO, LINK_SELECTOR, METAMODEL_VERSION, MetamodelError, ModelOperationError, NODE_KINDS, NODE_KIND_INFO, NODE_LINK_KINDS, PISTAR_TOOL, PistarParseError, PistarWriteError, actorBounds, addDependency, addElement, addLeg, boolean, canLink, childrenOf, compareSeverity, connect, connectResultToDiagnostic, createDiagnosticsStore, createEmptyModel, createModelStore, defaultHubPosition, defaultIdGenerator, defineMetamodel, defineMetamodelExtension, defineProperties, dependencyEnds, dependencyLinksOf, detectFramework, detectPrefix, disconnect, effectiveElementKind, effectiveLinkKind, elementBehavesLike, elementCenter, elementKindDefinition, enumOf, extendMetamodel, fileMetamodelExtension, fileMetamodelOf, fromLspDiagnostic, fromLspDiagnostics, fromNodeIdDiagnostic, fromNodeIdDiagnostics, getSourceLayout, groupDiagnostics, hostMetamodelOf, hubEntryLayoutKey, hubLinkOf, hubOfLink, inheritMetamodel, inheritSourceLayout, isActor, isActorIn, isActorKind, isActorKindIn, isActorLinkKind, isContributionLabel, isDependencyLinkKind, isElementKind, isHubElement, isLinkKind, isLinkRef, isNode, isNodeIn, isNodeKind, isNodeKindIn, isNodeLinkKind, linkBehavesLike, linkKindDefinition, linkTargetOf, linksOf, mergeDiagnostics, metamodelOf, moveElement, nestElement, number, parsePistar, prop, reference, removeElement, removeElements, removeLeg, setHostMetamodel, shortKindName, string, targetsLinks, toPistar, toPistarObject, updateDiagram, updateElement, updateLink, validateFileMetamodel, validateModel, validateModelProperties, withFileMetamodel, withMetamodel, worstDiagnosticSeverity };
+export { ACTOR_KINDS, ACTOR_LINK_KINDS, ACTOR_PADDING, CONTRIBUTION_LABELS, DEFAULT_DIAGRAM, DEFAULT_ELEMENT_SIZE, DEFAULT_PALETTE, DEPENDENCY_LINK_KINDS, DIAGNOSTIC_SEVERITIES, DIAGRAM_LAYOUT_KEY, DSM3_FILE_KEYS, DSM3_TOOL, ELEMENT_KINDS, FILE_METAMODEL_KEY, HUB_ENTRY_KEY, ISTAR_2_0, ISTAR_2_0_DECLARATION, ISTAR_PREFIX, ISTAR_VERSION, LINK_KINDS, LINK_KIND_INFO, LINK_SELECTOR, METAMODEL_VERSION, MetamodelError, ModelOperationError, NODE_KINDS, NODE_KIND_INFO, NODE_LINK_KINDS, PISTAR_TOOL, PistarParseError, PistarWriteError, SUGGEST_MARGIN, actorBounds, addDependency, addElement, addLeg, boolean, canLink, childrenOf, compareSeverity, connect, connectResultToDiagnostic, createDiagnosticsStore, createEmptyModel, createModelStore, defaultHubPosition, defaultIdGenerator, defineMetamodel, defineMetamodelExtension, defineProperties, dependencyEnds, dependencyLinksOf, detectFramework, detectPrefix, disconnect, effectiveElementKind, effectiveLinkKind, elementBehavesLike, elementCenter, elementKindDefinition, enumOf, extendMetamodel, fileMetamodelExtension, fileMetamodelOf, fromLspDiagnostic, fromLspDiagnostics, fromNodeIdDiagnostic, fromNodeIdDiagnostics, getSourceLayout, groupDiagnostics, hostMetamodelOf, hubEntryLayoutKey, hubLinkOf, hubOfLink, inheritMetamodel, inheritSourceLayout, isActor, isActorIn, isActorKind, isActorKindIn, isActorLinkKind, isContributionLabel, isDependencyLinkKind, isElementKind, isHubElement, isLinkKind, isLinkRef, isNode, isNodeIn, isNodeKind, isNodeKindIn, isNodeLinkKind, linkBehavesLike, linkKindDefinition, linkTargetOf, linksOf, mergeDiagnostics, metamodelOf, moveElement, nestElement, number, parsePistar, prop, reference, removeElement, removeElements, removeLeg, setHostMetamodel, shortKindName, string, suggestPosition, targetsLinks, toPistar, toPistarObject, updateDiagram, updateElement, updateLink, validateFileMetamodel, validateModel, validateModelProperties, withFileMetamodel, withMetamodel, worstDiagnosticSeverity };
 
 //# sourceMappingURL=index.js.map