@likec4/core 1.17.1 → 1.19.0

package/src/types/relation.ts

@@ -2,9 +2,9 @@ import type { Tagged } from 'type-fest'
 import type { NonEmptyArray } from './_common'
 import type { Fqn, Link, Tag } from './element'
 import type { Color, ThemeColor } from './theme'
-import type { ViewID } from './view'
+import type { ViewId } from './view'
 
-export type RelationID = Tagged<string, 'RelationID'>
+export type RelationId = Tagged<string, 'RelationID'>
 export type RelationshipKind<Kinds extends string = string> = Tagged<Kinds, 'RelationshipKind'>
 
 export type RelationshipLineType = 'dashed' | 'solid' | 'dotted'
@@ -22,30 +22,34 @@ export type RelationshipArrowType =
   | 'open'
   | 'vee'
 
-export const DefaultLineStyle = 'dashed' satisfies RelationshipLineType
-export const DefaultArrowType = 'normal' satisfies RelationshipArrowType
-export const DefaultRelationshipColor = 'gray' satisfies ThemeColor
+export const DefaultLineStyle: RelationshipLineType = 'dashed'
+export const DefaultArrowType: RelationshipArrowType = 'normal'
+export const DefaultRelationshipColor: ThemeColor = 'gray'
 
-// TODO: rename to Relationship
-export interface Relation {
-  readonly id: RelationID
-  readonly source: Fqn
-  readonly target: Fqn
-  readonly title: string
+export interface AbstractRelation {
+  readonly id: RelationId
+  readonly title?: string
   readonly description?: string
   readonly technology?: string
-  readonly tags?: NonEmptyArray<Tag>
+  readonly tags?: NonEmptyArray<Tag> | null
   readonly kind?: RelationshipKind
   readonly color?: Color
   readonly line?: RelationshipLineType
   readonly head?: RelationshipArrowType
   readonly tail?: RelationshipArrowType
-  readonly links?: NonEmptyArray<Link>
+  readonly links?: NonEmptyArray<Link> | null
   // Link to dynamic view
-  readonly navigateTo?: ViewID
+  readonly navigateTo?: ViewId
   readonly metadata?: { [key: string]: string }
 }
 
+// TODO: rename to Relationship
+export interface ModelRelation extends AbstractRelation {
+  readonly source: Fqn
+  readonly target: Fqn
+  readonly title: string
+}
+
 export interface RelationshipKindSpecification {
   readonly technology?: string
   readonly notation?: string

package/src/types/theme.ts

@@ -1,5 +1,4 @@
 import type { LiteralUnion } from 'type-fest'
-import type { CustomColor } from './_common'
 
 const ThemeColors = [
   'amber',

package/src/types/view-notation.ts

@@ -1,8 +1,8 @@
-import type { ElementKind, ElementShape } from './element'
+import type { ElementShape } from './element'
 import type { Color } from './theme'
 
 export type ElementNotation = {
-  kinds: ElementKind[]
+  kinds: string[]
   shape: ElementShape
   color: Color
   title: string

package/src/types/view.ts

@@ -8,15 +8,16 @@ import {
   type ElementStyle,
   type Fqn,
   type Link,
-  type Tag
+  type Tag,
 } from './element'
 import type { ElementExpression, ElementPredicateExpression, Expression } from './expression'
+import type { ExpressionV2, FqnExpr } from './expression-v2'
 import type { GlobalPredicateId, GlobalStyleID } from './global'
-import type { RelationID, RelationshipArrowType, RelationshipKind, RelationshipLineType } from './relation'
+import type { RelationId, RelationshipArrowType, RelationshipKind, RelationshipLineType } from './relation'
 import type { Color, ThemeColorValues } from './theme'
 import type { ElementNotation } from './view-notation'
 
-export type ViewID<Id extends string = string> = Tagged<Id, 'ViewID'>
+export type ViewId<Id extends string = string> = Tagged<Id, 'ViewID'>
 
 export type ViewRulePredicate =
   | {
@@ -27,7 +28,11 @@ export type ViewRulePredicate =
     include?: never
     exclude: Expression[]
   }
-export function isViewRulePredicate(rule: ViewRule): rule is ViewRulePredicate {
+
+export function isViewRulePredicate(rule: DeploymentViewRule): rule is DeploymentViewRulePredicate
+export function isViewRulePredicate(rule: DynamicViewRule): rule is DynamicViewIncludeRule
+export function isViewRulePredicate(rule: ViewRule): rule is ViewRulePredicate
+export function isViewRulePredicate(rule: object) {
   return (
     ('include' in rule && Array.isArray(rule.include))
     || ('exclude' in rule && Array.isArray(rule.exclude))
@@ -50,8 +55,10 @@ export interface ViewRuleStyle {
     icon?: IconUrl
   }
 }
-export function isViewRuleStyle(rule: ViewRule): rule is ViewRuleStyle {
-  return 'style' in rule && 'targets' in rule
+export function isViewRuleStyle(rule: DeploymentViewRule): rule is DeploymentViewRuleStyle
+export function isViewRuleStyle(rule: ViewRule): rule is ViewRuleStyle
+export function isViewRuleStyle(rule: object) {
+  return 'style' in rule && 'targets' in rule && Array.isArray(rule.targets)
 }
 
 export interface ViewRuleGlobalStyle {
@@ -73,7 +80,10 @@ export interface ViewRuleAutoLayout {
   nodeSep?: number
   rankSep?: number
 }
-export function isViewRuleAutoLayout(rule: ViewRule): rule is ViewRuleAutoLayout {
+
+export function isViewRuleAutoLayout(
+  rule: DeploymentViewRule | DynamicViewRule | ViewRule,
+): rule is ViewRuleAutoLayout {
   return 'direction' in rule
 }
 
@@ -99,12 +109,12 @@ export type ViewRule =
   | ViewRuleAutoLayout
 
 export interface BasicView<
-  ViewType extends 'element' | 'dynamic',
+  ViewType extends 'element' | 'dynamic' | 'deployment',
   ViewIDs extends string,
-  Tags extends string
+  Tags extends string,
 > {
   readonly __?: ViewType
-  readonly id: ViewID<ViewIDs>
+  readonly id: ViewId<ViewIDs>
   readonly title: string | null
   readonly description: string | null
   readonly tags: NonEmptyArray<Tag<Tags>> | null
@@ -148,11 +158,11 @@ export interface ScopedElementView<ViewIDs extends string, Tags extends string>
 export interface ExtendsElementView<ViewIDs extends string, Tags extends string>
   extends BasicElementView<ViewIDs, Tags>
 {
-  readonly extends: ViewID<ViewIDs>
+  readonly extends: ViewId<ViewIDs>
 }
 export type ElementView<
   ViewIDs extends string = string,
-  Tags extends string = string
+  Tags extends string = string,
 > =
   | ScopedElementView<ViewIDs, Tags>
   | ExtendsElementView<ViewIDs, Tags>
@@ -173,7 +183,7 @@ export interface DynamicViewStep {
   readonly tail?: RelationshipArrowType
   readonly isBackward?: boolean
   // Link to dynamic view
-  readonly navigateTo?: ViewID
+  readonly navigateTo?: ViewId
   __parallel?: never
 }
 
@@ -187,10 +197,6 @@ export type DynamicViewIncludeRule = {
   include: ElementPredicateExpression[]
 }
 
-export function isDynamicViewIncludeRule(rule: DynamicViewRule): rule is DynamicViewIncludeRule {
-  return 'include' in rule && Array.isArray(rule.include)
-}
-
 export type DynamicViewRule =
   | DynamicViewIncludeRule
   | ViewRuleGlobalPredicateRef
@@ -199,7 +205,7 @@ export type DynamicViewRule =
   | ViewRuleAutoLayout
 export interface DynamicView<
   ViewIDs extends string = string,
-  Tags extends string = string
+  Tags extends string = string,
 > extends BasicView<'dynamic', ViewIDs, Tags> {
   readonly __: 'dynamic'
 
@@ -214,14 +220,49 @@ export function isDynamicViewParallelSteps(step: DynamicViewStepOrParallel): ste
 
 export type CustomColorDefinitions = { [key: string]: ThemeColorValues }
 
+export type DeploymentViewRulePredicate =
+  | {
+    include: ExpressionV2[]
+    exclude?: never
+  }
+  | {
+    include?: never
+    exclude: ExpressionV2[]
+  }
+export type DeploymentViewRuleStyle = {
+  targets: FqnExpr[]
+  notation?: string
+  style: ElementStyle & {
+    color?: Color
+    shape?: ElementShape
+    icon?: IconUrl
+  }
+}
+export type DeploymentViewRule = DeploymentViewRulePredicate | ViewRuleAutoLayout | DeploymentViewRuleStyle
+
+export interface DeploymentView<
+  ViewIDs extends string = string,
+  Tags extends string = string,
+> extends BasicView<'deployment', ViewIDs, Tags> {
+  readonly __: 'deployment'
+  readonly rules: DeploymentViewRule[]
+}
+
 export type LikeC4View<
   ViewIDs extends string = string,
-  Tags extends string = string
-> = ElementView<ViewIDs, Tags> | DynamicView<ViewIDs, Tags>
+  Tags extends string = string,
+> = ElementView<ViewIDs, Tags> | DynamicView<ViewIDs, Tags> | DeploymentView<ViewIDs, Tags>
+
+export function isDeploymentView(view: LikeC4View): view is DeploymentView
+export function isDeploymentView<V extends { __?: string }>(view: V): boolean
+export function isDeploymentView(view: LikeC4View): view is DeploymentView {
+  return view.__ === 'deployment'
+}
 
 export function isDynamicView(view: LikeC4View): view is DynamicView {
   return view.__ === 'dynamic'
 }
+
 export function isElementView(view: LikeC4View): view is ElementView {
   return isNullish(view.__) || view.__ === 'element'
 }
@@ -239,7 +280,7 @@ export type NodeId<IDs extends string = string> = Tagged<IDs, 'Fqn'>
 export type EdgeId = Tagged<string, 'EdgeId'>
 export type StepEdgeIdLiteral = `step-${number}` | `step-${number}.${number}`
 export type StepEdgeId = Tagged<StepEdgeIdLiteral, 'EdgeId'>
-export function StepEdgeId(step: number, parallelStep?: number): StepEdgeId {
+export function stepEdgeId(step: number, parallelStep?: number): StepEdgeId {
   const id = `step-${String(step).padStart(2, '0')}` as StepEdgeId
   return parallelStep ? `${id}.${parallelStep}` as StepEdgeId : id
 }
@@ -266,8 +307,18 @@ export function getParallelStepsPrefix(id: string): string | null {
 
 export interface ComputedNode {
   id: NodeId
-  kind: ElementKind
+  kind: string // TODO: fix ElementKind | DeploymentNodeKind
   parent: NodeId | null
+  /**
+   * Reference to model element
+   * If 1 - node id is a reference
+   */
+  modelRef?: 1 | Fqn
+  /**
+   * Reference to deployment element
+   * If 1 - node id is a reference
+   */
+  deploymentRef?: 1 | Fqn
   title: string
   description: string | null
   technology: string | null
@@ -278,16 +329,13 @@ export interface ComputedNode {
   inEdges: EdgeId[]
   outEdges: EdgeId[]
   shape: ElementShape
-  /**
-   * @deprecated Use `style` instead
-   */
   color: Color
   /**
    * @deprecated Use `style` instead
    */
   icon?: IconUrl
   style: ElementStyle
-  navigateTo?: ViewID
+  navigateTo?: ViewId
   level: number
   // For compound nodes, the max depth of nested nodes
   depth?: number
@@ -297,6 +345,12 @@ export interface ComputedNode {
   isCustomized?: boolean
 }
 export namespace ComputedNode {
+  export function modelRef(node: ComputedNode): Fqn | null {
+    return node.modelRef === 1 ? node.id : (node.modelRef ?? null)
+  }
+  export function deploymentRef(node: ComputedNode): Fqn | null {
+    return node.deploymentRef === 1 ? node.id : (node.deploymentRef ?? null)
+  }
   /**
    * Nodes group is a special kind of node, exisiting only in view
    */
@@ -313,7 +367,7 @@ export interface ComputedEdge {
   label: string | null
   description?: string
   technology?: string
-  relations: RelationID[]
+  relations: RelationId[]
   kind?: RelationshipKind
   notation?: string
   // Notes for walkthrough
@@ -324,7 +378,7 @@ export interface ComputedEdge {
   tail?: RelationshipArrowType
   tags?: NonEmptyArray<Tag>
   // Link to dynamic view
-  navigateTo?: ViewID
+  navigateTo?: ViewId
   /**
    * If this edge is derived from custom relationship predicate
    */
@@ -333,7 +387,7 @@ export interface ComputedEdge {
    * For layouting purposes
    * @default 'forward'
    */
-  dir?: 'forward' | 'back'
+  dir?: 'forward' | 'back' | 'both'
 }
 
 export interface ViewWithHash {
@@ -356,9 +410,9 @@ export interface ViewAutoLayout {
 }
 export interface ComputedElementView<
   ViewIDs extends string = string,
-  Tags extends string = string
+  Tags extends string = string,
 > extends Omit<ElementView<ViewIDs, Tags>, 'rules' | 'docUri'>, ViewWithHash, ViewWithNotation {
-  readonly extends?: ViewID<ViewIDs>
+  readonly extends?: ViewId<ViewIDs>
   readonly autoLayout: ViewAutoLayout
   readonly nodes: ComputedNode[]
   readonly edges: ComputedEdge[]
@@ -367,7 +421,7 @@ export interface ComputedElementView<
 }
 export interface ComputedDynamicView<
   ViewIDs extends string = string,
-  Tags extends string = string
+  Tags extends string = string,
 > extends Omit<DynamicView<ViewIDs, Tags>, 'rules' | 'steps' | 'docUri'>, ViewWithHash, ViewWithNotation {
   readonly autoLayout: ViewAutoLayout
   readonly nodes: ComputedNode[]
@@ -376,17 +430,33 @@ export interface ComputedDynamicView<
   rules?: never
   docUri?: never
 }
-export function isComputedDynamicView(view: ComputedView): view is ComputedDynamicView {
-  return view.__ === 'dynamic'
+
+export interface ComputedDeploymentView<
+  ViewIDs extends string = string,
+  Tags extends string = string,
+> extends Omit<DeploymentView<ViewIDs, Tags>, 'rules' | 'docUri'>, ViewWithHash, ViewWithNotation {
+  readonly autoLayout: ViewAutoLayout
+  readonly nodes: ComputedNode[]
+  readonly edges: ComputedEdge[]
+  rules?: never
+  docUri?: never
 }
 
 export type ComputedView<
   ViewIDs extends string = string,
-  Tags extends string = string
-> = ComputedElementView<ViewIDs, Tags> | ComputedDynamicView<ViewIDs, Tags>
+  Tags extends string = string,
+> = ComputedElementView<ViewIDs, Tags> | ComputedDynamicView<ViewIDs, Tags> | ComputedDeploymentView<ViewIDs, Tags>
 
-export function isComputedElementView(view: ComputedView): view is ComputedElementView {
-  return isNullish(view.__) || view.__ === 'element'
+export namespace ComputedView {
+  export function isDeployment(view: ComputedView): view is ComputedDeploymentView {
+    return view.__ === 'deployment'
+  }
+  export function isDynamic(view: ComputedView): view is ComputedDynamicView {
+    return view.__ === 'dynamic'
+  }
+  export function isElement(view: ComputedView): view is ComputedElementView {
+    return isNullish(view.__) || view.__ === 'element'
+  }
 }
 
 // Bounding box
@@ -401,11 +471,11 @@ export function getBBoxCenter({
   x,
   y,
   width,
-  height
+  height,
 }: BBox): XYPoint {
   return {
     x: x + width / 2,
-    y: y + height / 2
+    y: y + height / 2,
   }
 }
 
@@ -418,6 +488,12 @@ export interface DiagramNode extends ComputedNode {
 }
 
 export namespace DiagramNode {
+  export function modelRef(node: DiagramNode): Fqn | null {
+    return node.modelRef === 1 ? node.id : (node.modelRef ?? null)
+  }
+  export function deploymentRef(node: DiagramNode): Fqn | null {
+    return node.deploymentRef === 1 ? node.id : (node.deploymentRef ?? null)
+  }
   /**
    * Nodes group is a special kind of node, exisiting only in view
    */
@@ -439,7 +515,7 @@ export interface DiagramEdge extends ComputedEdge {
 
 export interface DiagramView<
   ViewIDs extends string = string,
-  Tags extends string = string
+  Tags extends string = string,
 > extends Omit<ComputedView<ViewIDs, Tags>, 'nodes' | 'edges' | 'manualLayout'> {
   readonly nodes: DiagramNode[]
   readonly edges: DiagramEdge[]

package/src/utils/{commonHead.ts → common-head.ts}

@@ -2,6 +2,8 @@ import { map, pipe, takeWhile, zip } from 'remeda'
 
 /**
  * Common head of two arrays
+ *
+ * @param equals - Equality function, defaults to `Object.is`
  */
 export function commonHead<T>(
   sources: ReadonlyArray<T>,

package/src/utils/const.ts

@@ -0,0 +1 @@
+export const customInspectSymbol = Symbol.for('nodejs.util.inspect.custom')