@istar-ts/core 0.14.2 → 0.15.0-beta.1

package/dist/index.d.cts

@@ -76,6 +76,7 @@ export type LinkCheck = {
   ok: false;
   reason: string;
   code: ConstraintCode;
+  end?: "source" | "target";
 };
 /**
  * True for a link, as opposed to an element: the target of a link kind whose rules target links
@@ -607,6 +608,51 @@ export declare function elementCenter<EK extends string, LK extends string>(mode
  * Returns its top-left corner for a hub of `size`.
  */
 export declare function defaultHubPosition<EK extends string, LK extends string>(model: IstarModel<EK, LK>, source: IstarElement<EK>, target: IstarElement<EK>, size: Size): Point;
+export interface Box extends Point, Size {}
+/** Space kept between inner elements and an actor's boundary (piStar's `updateBoundary` adds 10px). */
+export declare const ACTOR_PADDING = 10;
+/**
+ * An actor's boundary: the kind's default-size rectangle at the actor's position, grown to
+ * include every inner element (each padded by `ACTOR_PADDING`), like piStar's `updateBoundary`
+ * (which floors on the kind's default size, not the actor's last expanded `display` size; an
+ * inner element's own `display` size does override, same as its rendered size elsewhere).
+ * Shared by `@istar-ts/react`'s node layout and `@istar-ts/glsp`'s GModel, so an actor draws the
+ * same box in both: children are looked up by category (`metamodelOf`), not `istar.*` names.
+ *
+ * `defaultSizeOf` resolves a kind's default size; it defaults to the metamodel's, but a host
+ * whose registry overrides a kind's size independently of the metamodel (`@istar-ts/react`'s
+ * `IstarRegistry`) must pass one that reads its own sizes, or its boundary would stop matching
+ * 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. */
@@ -811,11 +857,149 @@ export declare function fileMetamodelOf<EK extends string, LK extends string>(mo
  * host's kinds, or leaves out a kind the model still uses.
  */
 export declare function withFileMetamodel<EK extends string, LK extends string>(model: IstarModel<EK, LK>, block: FileMetamodel | null): IstarModel<string, string>;
+//#endregion
+//#region src/diagnostics.d.ts
+/**
+ * The Goal Model Diagnostics Protocol: findings about a model's elements and links, published by
+ * any analyser (a language server, a validator, a simulation…) and anchored by element id rather
+ * than by text position. Data only: diagnostics are never part of the model and are never
+ * written to disk.
+ *
+ * See goal-controller issue #24 (option D). Producers publish per source; consumers see the
+ * union of every source, deduplicated by `(elementId, key, message)`.
+ */
+export type DiagnosticSeverity = "error" | "warning" | "info" | "hint";
+/** Most severe first. */
+export declare const DIAGNOSTIC_SEVERITIES: readonly DiagnosticSeverity[];
+/** A zero-based position in the producer's document (as in LSP). */
+export interface DiagnosticPosition {
+  readonly line: number;
+  readonly character: number;
+}
+export interface DiagnosticRange {
+  readonly start: DiagnosticPosition;
+  readonly end: DiagnosticPosition;
+}
+export interface GoalDiagnostic {
+  /** Id of the element or link the diagnostic is about. */
+  readonly elementId: string;
+  /** The custom property it is about; absent for the element as a whole. */
+  readonly key?: string;
+  readonly severity: DiagnosticSeverity;
+  readonly message: string;
+  /** Who published it (e.g. `mutrose`, `goal-language`). */
+  readonly source?: string;
+  /** Where it was found in the producer's document, if it has one. */
+  readonly range?: DiagnosticRange;
+  readonly code?: string;
+  /** Producer data, passed through untouched. */
+  readonly data?: unknown;
+}
+/** Negative when `a` is more severe than `b`. */
+export declare function compareSeverity(a: DiagnosticSeverity, b: DiagnosticSeverity): number;
+/** The most severe severity in a list (what a badge shows), or `undefined` if it is empty. */
+export declare function worstDiagnosticSeverity(diagnostics: readonly {
+  readonly severity: DiagnosticSeverity;
+}[] | undefined): DiagnosticSeverity | undefined;
+/**
+ * The union of several lists, in order, without duplicates: diagnostics with the same
+ * `(elementId, key, message)` count once, keeping the first one's position and the most severe
+ * severity among them.
+ */
+export declare function mergeDiagnostics(lists: Iterable<readonly GoalDiagnostic[] | undefined>): GoalDiagnostic[];
+/** Diagnostics by element (or link) id, each list in the input order. */
+export declare function groupDiagnostics(diagnostics: readonly GoalDiagnostic[] | undefined): ReadonlyMap<string, readonly GoalDiagnostic[]>;
+/**
+ * Holds the diagnostics of several sources. Each `publish` replaces that source's set, so a
+ * producer re-publishes everything it currently reports, as an LSP server does.
+ */
+export interface DiagnosticsStore {
+  /**
+   * Replaces `source`'s diagnostics (an empty list clears them). Entries without a `source` get
+   * this one.
+   */
+  publish(source: string, diagnostics: readonly GoalDiagnostic[]): void;
+  /** Removes one source's diagnostics, or every source's. */
+  clear(source?: string): void;
+  /** Sources with diagnostics, in the order they first published. */
+  sources(): readonly string[];
+  /** One source's diagnostics. */
+  get(source: string): readonly GoalDiagnostic[];
+  /**
+   * Every source's diagnostics, merged (see `mergeDiagnostics`). The same array until the next
+   * change, so it can back `useSyncExternalStore`.
+   */
+  getAll(): readonly GoalDiagnostic[];
+  subscribe(listener: () => void): () => void;
+}
+export declare function createDiagnosticsStore(): DiagnosticsStore;
+/**
+ * The parts of an LSP `Diagnostic` the adapter reads (structurally typed, so no LSP library is
+ * needed). The element is taken from `data.elementId`, or MutRoSe's `data.nodeId`; the property
+ * from `data.key`.
+ */
+export interface LspDiagnosticLike {
+  readonly range?: DiagnosticRange;
+  /** LSP numbering: 1 error, 2 warning, 3 information, 4 hint. */
+  readonly severity?: number;
+  readonly message: string | {
+    readonly value: string;
+  };
+  readonly source?: string;
+  readonly code?: string | number | {
+    readonly value: string | number;
+  };
+  readonly data?: unknown;
+}
+export interface FromLspOptions<D extends LspDiagnosticLike = LspDiagnosticLike> {
+  /**
+   * The element of a diagnostic whose `data` names none, e.g. by looking its range up in the
+   * document. Return `undefined` to drop it.
+   */
+  readonly elementIdFor?: (diagnostic: D) => string | undefined;
+  /**
+   * `'vscode'` for `vscode.Diagnostic` objects, whose severity counts from 0 (error) to 3
+   * (hint). Default `'lsp'`, the protocol's 1 to 4.
+   */
+  readonly severityNumbering?: "lsp" | "vscode";
+}
+/**
+ * One LSP diagnostic anchored by `data.elementId` (or `data.nodeId`), or `undefined` when it
+ * names no element. For range-anchored diagnostics use `fromLspDiagnostics` with `elementIdFor`.
+ */
+export declare function fromLspDiagnostic(diagnostic: LspDiagnosticLike): GoalDiagnostic | undefined;
+/** LSP diagnostics as goal diagnostics; those that can't be anchored to an element are dropped. */
+export declare function fromLspDiagnostics<D extends LspDiagnosticLike>(diagnostics: readonly D[], options?: FromLspOptions<D>): GoalDiagnostic[];
+/**
+ * The shape MutRoSe's VS Code extension posts to its webview: `{ nodeId, severity, message }`
+ * (plus `range` and `source`). `nodeId` is missing when no node could be found.
+ */
+export interface NodeIdDiagnostic {
+  readonly nodeId?: string;
+  readonly key?: string;
+  readonly severity: DiagnosticSeverity | string;
+  readonly message: string;
+  readonly source?: string;
+  readonly range?: DiagnosticRange;
+  readonly code?: string;
+}
+/** One `{ nodeId, severity, message }` diagnostic, or `undefined` without a `nodeId`. */
+export declare function fromNodeIdDiagnostic(diagnostic: NodeIdDiagnostic): GoalDiagnostic | undefined;
+/**
+ * `{ nodeId, severity, message }` diagnostics (MutRoSe) as goal diagnostics, dropping those
+ * without a node: `store.publish('mutrose', fromNodeIdDiagnostics(message.diagnostics))`.
+ */
+export declare function fromNodeIdDiagnostics(diagnostics: readonly NodeIdDiagnostic[]): GoalDiagnostic[];
 declare namespace operations_d_exports {
-  export { AddDependencyResult, ConnectOptions, ConnectResult, ElementPatch, IdGenerator, LinkPatch, ModelOperationError, NewDependency, NewElement, NewLink, OperationContext, addDependency, addElement, addLeg, connect, defaultIdGenerator, dependencyEnds, disconnect, moveElement, nestElement, removeElement, removeElements, removeLeg, updateDiagram, updateElement, updateLink };
+  export { AddDependencyResult, ConnectOptions, ConnectResult, ElementPatch, IdGenerator, LinkPatch, ModelOperationError, NewDependency, NewElement, NewLink, OperationContext, addDependency, addElement, addLeg, connect, connectResultToDiagnostic, defaultIdGenerator, dependencyEnds, disconnect, moveElement, nestElement, removeElement, removeElements, removeLeg, updateDiagram, updateElement, updateLink };
 }
 export declare class ModelOperationError extends Error {
   override name: string;
+  /** The element or link the error is about, when the operation named one. */
+  readonly elementId?: string;
+  constructor(message: string, elementId?: string);
+  /** As a `GoalDiagnostic`, anchored on `elementId` (empty string if the error names none). */
+  toDiagnostic(): GoalDiagnostic;
 }
 /** Generates ids for new elements and links. piStar uses UUID v4. */
 export type IdGenerator = () => string;
@@ -873,11 +1057,22 @@ export interface NewLink<K extends string = LinkKind> {
   readonly source: string;
   /** An element id, or a link id for kinds whose rules target links. */
   readonly target: string;
+  /**
+   * The new link's id: for an n-ary kind whose target is not yet a hub, the new hub's; for an
+   * n-ary kind whose target already is a hub, the new leg's (same as `legId` there).
+   */
   readonly id?: string;
   /** Contribution value: make, help, hurt or break. */
   readonly label?: string;
   readonly name?: string;
   readonly customProperties?: CustomProperties;
+  /**
+   * The id of the leg it creates: for a target that is not yet a hub, the new leg from `source`;
+   * for a target that already is a hub, the new leg instead of `id`.
+   */
+  readonly legId?: string;
+  /** For an n-ary kind whose target is not yet a hub: the id of the end it creates. */
+  readonly endId?: string;
 }
 export interface ConnectOptions extends OperationContext {
   /** Skip constraint checking (used when loading or scripting known-good data). */
@@ -899,13 +1094,23 @@ export type ConnectResult<EK extends string = ElementKind, LK extends string = L
 } | Extract<LinkCheck, {
   ok: false;
 }>;
+/**
+ * Maps a failing `connect` result to a `GoalDiagnostic`, anchored on the end named by the
+ * `LinkCheck`'s `end` field (`target` when a check doesn't single out one end, such as
+ * `self-link` or `actor-types-differ`). `undefined` for a successful result.
+ */
+export declare function connectResultToDiagnostic<EK extends string = ElementKind, LK extends string = LinkKind>(result: ConnectResult<EK, LK>, endpoints: {
+  readonly source: string;
+  readonly target: string;
+}): GoalDiagnostic | undefined;
 /**
  * Adds a link between two elements if the iStar constraints allow it.
  *
  * With an n-ary kind (`arity: 'n'`), a `target` that is one of the kind's hubs gets a new leg
- * from `source` (see `addLeg`). Any other target gets a new hub, centred between source and
- * target, with a leg from `source` and an end to `target`. `input.id` and `customProperties`
- * then go to the hub, and `label` and `name` to the end.
+ * from `source` (see `addLeg`), taking `input.id` or `input.legId` (default a fresh id) as the
+ * leg's id. Any other target gets a new hub, centred between source and target, with a leg from
+ * `source` and an end to `target`. `input.id` and `customProperties` then go to the hub, `label`
+ * and `name` to the end, and `legId`/`endId` (default fresh ids) to the leg and end.
  */
 export declare function connect<EK extends string = ElementKind, LK extends string = LinkKind>(model: IstarModel<EK, LK>, input: NewLink<LK>, options?: ConnectOptions): ConnectResult<EK, LK>;
 /**
@@ -1170,137 +1375,43 @@ export declare function defineProperties<const S extends PropertyShape, const Ki
 }): PropertySchema<S, Kind>;
 export declare function validateModelProperties<EK extends string, LK extends string>(model: IstarModel<EK, LK>, schemas: readonly PropertySchema<PropertyShape, string>[]): ModelPropertyIssue[];
 //#endregion
-//#region src/diagnostics.d.ts
-/**
- * The Goal Model Diagnostics Protocol: findings about a model's elements and links, published by
- * any analyser (a language server, a validator, a simulation…) and anchored by element id rather
- * than by text position. Data only: diagnostics are never part of the model and are never
- * written to disk.
- *
- * See goal-controller issue #24 (option D). Producers publish per source; consumers see the
- * union of every source, deduplicated by `(elementId, key, message)`.
- */
-export type DiagnosticSeverity = "error" | "warning" | "info" | "hint";
-/** Most severe first. */
-export declare const DIAGNOSTIC_SEVERITIES: readonly DiagnosticSeverity[];
-/** A zero-based position in the producer's document (as in LSP). */
-export interface DiagnosticPosition {
-  readonly line: number;
-  readonly character: number;
-}
-export interface DiagnosticRange {
-  readonly start: DiagnosticPosition;
-  readonly end: DiagnosticPosition;
-}
-export interface GoalDiagnostic {
-  /** Id of the element or link the diagnostic is about. */
-  readonly elementId: string;
-  /** The custom property it is about; absent for the element as a whole. */
-  readonly key?: string;
-  readonly severity: DiagnosticSeverity;
-  readonly message: string;
-  /** Who published it (e.g. `mutrose`, `goal-language`). */
-  readonly source?: string;
-  /** Where it was found in the producer's document, if it has one. */
-  readonly range?: DiagnosticRange;
-  readonly code?: string;
-  /** Producer data, passed through untouched. */
-  readonly data?: unknown;
-}
-/** Negative when `a` is more severe than `b`. */
-export declare function compareSeverity(a: DiagnosticSeverity, b: DiagnosticSeverity): number;
-/** The most severe severity in a list (what a badge shows), or `undefined` if it is empty. */
-export declare function worstDiagnosticSeverity(diagnostics: readonly {
-  readonly severity: DiagnosticSeverity;
-}[] | undefined): DiagnosticSeverity | undefined;
-/**
- * The union of several lists, in order, without duplicates: diagnostics with the same
- * `(elementId, key, message)` count once, keeping the first one's position and the most severe
- * severity among them.
- */
-export declare function mergeDiagnostics(lists: Iterable<readonly GoalDiagnostic[] | undefined>): GoalDiagnostic[];
-/** Diagnostics by element (or link) id, each list in the input order. */
-export declare function groupDiagnostics(diagnostics: readonly GoalDiagnostic[] | undefined): ReadonlyMap<string, readonly GoalDiagnostic[]>;
-/**
- * Holds the diagnostics of several sources. Each `publish` replaces that source's set, so a
- * producer re-publishes everything it currently reports, as an LSP server does.
- */
-export interface DiagnosticsStore {
-  /**
-   * Replaces `source`'s diagnostics (an empty list clears them). Entries without a `source` get
-   * this one.
-   */
-  publish(source: string, diagnostics: readonly GoalDiagnostic[]): void;
-  /** Removes one source's diagnostics, or every source's. */
-  clear(source?: string): void;
-  /** Sources with diagnostics, in the order they first published. */
-  sources(): readonly string[];
-  /** One source's diagnostics. */
-  get(source: string): readonly GoalDiagnostic[];
-  /**
-   * Every source's diagnostics, merged (see `mergeDiagnostics`). The same array until the next
-   * change, so it can back `useSyncExternalStore`.
-   */
-  getAll(): readonly GoalDiagnostic[];
-  subscribe(listener: () => void): () => void;
-}
-export declare function createDiagnosticsStore(): DiagnosticsStore;
-/**
- * The parts of an LSP `Diagnostic` the adapter reads (structurally typed, so no LSP library is
- * needed). The element is taken from `data.elementId`, or MutRoSe's `data.nodeId`; the property
- * from `data.key`.
- */
-export interface LspDiagnosticLike {
-  readonly range?: DiagnosticRange;
-  /** LSP numbering: 1 error, 2 warning, 3 information, 4 hint. */
-  readonly severity?: number;
-  readonly message: string | {
-    readonly value: string;
-  };
-  readonly source?: string;
-  readonly code?: string | number | {
-    readonly value: string | number;
-  };
-  readonly data?: unknown;
-}
-export interface FromLspOptions<D extends LspDiagnosticLike = LspDiagnosticLike> {
-  /**
-   * The element of a diagnostic whose `data` names none, e.g. by looking its range up in the
-   * document. Return `undefined` to drop it.
-   */
-  readonly elementIdFor?: (diagnostic: D) => string | undefined;
-  /**
-   * `'vscode'` for `vscode.Diagnostic` objects, whose severity counts from 0 (error) to 3
-   * (hint). Default `'lsp'`, the protocol's 1 to 4.
-   */
-  readonly severityNumbering?: "lsp" | "vscode";
-}
-/**
- * One LSP diagnostic anchored by `data.elementId` (or `data.nodeId`), or `undefined` when it
- * names no element. For range-anchored diagnostics use `fromLspDiagnostics` with `elementIdFor`.
- */
-export declare function fromLspDiagnostic(diagnostic: LspDiagnosticLike): GoalDiagnostic | undefined;
-/** LSP diagnostics as goal diagnostics; those that can't be anchored to an element are dropped. */
-export declare function fromLspDiagnostics<D extends LspDiagnosticLike>(diagnostics: readonly D[], options?: FromLspOptions<D>): GoalDiagnostic[];
-/**
- * The shape MutRoSe's VS Code extension posts to its webview: `{ nodeId, severity, message }`
- * (plus `range` and `source`). `nodeId` is missing when no node could be found.
- */
-export interface NodeIdDiagnostic {
-  readonly nodeId?: string;
-  readonly key?: string;
-  readonly severity: DiagnosticSeverity | string;
-  readonly message: string;
-  readonly source?: string;
-  readonly range?: DiagnosticRange;
-  readonly code?: string;
+//#region src/palette.d.ts
+export interface PaletteEntryDescription {
+  readonly label: string;
+  /** Lower comes first. */
+  readonly order?: number;
+  /** Entries sharing a group collapse into one dropdown button (e.g. Actor / Agent / Role). */
+  readonly group?: string;
+  /** Sections are separated by a divider. Default palette: "actors" and "elements". */
+  readonly section?: string;
+}
+export interface ElementToolEntryDescription extends PaletteEntryDescription {
+  /** customProperties preset on the element this entry creates, over `defaultProperties`. */
+  readonly properties?: CustomProperties;
+}
+export interface LinkToolEntryDescription<DK extends string = NodeKind> extends PaletteEntryDescription {
+  /** Contribution value to set on the new link. */
+  readonly value?: string;
+  /** For dependencies: the kind of dependum to create. */
+  readonly dependum?: DK;
+}
+export interface PaletteGroupDescription {
+  readonly label: string;
 }
-/** One `{ nodeId, severity, message }` diagnostic, or `undefined` without a `nodeId`. */
-export declare function fromNodeIdDiagnostic(diagnostic: NodeIdDiagnostic): GoalDiagnostic | undefined;
 /**
- * `{ nodeId, severity, message }` diagnostics (MutRoSe) as goal diagnostics, dropping those
- * without a node: `store.publish('mutrose', fromNodeIdDiagnostics(message.diagnostics))`.
+ * Per-kind palette data. `elements`/`links` entries are `false` for kinds hidden from the
+ * palette, one entry for most element kinds, or several for a kind with more than one toolbar
+ * button (a link's values, a dependency's dependum kinds).
  */
-export declare function fromNodeIdDiagnostics(diagnostics: readonly NodeIdDiagnostic[]): GoalDiagnostic[];
+export interface PaletteDescription<EK extends string = ElementKind, LK extends string = LinkKind> {
+  readonly elements: Readonly<Record<EK, PaletteEntryDescription | readonly ElementToolEntryDescription[] | false>>;
+  readonly links: Readonly<Record<LK, readonly LinkToolEntryDescription[] | false>>;
+  /** Labels for palette groups, keyed by `PaletteEntryDescription.group`. */
+  readonly groups: Readonly<Record<string, PaletteGroupDescription>>;
+}
+/** A palette description of any dialect, for code that handles every kind generically. */
+export type AnyPaletteDescription = PaletteDescription<string, string>;
+/** The palette data of iStar 2.0, as piStar's toolbar presents it. */
+export declare const DEFAULT_PALETTE: PaletteDescription;
 //#endregion
 //# sourceMappingURL=index.d.cts.map