@likec4/core 1.32.2 → 1.33.0

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

@@ -47,6 +47,7 @@ export function applyCustomElementProperties<A extends AnyAux>(
       padding,
       size,
       textSize,
+      description,
       ...rest
     } = omitBy(props, isNullish)
     const notEmpty = !isEmpty(rest)
@@ -62,6 +63,13 @@ export function applyCustomElementProperties<A extends AnyAux>(
           ...rest,
         }
       }
+      if (description !== undefined) {
+        node = {
+          ...node,
+          isCustomized: true,
+          description: { txt: description },
+        }
+      }
 
       let styleOverride: ComputedNode['style'] | undefined
       if (border !== undefined) {

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

@@ -18,6 +18,7 @@ export function applyCustomRelationProperties<A extends AnyAux>(
       customRelation: {
         expr,
         title,
+        description,
         ...customprops
       },
     } of rules
@@ -44,6 +45,7 @@ export function applyCustomRelationProperties<A extends AnyAux>(
         edges[i] = {
           ...edge,
           ...props,
+          ...description && { description: { txt: description } },
           label: title ?? edge.label,
           isCustomized: true,
         }

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

@@ -29,8 +29,8 @@ function updateDepthOfAncestors(node: ComputedNode, nodes: ReadonlyMap<string, C
 }
 
 export type ComputedNodeSource<A extends AnyAux = Unknown> = Simplify<
-  & Pick<ComputedNode<A>, 'id' | 'title' | 'kind' | 'deploymentRef' | 'modelRef'>
-  & Partial<Omit<Element<A>, 'id' | 'title' | 'kind'>>
+  & Pick<ComputedNode<A>, 'id' | 'title' | 'description' | 'kind' | 'deploymentRef' | 'modelRef'>
+  & Partial<Omit<Element<A>, 'id' | 'title' | 'description' | 'kind'>>
 >
 
 export function elementModelToNodeSource<A extends AnyAux>(el: ElementModel<A>): ComputedNodeSource<A> {
@@ -86,7 +86,7 @@ export function buildComputedNodes<A extends AnyAux>(
   // Ensure that parent nodes are created before child nodes
   Array.from(elements)
     .sort(compareByFqnHierarchically)
-    .forEach(({ id, style, kind, title, color, shape, tags, ...el }) => {
+    .forEach(({ id, style, kind, title, color, shape, tags, notation, ...el }) => {
       let parent = parentFqn(id)
       let level = 0
       let parentNd: ComputedNode<A> | undefined
@@ -130,6 +130,7 @@ export function buildComputedNodes<A extends AnyAux>(
         children: [],
         inEdges: [],
         outEdges: [],
+        ...notation && { notation },
         ...el,
         style: {
           ...style,

package/src/compute-view/utils/merge-props-from-relationships.ts

@@ -1,4 +1,4 @@
-import { isTruthy, only, pickBy, pipe, reduce, unique } from 'remeda'
+import { isDeepEqual, isTruthy, only, pickBy, pipe, reduce, unique } from 'remeda'
 import type {
   AnyAux,
   aux,
@@ -9,12 +9,13 @@ import type {
   Relationship,
   RelationshipArrowType,
   RelationshipLineType,
+  scalar,
 } from '../../types'
 import { isNonEmptyArray } from '../../utils'
 
 function pickRelationshipProps<A extends AnyAux>(relation: Relationship<A> | DeploymentRelationship<A>): {
   title?: string
-  description?: string | null
+  description?: scalar.MarkdownOrString | null
   technology: string | null
   kind: aux.RelationKind<A> | null
   color: Color | null
@@ -52,7 +53,7 @@ function pickRelationshipProps<A extends AnyAux>(relation: Relationship<A> | Dep
 
 export type MergedRelationshipProps<A extends AnyAux> = {
   title?: string | null
-  description?: string
+  description?: scalar.MarkdownOrString | null
   technology?: string
   kind?: aux.RelationKind<A>
   color?: Color
@@ -80,7 +81,7 @@ export function mergePropsFromRelationships<A extends AnyAux>(
         if (isTruthy(r.title) && !acc.title.includes(r.title)) {
           acc.title.push(r.title)
         }
-        if (isTruthy(r.description) && !acc.description.includes(r.description)) {
+        if (isTruthy(r.description) && !acc.description.some(isDeepEqual(r.description))) {
           acc.description.push(r.description)
         }
         if (isTruthy(r.technology) && !acc.technology.includes(r.technology)) {
@@ -114,7 +115,7 @@ export function mergePropsFromRelationships<A extends AnyAux>(
       },
       {
         title: [] as string[],
-        description: [] as string[],
+        description: [] as scalar.MarkdownOrString[],
         technology: [] as string[],
         kind: [] as aux.RelationKind<A>[],
         head: [] as RelationshipArrowType[],

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

@@ -10,12 +10,33 @@ export function calcViewLayoutHash<V extends ComputedView>(view: SetOptional<V,
     autoLayout: view.autoLayout,
     nodes: pipe(
       view.nodes,
-      map(pick(['id', 'title', 'description', 'technology', 'shape', 'icon', 'children'])),
-      mapToObj(({ id, icon, ...node }) => [id, { ...node, icon: isTruthy(icon) ? 'Y' : 'N' }]),
+      map(n => ({
+        id: n.id,
+        icon: isTruthy(n.icon) ? 'Y' : 'N',
+        title: n.title,
+        description: n.description?.md ?? n.description?.txt ?? null,
+        technology: n.technology ?? null,
+        shape: n.shape,
+        size: n.style.size ?? null,
+        textSize: n.style.textSize ?? null,
+        padding: n.style.padding ?? null,
+        children: n.children,
+      })),
+      mapToObj(({ id, ...node }) => [id, node]),
     ),
     edges: pipe(
       view.edges,
-      map(pick(['source', 'target', 'label', 'description', 'technology', 'dir', 'head', 'tail', 'line'])),
+      map(e => ({
+        source: e.source,
+        target: e.target,
+        label: e.label,
+        description: e.description?.md ?? e.description?.txt ?? null,
+        technology: e.technology ?? null,
+        dir: e.dir,
+        head: e.head,
+        tail: e.tail,
+        line: e.line,
+      })),
       mapToObj(({ source, target, ...edge }) => [`${source}:${target}`, edge]),
     ),
   }

package/src/model/DeploymentElementModel.ts

@@ -1,4 +1,4 @@
-import { isTruthy, only, unique } from 'remeda'
+import { isEmpty, isTruthy, only, unique } from 'remeda'
 import type { SetRequired } from 'type-fest'
 import {
   type Any,
@@ -12,11 +12,13 @@ import {
   type IteratorLike,
   type Link,
   type RelationshipLineType,
+  type RichTextOrEmpty,
   type scalar,
   DefaultElementShape,
   DefaultLineStyle,
   DefaultShapeSize,
   DefaultThemeColor,
+  RichText,
 } from '../types'
 import * as aux from '../types/aux'
 import { commonAncestor, hierarchyLevel, memoizeProp, nonNullable } from '../utils'
@@ -61,8 +63,8 @@ abstract class AbstractDeploymentElementModel<A extends Any> implements WithTags
     return this.$node.style?.color as Color ?? DefaultThemeColor
   }
 
-  get description(): string | null {
-    return this.$node.description ?? null
+  get description(): RichTextOrEmpty {
+    return RichText.memoize(this, this.$node.description)
   }
 
   get technology(): string | null {
@@ -199,6 +201,10 @@ abstract class AbstractDeploymentElementModel<A extends Any> implements WithTags
       ))
   }
 
+  public hasMetadata(): boolean {
+    return !!this.$node.metadata && !isEmpty(this.$node.metadata)
+  }
+
   public getMetadata(): aux.Metadata<A>
   public getMetadata(field: aux.MetadataKey<A>): string | undefined
   public getMetadata(field?: aux.MetadataKey<A>) {
@@ -402,12 +408,12 @@ export class DeployedInstanceModel<A extends Any = Any> extends AbstractDeployme
     return this.element.kind
   }
 
-  override get description(): string | null {
-    return this.$instance.description ?? this.element.description
+  override get description(): RichTextOrEmpty {
+    return RichText.memoize(this, this.$instance.description ?? this.element.$element.description)
   }
 
   override get technology(): string | null {
-    return this.$instance.technology ?? this.element.technology
+    return this.$instance.technology ?? this.element.technology ?? null
   }
 
   override get links(): ReadonlyArray<Link> {
@@ -486,7 +492,7 @@ export class NestedElementOfDeployedInstanceModel<A extends Any = Any> {
     return this.element.title
   }
 
-  get description(): string | null {
+  get description(): RichTextOrEmpty {
     return this.element.description
   }
 
@@ -536,17 +542,11 @@ export class DeploymentRelationModel<A extends Any = Any> implements AnyRelation
   }
 
   get technology(): string | null {
-    if (!isTruthy(this.$relationship.technology)) {
-      return null
-    }
-    return this.$relationship.technology
+    return this.$relationship.technology ?? null
   }
 
-  get description(): string | null {
-    if (!isTruthy(this.$relationship.description)) {
-      return null
-    }
-    return this.$relationship.description
+  get description(): RichTextOrEmpty {
+    return RichText.memoize(this, this.$relationship.description)
   }
 
   get tags(): aux.Tags<A> {
@@ -590,6 +590,10 @@ export class DeploymentRelationModel<A extends Any = Any> implements AnyRelation
     return false
   }
 
+  public hasMetadata(): boolean {
+    return !!this.$relationship.metadata && !isEmpty(this.$relationship.metadata)
+  }
+
   public getMetadata(): aux.Metadata<A>
   public getMetadata(field: aux.MetadataKey<A>): string | undefined
   public getMetadata(field?: aux.MetadataKey<A>) {

package/src/model/ElementModel.ts

@@ -1,4 +1,4 @@
-import { isTruthy, unique } from 'remeda'
+import { isEmpty, isTruthy, unique } from 'remeda'
 import type { SetRequired } from 'type-fest'
 import type { Any, AnyAux, Color, IteratorLike } from '../types'
 import {
@@ -8,9 +8,11 @@ import {
   type IconUrl,
   type Link,
   type ProjectId,
+  type RichTextOrEmpty,
   DefaultElementShape,
   DefaultShapeSize,
   DefaultThemeColor,
+  RichText,
   splitGlobalFqn,
 } from '../types'
 import * as aux from '../types/aux'
@@ -89,8 +91,8 @@ export class ElementModel<A extends AnyAux = Any> implements WithTags<A>, WithMe
     return this.$element.title
   }
 
-  get description(): string | null {
-    return this.$element.description ?? null
+  get description(): RichTextOrEmpty {
+    return RichText.memoize(this, this.$element.description)
   }
 
   get technology(): string | null {
@@ -265,6 +267,10 @@ export class ElementModel<A extends AnyAux = Any> implements WithTags<A>, WithMe
     return this.$model.deployment.instancesOf(this)
   }
 
+  public hasMetadata(): boolean {
+    return !!this.$element.metadata && !isEmpty(this.$element.metadata)
+  }
+
   public getMetadata(): aux.Metadata<A>
   public getMetadata(field: aux.MetadataKey<A>): string | undefined
   public getMetadata(field?: aux.MetadataKey<A>) {

package/src/model/RelationModel.ts

@@ -1,11 +1,13 @@
-import { isTruthy } from 'remeda'
+import { isEmpty, isTruthy } from 'remeda'
 import type { AnyAux, Color, IteratorLike, Link, scalar } from '../types'
 import {
   type Relationship,
   type RelationshipLineType,
+  type RichTextOrEmpty,
   DefaultLineStyle,
   DefaultRelationshipColor,
   FqnRef,
+  RichText,
 } from '../types'
 import type * as aux from '../types/aux'
 import { commonAncestor } from '../utils/fqn'
@@ -23,16 +25,16 @@ export type RelationshipsIterator<A extends AnyAux> = IteratorLike<RelationshipM
  * use {@link isDeploymentRelationModel} guard to check if the relationship is a deployment relationship
  */
 export interface AnyRelationshipModel<A extends AnyAux> extends WithTags<A>, WithMetadata<A> {
-  get id(): scalar.RelationId
-  get expression(): string
-  get title(): string | null
-  get technology(): string | null
-  get description(): string | null
-  get navigateTo(): LikeC4ViewModel<A> | null
-  get kind(): aux.RelationKind<A> | null
-  get links(): ReadonlyArray<Link>
-  get color(): Color
-  get line(): RelationshipLineType
+  readonly id: scalar.RelationId
+  readonly expression: string
+  readonly title: string | null
+  readonly technology: string | null
+  readonly description: RichTextOrEmpty
+  readonly navigateTo: LikeC4ViewModel<A> | null
+  readonly kind: aux.RelationKind<A> | null
+  readonly links: ReadonlyArray<Link>
+  readonly color: Color
+  readonly line: RelationshipLineType
   isDeploymentRelation(): this is DeploymentRelationModel<A>
   isModelRelation(): this is RelationshipModel<A>
   views(): ViewsIterator<A>
@@ -80,11 +82,8 @@ export class RelationshipModel<A extends AnyAux = AnyAux> implements AnyRelation
     return this.$relationship.technology
   }
 
-  get description(): string | null {
-    if (!isTruthy(this.$relationship.description)) {
-      return null
-    }
-    return this.$relationship.description
+  get description(): RichTextOrEmpty {
+    return RichText.memoize(this, this.$relationship.description)
   }
 
   get navigateTo(): LikeC4ViewModel<A> | null {
@@ -131,6 +130,10 @@ export class RelationshipModel<A extends AnyAux = AnyAux> implements AnyRelation
     return true
   }
 
+  public hasMetadata(): boolean {
+    return !!this.$relationship.metadata && !isEmpty(this.$relationship.metadata)
+  }
+
   public getMetadata(): aux.Metadata<A>
   public getMetadata(field: aux.MetadataKey<A>): string | undefined
   public getMetadata(field?: aux.MetadataKey<A>) {

package/src/model/index.ts

@@ -60,3 +60,5 @@ export type {
   AuxFromLikeC4ModelData,
   SpecAux,
 } from '../types'
+
+export { RichText, type RichTextEmpty, type RichTextOrEmpty } from '../types'

package/src/model/types.ts

@@ -68,6 +68,7 @@ export interface WithTags<A extends AnyAux> {
 }
 
 export interface WithMetadata<A extends AnyAux> {
+  hasMetadata(): boolean
   getMetadata(): aux.Metadata<A>
   getMetadata(field: aux.MetadataKey<A>): string | undefined
 }

package/src/model/view/EdgeModel.ts

@@ -11,6 +11,7 @@ import {
   extractStep,
   isStepEdgeId,
 } from '../../types'
+import { type RichTextOrEmpty, RichText } from '../../types'
 import type { DeploymentRelationModel } from '../DeploymentElementModel'
 import type { RelationshipModel } from '../RelationModel'
 import type { $View, WithTags } from '../types'
@@ -39,11 +40,11 @@ export class EdgeModel<A extends Any = Any, View extends $View<A> = $View<A>> im
   }
 
   get label(): string | null {
-    return this.#edge.label
+    return this.#edge.label ?? null
   }
 
-  get description(): string | null {
-    return this.#edge.description ?? null
+  get description(): RichTextOrEmpty {
+    return RichText.memoize(this, this.#edge.description)
   }
 
   get technology(): string | null {

package/src/model/view/LikeC4ViewModel.ts

@@ -8,6 +8,7 @@ import type {
   ViewWithType,
 } from '../../types'
 import { _stage, _type } from '../../types'
+import { type RichTextOrEmpty, RichText } from '../../types'
 import type * as aux from '../../types/aux'
 import { DefaultMap, ifind, nonNullable } from '../../utils'
 import type { ElementModel } from '../ElementModel'
@@ -92,6 +93,10 @@ export class LikeC4ViewModel<A extends Any = Any, V extends $View<A> = $View<A>>
     return this.$view.title
   }
 
+  get description(): RichTextOrEmpty {
+    return RichText.memoize(this, this.$view.description)
+  }
+
   get tags(): aux.Tags<A> {
     return this.$view.tags ?? []
   }

package/src/model/view/NodeModel.ts

@@ -10,9 +10,11 @@ import {
   type IconUrl,
   type IteratorLike,
   type Link,
+  type RichTextOrEmpty,
   type scalar,
   GroupElementKind,
   isGroupElementKind,
+  RichText,
 } from '../../types'
 import type * as aux from '../../types/aux'
 import { memoizeProp } from '../../utils'
@@ -46,8 +48,8 @@ export class NodeModel<A extends Any = Any, V extends $View<A> = $View<A>> imple
     return this.#node.kind as any
   }
 
-  get description(): string | null {
-    return this.#node.description ?? null
+  get description(): RichTextOrEmpty {
+    return RichText.memoize(this, this.#node.description)
   }
 
   get technology(): string | null {

package/src/theme/index.ts

@@ -37,12 +37,19 @@ export const defaultTheme: LikeC4Theme = {
     lg: 24, // 1.5rem = 16px + 8px
     xl: 32, // 2rem
   },
+  /**
+   * Text sizes for titles
+   * https://typescale.com/
+   *
+   * Scale:  1.2
+   * Base:   16px
+   */
   textSizes: {
-    xs: 12,
-    sm: 14,
-    md: 19,
-    lg: 24,
-    xl: 32,
+    xs: 13.33,
+    sm: 16,
+    md: 19.2,
+    lg: 23.04,
+    xl: 27.65,
   },
 }
 

package/src/types/RichText.ts

@@ -0,0 +1,200 @@
+import type { MarkdownOrString } from '../types'
+import { markdownToHtml, markdownToText, memoizeProp, nonexhaustive } from '../utils'
+
+const richtxt = Symbol.for('richtxt')
+const symb_text = Symbol.for('text')
+const symb_html = Symbol.for('html')
+
+const emptyTxt = ''
+
+export interface RichTextEmpty {
+  readonly isEmpty: true
+  readonly isMarkdown: false
+  readonly nonEmpty: false
+  readonly $source: null
+  readonly text: null
+  readonly md: null
+  readonly html: null
+  equals(other: unknown): boolean
+}
+
+export interface RichTextNonEmpty {
+  readonly isEmpty: false
+  readonly nonEmpty: true
+  readonly isMarkdown: boolean
+  readonly $source: MarkdownOrString
+  readonly text: string
+  readonly md: string
+  readonly html: string
+  equals(other: unknown): boolean
+}
+
+export type RichTextOrEmpty = RichTextNonEmpty | RichTextEmpty
+
+/**
+ * RichText is a class that represents a potentially markdown string.
+ * It can be either a plain text or a markdown.
+ * It is used to represent the content of a node or a link.
+ */
+export class RichText {
+  private static _cache = new WeakMap<MarkdownOrString, RichTextOrEmpty>()
+
+  /**
+   * Creates and memoizes a RichText instance.
+   * @see ElementModel.description
+   * @example
+   *
+   *  get description(): RichTextOrEmpty {
+   *    return RichText.memoize(this, this.$element.description)
+   *  }
+   */
+  static memoize(obj: object, source: MarkdownOrString | null | undefined): RichTextOrEmpty {
+    return memoizeProp(obj, richtxt, () => RichText.from(source))
+  }
+
+  /**
+   * Creates a RichText instance from a source.
+   */
+  static from(source: RichTextOrEmpty | MarkdownOrString | string | null | undefined): RichTextOrEmpty {
+    if (source === null || source === undefined || source === RichText.EMPTY) {
+      return RichText.EMPTY
+    }
+    if (source instanceof RichText) {
+      return source as RichTextOrEmpty
+    }
+    if (typeof source === 'string') {
+      return RichText.from({ txt: source })
+    }
+    if ('isEmpty' in source && source.isEmpty) {
+      return RichText.EMPTY
+    }
+    if ('md' in source && source.md.trim() === emptyTxt) {
+      return RichText.EMPTY
+    }
+    if ('txt' in source && source.txt.trim() === emptyTxt) {
+      return RichText.EMPTY
+    }
+    const _source = source as MarkdownOrString
+    const cached = RichText._cache.get(_source)
+    if (cached) {
+      return cached
+    }
+    const rt = new RichText(_source) as RichTextOrEmpty
+    RichText._cache.set(_source, rt)
+    return rt
+  }
+
+  /**
+   * This is a workaround for the fact that we need instance of RichText for `instanceof` checks
+   * It is invalid inheritance (returning `null` from getters), and we cast to @see RichTextEmpty
+   */
+  static EMPTY: RichTextEmpty = new class extends RichText {
+    public override readonly isEmpty: true = true
+    public override readonly nonEmpty: false = false
+    public override readonly isMarkdown: false = false
+    public override readonly $source: null = null
+    constructor() {
+      super({ txt: emptyTxt })
+    }
+
+    override get text(): any {
+      return null
+    }
+
+    override get md(): any {
+      return null
+    }
+
+    override get html(): any {
+      return null
+    }
+  }()
+
+  public readonly $source: Readonly<MarkdownOrString> | null
+
+  public readonly isEmpty: boolean
+  public readonly nonEmpty: boolean
+  public readonly isMarkdown: boolean
+
+  /**
+   * Private constructor to prevent direct instantiation.
+   * Use {@link RichText.from} or {@link RichText.memoize} instead.
+   */
+  private constructor(source: MarkdownOrString | string) {
+    this.isMarkdown = false
+    if (typeof source === 'string') {
+      this.$source = { txt: source }
+      this.isEmpty = source.trim() === emptyTxt
+    } else {
+      this.$source = source
+      this.isEmpty = true
+      if ('md' in source) {
+        this.isEmpty = source.md === emptyTxt
+        this.isMarkdown = true
+      } else {
+        this.isEmpty = source.txt === emptyTxt
+      }
+    }
+    this.nonEmpty = !this.isEmpty
+  }
+
+  /**
+   * Returns the text content of the rich text.
+   * If the source is a string, it returns the string.
+   * If the source is a markdown, it returns the markdown.
+   */
+  get text(): string {
+    if (this.isEmpty || this.$source === null) {
+      return emptyTxt
+    }
+    const source = this.$source
+    if ('txt' in source) {
+      return source.txt
+    }
+    return memoizeProp(this, symb_text, () => markdownToText(source.md!))
+  }
+
+  /**
+   * Returns the markdown content of the rich text.
+   * If the source is a string, it returns the string.
+   * If the source is a markdown, it returns the markdown.
+   */
+  get md(): string {
+    if (this.isEmpty || this.$source === null) {
+      return emptyTxt
+    }
+    const source = this.$source
+    if ('md' in source) {
+      return source.md
+    }
+    if ('txt' in source) {
+      return source.txt
+    }
+    nonexhaustive(source)
+  }
+
+  /**
+   * Returns the html content of the rich text.
+   * If the source is a string, it returns the string.
+   * If the source is a markdown, it returns the HTML.
+   */
+  get html(): string {
+    if (this.isEmpty || this.$source === null) {
+      return emptyTxt
+    }
+    const markdown = this.$source.md ?? this.$source.txt
+    return memoizeProp(this, symb_html, () => markdownToHtml(markdown))
+  }
+
+  equals(other: unknown): boolean {
+    if (this === other) return true
+    if (!(other instanceof RichText)) return false
+    if (this.isEmpty && other.isEmpty) return true
+    if (this.isEmpty !== other.isEmpty || this.isMarkdown !== other.isMarkdown) return false
+
+    if (this.isMarkdown) {
+      return this.$source?.md === other.$source?.md
+    }
+    return this.$source?.txt === other.$source?.txt
+  }
+}

package/src/types/index.ts

@@ -37,3 +37,5 @@ export * from './view-parsed.dynamic'
 export * from './view-parsed.element'
 
 export type * as scalar from './scalar'
+
+export { RichText, type RichTextEmpty, type RichTextOrEmpty } from './RichText'