@likec4/core 1.40.0 → 1.41.0

package/src/builder/Builder.ts

@@ -2,7 +2,9 @@ import defu from 'defu'
 import {
   entries,
   fromEntries,
+  fromKeys,
   hasAtLeast,
+  isArray,
   isFunction,
   isNonNullish,
   isNullish,
@@ -23,6 +25,7 @@ import type {
   ParsedElementView,
   ParsedLikeC4ModelData,
   Specification,
+  TagSpecification,
 } from '../types'
 import {
   type Color,
@@ -200,30 +203,51 @@ interface Internals<T extends AnyTypes> extends ViewsBuilder<T>, ModelBuilder<T>
 
 type Op<T> = (b: T) => T
 
-function validateSpec(specification: BuilderSpecification) {
-  for (const [kind, spec] of entries(specification.elements)) {
+function ensureObj<T>(value: string[] | Record<string, Partial<T>>): Record<string, Partial<T>> {
+  return isArray(value) ? fromKeys(value, v => ({})) : value
+}
+
+function validateSpec({ tags, elements, deployments, relationships, ...specification }: BuilderSpecification) {
+  const spectags = {} as Record<string, Partial<TagSpecification>>
+  if (tags) {
+    Object.assign(
+      spectags,
+      ensureObj(tags),
+    )
+  }
+  const _elements = ensureObj(elements)
+
+  for (const [kind, spec] of entries(_elements)) {
     if (spec.tags) {
       for (const tag of spec.tags) {
-        invariant(specification.tags?.[tag], `Invalid specification for element kind "${kind}": tag "${tag}" not found`)
+        invariant(tag in spectags, `Invalid specification for element kind "${kind}": tag "${tag}" not found`)
       }
     }
   }
-  if (specification.deployments) {
-    for (const [kind, spec] of entries(specification.deployments)) {
-      if (spec.tags) {
-        for (const tag of spec.tags) {
-          invariant(
-            specification.tags?.[tag],
-            `Invalid specification for deployment kind "${kind}": tag "${tag}" not found`,
-          )
-        }
+  const _deployments = ensureObj(deployments ?? {})
+
+  for (const [kind, spec] of entries(_deployments)) {
+    if (spec.tags) {
+      for (const tag of spec.tags) {
+        invariant(
+          tag in spectags,
+          `Invalid specification for deployment kind "${kind}": tag "${tag}" not found`,
+        )
       }
     }
   }
+
+  return {
+    ...specification,
+    tags: spectags,
+    elements: _elements,
+    deployments: _deployments,
+    relationships: ensureObj(relationships ?? {}),
+  }
 }
 
 function builder<Spec extends BuilderSpecification, T extends AnyTypes>(
-  spec: Spec,
+  _spec: Spec,
   _elements = new Map<string, Element<Any>>(),
   _relations = [] as ModelRelation[],
   _views = new Map<string, LikeC4View>(),
@@ -235,22 +259,17 @@ function builder<Spec extends BuilderSpecification, T extends AnyTypes>(
   _deployments = new Map<string, DeploymentElement>(),
   _deploymentRelations = [] as DeploymentRelation[],
 ): Builder<T> {
+  const spec = validateSpec(_spec)
+
   const toLikeC4Specification = (): Specification<Types.ToAux<T>> => {
-    validateSpec(spec)
     return ({
-      elements: {
-        ...structuredClone(spec.elements) as any,
-      },
-      deployments: {
-        ...structuredClone(spec.deployments) as any,
-      },
-      relationships: {
-        ...structuredClone(spec.relationships) as any,
-      },
-      tags: mapValues(spec.tags ?? {}, (tagSpec) => ({
+      elements: structuredClone(spec.elements),
+      deployments: structuredClone(spec.deployments),
+      relationships: structuredClone(spec.relationships),
+      tags: mapValues(spec.tags, (tagSpec) => ({
         color: DefaultThemeColor,
         ...tagSpec,
-      })) as any,
+      })),
       ...(!!spec.metadataKeys ? { metadataKeys: spec.metadataKeys as any } : {}),
       customColors: {},
     } as Specification<Types.ToAux<T>>)
@@ -510,7 +529,8 @@ function builder<Spec extends BuilderSpecification, T extends AnyTypes>(
                 icon: _icon,
                 style,
                 title,
-                description = null,
+                description,
+                summary,
                 ...props
               } = typeof _props === 'string' ? { title: _props } : { ..._props }
 
@@ -525,8 +545,7 @@ function builder<Spec extends BuilderSpecification, T extends AnyTypes>(
                 kind: kind as any,
                 title: title ?? nameFromFqn(_id),
                 ...(description && { description: { txt: description } }),
-                technology: null,
-                tags: [],
+                ...(summary && { summary: { txt: summary } }),
                 color: specStyle?.color ?? DefaultThemeColor as Color,
                 shape: specStyle?.shape ?? DefaultElementShape as ElementShape,
                 style: pickBy({
@@ -537,7 +556,7 @@ function builder<Spec extends BuilderSpecification, T extends AnyTypes>(
                   textSize: specStyle?.textSize,
                   ...style,
                 }, isNonNullish),
-                links,
+                ...(links && { links }),
                 ...icon && { icon: icon as IconUrl },
                 ...spec,
                 ...props,
@@ -704,7 +723,8 @@ function builder<Spec extends BuilderSpecification, T extends AnyTypes>(
             const {
               links,
               title,
-              description = null,
+              description,
+              summary,
               ...props
             } = typeof _props === 'string' ? { title: _props } : { ..._props }
             const _id = b.__deploymentFqn(id)
@@ -713,6 +733,7 @@ function builder<Spec extends BuilderSpecification, T extends AnyTypes>(
               id: _id,
               element: target as Fqn,
               ...title && { title },
+              ...(summary && { summary: { txt: summary } }),
               ...(description && { description: { txt: description } }),
               ...links && { links: mapLinks(links) },
               ...props,
@@ -757,7 +778,8 @@ function builder<Spec extends BuilderSpecification, T extends AnyTypes>(
                 icon: _icon,
                 style,
                 title,
-                description = null,
+                description,
+                summary,
                 ...props
               } = typeof _props === 'string' ? { title: _props } : { ..._props }
 
@@ -770,8 +792,7 @@ function builder<Spec extends BuilderSpecification, T extends AnyTypes>(
                 kind: kind as any,
                 title: title ?? nameFromFqn(_id),
                 ...(description && { description: { txt: description } }),
-                technology: null,
-                tags: null,
+                ...(summary && { summary: { txt: summary } }),
                 style: {
                   ...icon && { icon: icon as IconUrl },
                   color: specStyle?.color ?? DefaultThemeColor as Color,
@@ -841,11 +862,40 @@ function builder<Spec extends BuilderSpecification, T extends AnyTypes>(
 
   return self
 }
-
-export namespace Builder {
-  export type Any = Builder<AnyTypes>
-
-  export function forSpecification<const Spec extends BuilderSpecification>(
+export const Builder = {
+  /**
+   * Creates a builder with compositional methods
+   *
+   * @example
+   * ```ts
+   * const {
+   *   model: { model, system, component, relTo },
+   *   deployment: { env, vm},
+   *   views: { view, $include },
+   *   builder,
+   * } = Builder.forSpecification({
+   *   elements: {
+   *     system: {},
+   *     component: {},
+   *   },
+   *   deployments: ['env', 'vm'],
+   * })
+   *
+   * const b = builder
+   *   .with(
+   *     model(
+   *       system('cloud').with(
+   *         component('backend'),
+   *         component('backend.api'),
+   *         component('frontend').with(
+   *           relTo('cloud.backend.api'),
+   *         ),
+   *       ),
+   *     ),
+   *   )
+   * ```
+   */
+  forSpecification<const Spec extends BuilderSpecification>(
     spec: Spec,
   ): {
     builder: Builder<Types.FromSpecification<Spec>>
@@ -853,18 +903,44 @@ export namespace Builder {
     deployment: DeloymentModelHelpers<Types.FromSpecification<Spec>>
     views: ViewsHelpers
   } {
-    validateSpec(spec)
     const b = builder<Spec, Types.FromSpecification<Spec>>(spec)
     return {
       ...b.helpers(),
       builder: b,
     }
-  }
+  },
 
-  export function specification<const Spec extends BuilderSpecification>(
+  /**
+   * Creates a builder with chainable methods
+   *
+   * @example
+   * ```ts
+   * const b = Builder
+   *   .specification({
+   *     elements: ['system', 'component'],
+   *     deployments: ['env', 'vm'],
+   *   })
+   *   .model(({ system, component, relTo }, _) =>
+   *     _(
+   *       system('cloud').with(
+   *         component('backend').with(
+   *           component('api'),
+   *         ),
+   *         component('frontend').with(
+   *           relTo('cloud.backend.api'),
+   *         )
+   *       )
+   *     )
+   *   )
+   * ```
+   */
+  specification<const Spec extends BuilderSpecification>(
     spec: Spec,
   ): Builder<Types.FromSpecification<Spec>> {
-    validateSpec(spec)
     return builder<Spec, Types.FromSpecification<Spec>>(spec)
-  }
+  },
+}
+
+export namespace Builder {
+  export type Any = Builder<AnyTypes>
 }

package/src/builder/_types.ts

@@ -26,16 +26,16 @@ type ElementSpecification = Omit<ElementKindSpecification, 'tags'> & {
 }
 
 export type BuilderSpecification = {
-  elements: {
+  elements: string[] | {
     [kind: string]: Partial<ElementSpecification>
   }
-  relationships?: {
+  relationships?: string[] | {
     [kind: string]: Partial<RelationshipKindSpecification>
   }
-  deployments?: {
+  deployments?: string[] | {
     [kind: string]: Partial<ElementSpecification>
   }
-  tags?: {
+  tags?: string[] | {
     [kind: string]: Partial<TagSpecification>
   }
   metadataKeys?: string[]
@@ -59,6 +59,7 @@ export type Metadata<MetadataKey extends string> = IsNever<MetadataKey> extends
 
 export type NewElementProps<Tag, Metadata> = {
   title?: string
+  summary?: string
   description?: string
   technology?: string
   tags?: IfNever<Tag, never, [Tag, ...Tag[]]>
@@ -79,6 +80,7 @@ export type NewElementProps<Tag, Metadata> = {
 
 export type NewDeploymentNodeProps<Tag, Metadata> = {
   title?: string
+  summary?: string
   description?: string
   technology?: string
   tags?: IfNever<Tag, never, [Tag, ...Tag[]]>
@@ -211,15 +213,17 @@ export type AnyTypesNested = TypesNested<
   any
 >
 
+type KeysOrTuple<T> = T extends readonly string[] ? TupleToUnion<T> : KeysOf<T>
+
 export namespace Types {
   export type FromSpecification<Spec> = Spec extends BuilderSpecification ? Types<
-      KeysOf<Spec['elements']>,
+      KeysOrTuple<Spec['elements']>,
       never,
       never,
-      KeysOf<Spec['relationships']>,
-      KeysOf<Spec['tags']>,
+      KeysOrTuple<Spec['relationships']>,
+      KeysOrTuple<Spec['tags']>,
       TupleToUnion<Spec['metadataKeys']>,
-      KeysOf<Spec['deployments']>,
+      KeysOrTuple<Spec['deployments']>,
       never
     >
     : never

package/src/compute-view/deployment-view/utils.ts

@@ -1,4 +1,4 @@
-import { hasAtLeast, isEmpty, unique } from 'remeda'
+import { hasAtLeast, unique } from 'remeda'
 import type {
   DeployedInstanceModel,
   DeploymentConnectionModel,
@@ -17,8 +17,12 @@ import {
   type scalar,
   type Unknown,
   DefaultArrowType,
+  DefaultElementShape,
+  DefaultThemeColor,
   FqnExpr,
   isViewRuleStyle,
+  omitUndefined,
+  preferSummary,
 } from '../../types'
 import { invariant, nameFromFqn, nonexhaustive, parentFqn } from '../../utils'
 import { applyViewRuleStyle } from '../utils/applyViewRuleStyles'
@@ -135,44 +139,56 @@ export function deploymentExpressionToPredicate<
   nonexhaustive(target)
 }
 
+function instanceSummary(model: DeployedInstanceModel<any>) {
+  return preferSummary(model.$instance) ?? preferSummary(model.element.$element)
+}
+
 export function toNodeSource<A extends AnyAux>(
   el: DeploymentNodeModel<A> | DeployedInstanceModel<A>,
 ): ComputedNodeSource<A> {
   if (el.isDeploymentNode()) {
     const onlyOneInstance = el.onlyOneInstance()
-    let { title, kind, id, description, ...$node } = el.$node
-    const { icon, color, shape, ...style } = el.$node.style ?? {}
+    let {
+      title,
+      id,
+      description,
+      summary,
+      metadata,
+      style,
+      element,
+      tags: _tags, // omit
+      ...$node
+    } = el.$node
+    let icon = style.icon
     let tags = [...el.tags]
     // let description
     // If there is only one instance
+    summary ??= description
     if (onlyOneInstance) {
       tags = unique([...tags, ...onlyOneInstance.tags])
       // If title was not overriden, take title from the instance
       if (title === nameFromFqn(el.id)) {
         title = onlyOneInstance.title
       }
-      description = onlyOneInstance.description.$source ?? description
+      icon ??= onlyOneInstance.style.icon
+      summary ??= instanceSummary(onlyOneInstance)
     }
 
-    return {
+    return omitUndefined({
+      id: id as scalar.NodeId,
+      deploymentRef: id,
+      title,
+      ...$node,
+      color: style.color ?? onlyOneInstance?.color ?? DefaultThemeColor,
+      shape: style.shape ?? DefaultElementShape,
       ...(onlyOneInstance && {
-        ...toNodeSource(onlyOneInstance),
         modelRef: onlyOneInstance.element.id,
       }),
-      title,
-      ...$node,
-      ...(icon && { icon }),
-      ...(color && { color }),
-      ...(shape && { shape }),
-      ...(description && { description }),
+      icon,
+      description: summary,
       tags,
-      style: {
-        ...style,
-      },
-      deploymentRef: id,
-      kind,
-      id: id as scalar.NodeId,
-    }
+      style,
+    })
   }
   invariant(el.isInstance(), 'Expected Instance')
   const instance = el.$instance
@@ -184,33 +200,28 @@ export function toNodeSource<A extends AnyAux>(
     ...(instance.links ?? []),
   ]
 
-  const metadata = {
-    ...element.getMetadata(),
-    ...instance.metadata,
-  }
-
   const notation = instance.notation ?? element.$element.notation
 
-  let description = el.description.$source
-  let technology = instance.technology ?? element.technology
+  const description = instanceSummary(el)
 
-  return {
+  const technology = el.technology ?? undefined
+
+  return omitUndefined({
     id: el.id as scalar.NodeId,
     kind: 'instance' as unknown as aux.DeploymentKind<A>,
     title: el.title,
-    ...(description && { description }),
-    ...(technology && { technology }),
+    description,
+    technology,
     tags: [...el.tags],
-    links: hasAtLeast(links, 1) ? links : null,
-    ...icon && { icon },
-    ...color && { color },
-    ...shape && { shape },
+    links: hasAtLeast(links, 1) ? links : undefined,
+    icon,
+    color,
+    shape,
     style,
     deploymentRef: instance.id,
     modelRef: element.id,
-    ...notation && { notation },
-    ...!isEmpty(metadata) && ({ metadata }),
-  }
+    notation,
+  })
 }
 
 export function toComputedEdges<A extends AnyAux>(

package/src/compute-view/relationships-view/layout.ts

@@ -2,7 +2,7 @@ import dagre, { type EdgeConfig, type GraphLabel } from '@dagrejs/dagre'
 import { concat, filter, forEachObj, groupBy, map, mapToObj, pipe, prop, reduce, tap } from 'remeda'
 import type { ElementModel } from '../../model/ElementModel'
 import type { RelationshipModel } from '../../model/RelationModel'
-import type { DiagramNode, DiagramView, Fqn, NodeId } from '../../types'
+import { type DiagramNode, type DiagramView, type Fqn, type NodeId, omitUndefined } from '../../types'
 import { invariant, sortParentsFirst } from '../../utils'
 import { toArray } from '../../utils/iterable'
 import { DefaultMap } from '../../utils/mnemonist'
@@ -311,13 +311,14 @@ export function layoutRelationshipsView(data: RelationshipsViewData): Pick<Diagr
     // }
     const children = (g.children(id) as NodeId[] | undefined ?? []).filter(c => !c.endsWith(PortSuffix))
 
-    return {
+    return omitUndefined({
       id: id as NodeId,
       parent: parentId as NodeId ?? null,
       title: element.title,
-      ...position,
+      x: position.x,
+      y: position.y,
       position: [position.x, position.y],
-      description: element.description?.$source ?? null,
+      description: element.$element.summary ?? element.$element.description ?? null,
       technology: element.technology,
       tags: [],
       links: null,
@@ -337,11 +338,11 @@ export function layoutRelationshipsView(data: RelationshipsViewData): Pick<Diagr
       },
       inEdges: [],
       outEdges: [],
-      ...(children.length > 0 && { depth: nodeDepth(id) }),
+      depth: children.length > 0 ? nodeDepth(id) : 0,
       children,
       width,
       height,
-    }
+    })
   })
 
   return {

package/src/compute-view/utils/buildComputedNodes.ts

@@ -1,15 +1,16 @@
-import type { Simplify } from 'type-fest'
+import type { Except } from 'type-fest'
 import type { ElementModel } from '../../model'
 import {
   type AnyAux,
   type aux,
   type ComputedNode,
-  type Element,
   type scalar,
   type Unknown,
   DefaultElementShape,
   DefaultThemeColor,
   GroupElementKind,
+  omitUndefined,
+  preferSummary,
 } from '../../types'
 import { nonNullable } from '../../utils'
 import { compareByFqnHierarchically, parentFqn } from '../../utils/fqn'
@@ -28,18 +29,30 @@ function updateDepthOfAncestors(node: ComputedNode, nodes: ReadonlyMap<string, C
   }
 }
 
-export type ComputedNodeSource<A extends AnyAux = Unknown> = Simplify<
-  & Pick<ComputedNode<A>, 'id' | 'title' | 'description' | 'kind' | 'deploymentRef' | 'modelRef'>
-  & Partial<Omit<Element<A>, 'id' | 'title' | 'description' | 'kind'>>
+export type ComputedNodeSource<A extends AnyAux = Unknown> = Except<
+  ComputedNode<A>,
+  'parent' | 'children' | 'inEdges' | 'outEdges' | 'level' | 'depth',
+  { requireExactProps: true }
 >
 
 export function elementModelToNodeSource<A extends AnyAux>(el: ElementModel<A>): ComputedNodeSource<A> {
-  return {
-    ...el.$element,
+  const {
+    id,
+    summary, // omit
+    style,
+    metadata, // omit
+    ...rest
+  } = el.$element
+  return omitUndefined({
+    id: id as scalar.NodeId,
+    modelRef: id,
+    ...rest,
+    style: { ...style },
+    color: el.color,
+    shape: el.shape,
+    description: preferSummary(el.$element),
     tags: [...el.tags],
-    id: el.id as scalar.NodeId,
-    modelRef: el.id,
-  }
+  })
 }
 
 export function buildComputedNodes<A extends AnyAux>(

package/src/compute-view/utils/buildElementNotations.ts

@@ -1,4 +1,4 @@
-import { entries, flatMap, groupBy, map, mapValues, pipe, piped, prop, sortBy, unique } from 'remeda'
+import { entries, filter, flatMap, groupBy, map, mapValues, pipe, piped, prop, sortBy, unique } from 'remeda'
 import type { ComputedNode, NodeNotation } from '../../types'
 
 /**
@@ -12,6 +12,7 @@ import type { ComputedNode, NodeNotation } from '../../types'
 export function buildElementNotations(nodes: ComputedNode<any>[]): NodeNotation[] {
   return pipe(
     nodes,
+    filter((n): n is ComputedNode<any> & { notation: string } => !!n.notation),
     groupBy(prop('notation')),
     mapValues(
       piped(

package/src/model/DeploymentElementModel.ts

@@ -18,6 +18,8 @@ import {
   DefaultLineStyle,
   DefaultShapeSize,
   DefaultThemeColor,
+  preferDescription,
+  preferSummary,
   RichText,
 } from '../types'
 import * as aux from '../types/_aux'
@@ -67,8 +69,20 @@ abstract class AbstractDeploymentElementModel<A extends Any> implements WithTags
     return this.$node.style?.color as Color ?? DefaultThemeColor
   }
 
+  /**
+   * Short description of the element.
+   * Falls back to description if summary is not provided.
+   */
+  get summary(): RichTextOrEmpty {
+    return RichText.memoize(this, 'summary', preferSummary(this.$node))
+  }
+
+  /**
+   * Long description of the element.
+   * Falls back to summary if description is not provided.
+   */
   get description(): RichTextOrEmpty {
-    return RichText.memoize(this, this.$node.description)
+    return RichText.memoize(this, 'description', preferDescription(this.$node))
   }
 
   get technology(): string | null {
@@ -412,8 +426,20 @@ export class DeployedInstanceModel<A extends Any = Any> extends AbstractDeployme
     return this.element.kind
   }
 
+  override get summary(): RichTextOrEmpty {
+    return RichText.memoize(
+      this,
+      'summary',
+      preferSummary(this.$instance) ?? preferSummary(this.element.$element),
+    )
+  }
+
   override get description(): RichTextOrEmpty {
-    return RichText.memoize(this, this.$instance.description ?? this.element.$element.description)
+    return RichText.memoize(
+      this,
+      'description',
+      preferDescription(this.$instance) ?? preferDescription(this.element.$element),
+    )
   }
 
   override get technology(): string | null {
@@ -496,6 +522,10 @@ export class NestedElementOfDeployedInstanceModel<A extends Any = Any> {
     return this.element.title
   }
 
+  get summary(): RichTextOrEmpty {
+    return this.element.summary
+  }
+
   get description(): RichTextOrEmpty {
     return this.element.description
   }
@@ -550,7 +580,7 @@ export class DeploymentRelationModel<A extends Any = Any> implements AnyRelation
   }
 
   get description(): RichTextOrEmpty {
-    return RichText.memoize(this, this.$relationship.description)
+    return RichText.memoize(this, 'description', this.$relationship.description)
   }
 
   get tags(): aux.Tags<A> {