@istar-ts/core 0.10.0 → 0.11.0

package/dist/index.d.cts

@@ -128,6 +128,25 @@ export declare function validateModel(model: IstarModel): ModelIssue[];
 //#endregion
 //#region src/metamodels.d.ts
 export type ElementCategory = "actor" | "node";
+/**
+ * Presentation hints a kind may carry, as data (core never draws). `@istar-ts/react` uses them as
+ * the defaults for the kind: a shape as SVG path data, the label's text box, a link's line.
+ */
+export interface KindShape {
+  readonly path: string;
+  readonly viewBox?: string;
+}
+export interface KindTextBox {
+  readonly top: number;
+  readonly right: number;
+  readonly bottom: number;
+  readonly left: number;
+}
+export interface KindLine {
+  readonly dash?: string;
+  readonly marker?: string | false;
+  readonly markerFilled?: boolean;
+}
 export type LinkCategory = "actor" | "node" | "dependency";
 /** A resolved element kind of a metamodel. */
 export interface ElementKindDefinition<K extends string = string> {
@@ -145,6 +164,9 @@ export interface ElementKindDefinition<K extends string = string> {
   readonly pistarType: string;
   /** Name of the extension that declared it; absent for iStar 2.0 kinds. */
   readonly extension?: string;
+  /** Presentation hints (drawn by `@istar-ts/react`). */
+  readonly shape?: KindShape;
+  readonly textBox?: KindTextBox;
 }
 /**
  * Declarative link rules, as piStar-ext's "Create a new Construct" dialog collects them:
@@ -184,6 +206,8 @@ export interface LinkKindDefinition<K extends string = string> {
   readonly check?: (context: LinkRuleContext) => LinkCheck;
   readonly pistarType: string;
   readonly extension?: string;
+  /** Presentation hint (drawn by `@istar-ts/react`). */
+  readonly line?: KindLine;
 }
 /** A metamodel: the element and link kinds a model may use, and their rules. */
 export interface Metamodel<EK extends string = ElementKind, LK extends string = LinkKind> {
@@ -222,6 +246,9 @@ export interface ElementKindDeclaration<K extends string = string> {
    * constructs as `istar.<Name>`, so `pistarType: 'istar.Planning'` reads its files.
    */
   readonly pistarType?: string;
+  /** Presentation hints, kept as data for renderers (`@istar-ts/react` draws them). */
+  readonly shape?: KindShape;
+  readonly textBox?: KindTextBox;
 }
 export interface LinkKindDeclaration<K extends string = string> {
   readonly kind: K;
@@ -237,6 +264,8 @@ export interface LinkKindDeclaration<K extends string = string> {
   /** Default: that of `behavesLike`, else none (no fixed label, no changeable value). */
   readonly info?: LinkKindInfo;
   readonly pistarType?: string;
+  /** Presentation hint, kept as data for renderers (`@istar-ts/react` draws it). */
+  readonly line?: KindLine;
 }
 /** A named set of new kinds, applied to a metamodel with `extendMetamodel`. */
 export interface MetamodelExtension<NEK extends string = string, NLK extends string = string> {
@@ -381,6 +410,10 @@ export type AnyIstarModel = IstarModel<string, string>;
  * the association.
  */
 export declare function withMetamodel<EK extends string, LK extends string>(model: IstarModel<string, string>, metamodel: Metamodel<EK, LK>): IstarModel<EK, LK>;
+/** @internal Records the host part of a model's metamodel (used by serialization). */
+export declare function setHostMetamodel(model: object, metamodel: AnyMetamodel | undefined): void;
+/** @internal The host part of a model's metamodel, if the file declares the rest. */
+export declare function hostMetamodelOf(model: object): AnyMetamodel | undefined;
 /** Gives `to` the metamodel of `from` (used for every model an operation derives). */
 export declare function inheritMetamodel<M extends IstarModel<string, string>>(from: IstarModel<string, string>, to: M): M;
 export declare function createEmptyModel<EK extends string, LK extends string>(diagram: Diagram | undefined, options: {
@@ -416,6 +449,38 @@ export declare function dependencyLinksOf<EK extends string, LK extends string>(
   outbound?: IstarLink<LK>;
 };
 //#endregion
+//#region src/file-metamodel.d.ts
+/** The top-level key of the block in piStar JSON. */
+export declare const FILE_METAMODEL_KEY = "metamodel";
+export interface FileElementKind extends Omit<ElementKindDeclaration<string>, "info"> {
+  readonly info?: {
+    readonly canBeInnerElement?: boolean;
+    readonly canBeDependum?: boolean;
+    readonly canBeOnPaper?: boolean;
+  };
+  readonly [key: string]: unknown;
+}
+export interface FileLinkKind extends Omit<LinkKindDeclaration<string>, "check"> {
+  readonly [key: string]: unknown;
+}
+/** The `"metamodel"` block of a model file. */
+export interface FileMetamodel {
+  /** Identifies the constructs' dialect, e.g. `iStar4RationalAgents`. */
+  readonly name: string;
+  readonly elements?: readonly FileElementKind[];
+  readonly links?: readonly FileLinkKind[];
+  readonly [key: string]: unknown;
+}
+/**
+ * Checks that `value` is a well-formed `"metamodel"` block and returns it typed. Throws
+ * `MetamodelError` naming the offending path (`metamodel.elements[1].kind must be a string`).
+ * Whether its kinds fit a given metamodel (namespacing, collisions, `behavesLike` targets) is
+ * checked when it is applied, by `extendMetamodel`.
+ */
+export declare function validateFileMetamodel(value: unknown, path?: string): FileMetamodel;
+/** The block as an extension `extendMetamodel` applies (it ignores the extra keys). */
+export declare function fileMetamodelExtension(block: FileMetamodel): MetamodelExtension<string, string>;
+//#endregion
 //#region src/serialization.d.ts
 export interface PistarElementJson {
   id: string;
@@ -494,12 +559,21 @@ export declare function inheritSourceLayout<M extends IstarModel<string, string>
  * `if (element.x && element.y)` silently drops them, which looks unintended.
  */
 export interface ParsePistarOptions<EK extends string = ElementKind, LK extends string = LinkKind> {
+  /**
+   * Read the file's own `"metamodel"` block (see `FileMetamodel`) and parse with `metamodel`
+   * (or iStar 2.0) extended by it. Default false: the block is kept as an unknown key and not
+   * applied, as before. A block whose kinds collide with the metamodel throws `MetamodelError`.
+   */
+  readonly fileMetamodel?: boolean;
   /**
    * The metamodel whose kinds the file may use. Default iStar 2.0: any other `type` throws,
    * as in the piStar tool. The parsed model remembers it (see `metamodelOf`).
    */
   readonly metamodel?: Metamodel<EK, LK>;
 }
+export declare function parsePistar(input: string | PistarFile | Record<string, unknown>, options: ParsePistarOptions<string, string> & {
+  readonly fileMetamodel: true;
+}): IstarModel<string, string>;
 export declare function parsePistar<EK extends string, LK extends string>(input: string | PistarFile | Record<string, unknown>, options: ParsePistarOptions<EK, LK> & {
   readonly metamodel: Metamodel<EK, LK>;
 }): IstarModel<EK, LK>;
@@ -519,6 +593,19 @@ export interface ToPistarOptions {
 export declare function toPistarObject<EK extends string, LK extends string>(input: IstarModel<EK, LK>, options?: ToPistarOptions): PistarFile;
 /** Serializes a model to piStar's JSON text (2-space indentation, no trailing newline). */
 export declare function toPistar<EK extends string, LK extends string>(model: IstarModel<EK, LK>, options?: ToPistarOptions): string;
+/**
+ * The constructs the model's file declares in its `"metamodel"` block, when they were applied
+ * (read with `fileMetamodel: true`, or set with `withFileMetamodel`); `undefined` otherwise.
+ * Kinds the host supplied are never part of it.
+ */
+export declare function fileMetamodelOf<EK extends string, LK extends string>(model: IstarModel<EK, LK>): FileMetamodel | undefined;
+/**
+ * A copy of `model` whose file declares `block` (`null` removes the block): its metamodel is the
+ * host's extended by `block`, and `toPistar` writes the block. This is how a tool's "Add new"
+ * construct joins a model. Throws `MetamodelError` if the block is malformed, collides with the
+ * 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>;
 declare namespace operations_d_exports {
   export { AddDependencyResult, ConnectOptions, ConnectResult, ElementPatch, IdGenerator, LinkPatch, ModelOperationError, NewDependency, NewElement, NewLink, OperationContext, addDependency, addElement, connect, defaultIdGenerator, dependencyEnds, disconnect, moveElement, nestElement, removeElement, removeElements, updateDiagram, updateElement, updateLink };
 }

package/dist/index.d.ts

@@ -128,6 +128,25 @@ export declare function validateModel(model: IstarModel): ModelIssue[];
 //#endregion
 //#region src/metamodels.d.ts
 export type ElementCategory = "actor" | "node";
+/**
+ * Presentation hints a kind may carry, as data (core never draws). `@istar-ts/react` uses them as
+ * the defaults for the kind: a shape as SVG path data, the label's text box, a link's line.
+ */
+export interface KindShape {
+  readonly path: string;
+  readonly viewBox?: string;
+}
+export interface KindTextBox {
+  readonly top: number;
+  readonly right: number;
+  readonly bottom: number;
+  readonly left: number;
+}
+export interface KindLine {
+  readonly dash?: string;
+  readonly marker?: string | false;
+  readonly markerFilled?: boolean;
+}
 export type LinkCategory = "actor" | "node" | "dependency";
 /** A resolved element kind of a metamodel. */
 export interface ElementKindDefinition<K extends string = string> {
@@ -145,6 +164,9 @@ export interface ElementKindDefinition<K extends string = string> {
   readonly pistarType: string;
   /** Name of the extension that declared it; absent for iStar 2.0 kinds. */
   readonly extension?: string;
+  /** Presentation hints (drawn by `@istar-ts/react`). */
+  readonly shape?: KindShape;
+  readonly textBox?: KindTextBox;
 }
 /**
  * Declarative link rules, as piStar-ext's "Create a new Construct" dialog collects them:
@@ -184,6 +206,8 @@ export interface LinkKindDefinition<K extends string = string> {
   readonly check?: (context: LinkRuleContext) => LinkCheck;
   readonly pistarType: string;
   readonly extension?: string;
+  /** Presentation hint (drawn by `@istar-ts/react`). */
+  readonly line?: KindLine;
 }
 /** A metamodel: the element and link kinds a model may use, and their rules. */
 export interface Metamodel<EK extends string = ElementKind, LK extends string = LinkKind> {
@@ -222,6 +246,9 @@ export interface ElementKindDeclaration<K extends string = string> {
    * constructs as `istar.<Name>`, so `pistarType: 'istar.Planning'` reads its files.
    */
   readonly pistarType?: string;
+  /** Presentation hints, kept as data for renderers (`@istar-ts/react` draws them). */
+  readonly shape?: KindShape;
+  readonly textBox?: KindTextBox;
 }
 export interface LinkKindDeclaration<K extends string = string> {
   readonly kind: K;
@@ -237,6 +264,8 @@ export interface LinkKindDeclaration<K extends string = string> {
   /** Default: that of `behavesLike`, else none (no fixed label, no changeable value). */
   readonly info?: LinkKindInfo;
   readonly pistarType?: string;
+  /** Presentation hint, kept as data for renderers (`@istar-ts/react` draws it). */
+  readonly line?: KindLine;
 }
 /** A named set of new kinds, applied to a metamodel with `extendMetamodel`. */
 export interface MetamodelExtension<NEK extends string = string, NLK extends string = string> {
@@ -381,6 +410,10 @@ export type AnyIstarModel = IstarModel<string, string>;
  * the association.
  */
 export declare function withMetamodel<EK extends string, LK extends string>(model: IstarModel<string, string>, metamodel: Metamodel<EK, LK>): IstarModel<EK, LK>;
+/** @internal Records the host part of a model's metamodel (used by serialization). */
+export declare function setHostMetamodel(model: object, metamodel: AnyMetamodel | undefined): void;
+/** @internal The host part of a model's metamodel, if the file declares the rest. */
+export declare function hostMetamodelOf(model: object): AnyMetamodel | undefined;
 /** Gives `to` the metamodel of `from` (used for every model an operation derives). */
 export declare function inheritMetamodel<M extends IstarModel<string, string>>(from: IstarModel<string, string>, to: M): M;
 export declare function createEmptyModel<EK extends string, LK extends string>(diagram: Diagram | undefined, options: {
@@ -416,6 +449,38 @@ export declare function dependencyLinksOf<EK extends string, LK extends string>(
   outbound?: IstarLink<LK>;
 };
 //#endregion
+//#region src/file-metamodel.d.ts
+/** The top-level key of the block in piStar JSON. */
+export declare const FILE_METAMODEL_KEY = "metamodel";
+export interface FileElementKind extends Omit<ElementKindDeclaration<string>, "info"> {
+  readonly info?: {
+    readonly canBeInnerElement?: boolean;
+    readonly canBeDependum?: boolean;
+    readonly canBeOnPaper?: boolean;
+  };
+  readonly [key: string]: unknown;
+}
+export interface FileLinkKind extends Omit<LinkKindDeclaration<string>, "check"> {
+  readonly [key: string]: unknown;
+}
+/** The `"metamodel"` block of a model file. */
+export interface FileMetamodel {
+  /** Identifies the constructs' dialect, e.g. `iStar4RationalAgents`. */
+  readonly name: string;
+  readonly elements?: readonly FileElementKind[];
+  readonly links?: readonly FileLinkKind[];
+  readonly [key: string]: unknown;
+}
+/**
+ * Checks that `value` is a well-formed `"metamodel"` block and returns it typed. Throws
+ * `MetamodelError` naming the offending path (`metamodel.elements[1].kind must be a string`).
+ * Whether its kinds fit a given metamodel (namespacing, collisions, `behavesLike` targets) is
+ * checked when it is applied, by `extendMetamodel`.
+ */
+export declare function validateFileMetamodel(value: unknown, path?: string): FileMetamodel;
+/** The block as an extension `extendMetamodel` applies (it ignores the extra keys). */
+export declare function fileMetamodelExtension(block: FileMetamodel): MetamodelExtension<string, string>;
+//#endregion
 //#region src/serialization.d.ts
 export interface PistarElementJson {
   id: string;
@@ -494,12 +559,21 @@ export declare function inheritSourceLayout<M extends IstarModel<string, string>
  * `if (element.x && element.y)` silently drops them, which looks unintended.
  */
 export interface ParsePistarOptions<EK extends string = ElementKind, LK extends string = LinkKind> {
+  /**
+   * Read the file's own `"metamodel"` block (see `FileMetamodel`) and parse with `metamodel`
+   * (or iStar 2.0) extended by it. Default false: the block is kept as an unknown key and not
+   * applied, as before. A block whose kinds collide with the metamodel throws `MetamodelError`.
+   */
+  readonly fileMetamodel?: boolean;
   /**
    * The metamodel whose kinds the file may use. Default iStar 2.0: any other `type` throws,
    * as in the piStar tool. The parsed model remembers it (see `metamodelOf`).
    */
   readonly metamodel?: Metamodel<EK, LK>;
 }
+export declare function parsePistar(input: string | PistarFile | Record<string, unknown>, options: ParsePistarOptions<string, string> & {
+  readonly fileMetamodel: true;
+}): IstarModel<string, string>;
 export declare function parsePistar<EK extends string, LK extends string>(input: string | PistarFile | Record<string, unknown>, options: ParsePistarOptions<EK, LK> & {
   readonly metamodel: Metamodel<EK, LK>;
 }): IstarModel<EK, LK>;
@@ -519,6 +593,19 @@ export interface ToPistarOptions {
 export declare function toPistarObject<EK extends string, LK extends string>(input: IstarModel<EK, LK>, options?: ToPistarOptions): PistarFile;
 /** Serializes a model to piStar's JSON text (2-space indentation, no trailing newline). */
 export declare function toPistar<EK extends string, LK extends string>(model: IstarModel<EK, LK>, options?: ToPistarOptions): string;
+/**
+ * The constructs the model's file declares in its `"metamodel"` block, when they were applied
+ * (read with `fileMetamodel: true`, or set with `withFileMetamodel`); `undefined` otherwise.
+ * Kinds the host supplied are never part of it.
+ */
+export declare function fileMetamodelOf<EK extends string, LK extends string>(model: IstarModel<EK, LK>): FileMetamodel | undefined;
+/**
+ * A copy of `model` whose file declares `block` (`null` removes the block): its metamodel is the
+ * host's extended by `block`, and `toPistar` writes the block. This is how a tool's "Add new"
+ * construct joins a model. Throws `MetamodelError` if the block is malformed, collides with the
+ * 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>;
 declare namespace operations_d_exports {
   export { AddDependencyResult, ConnectOptions, ConnectResult, ElementPatch, IdGenerator, LinkPatch, ModelOperationError, NewDependency, NewElement, NewLink, OperationContext, addDependency, addElement, connect, defaultIdGenerator, dependencyEnds, disconnect, moveElement, nestElement, removeElement, removeElements, updateDiagram, updateElement, updateLink };
 }