@likec4/core 1.40.0 → 1.41.0

package/src/model/ElementModel.ts

@@ -1,4 +1,4 @@
-import { isEmpty, isTruthy, unique } from 'remeda'
+import { isEmpty, isShallowEqual, isTruthy, unique } from 'remeda'
 import type { SetRequired } from 'type-fest'
 import type { Any, AnyAux, Color, IteratorLike } from '../types'
 import {
@@ -12,6 +12,8 @@ import {
   DefaultElementShape,
   DefaultShapeSize,
   DefaultThemeColor,
+  preferDescription,
+  preferSummary,
   RichText,
   splitGlobalFqn,
 } from '../types'
@@ -95,8 +97,29 @@ export class ElementModel<A extends AnyAux = Any> implements WithTags<A>, WithMe
     return this.$element.title
   }
 
+  /**
+   * Returns true if the element has a summary and a description
+   * (if one is missing - it falls back to another)
+   */
+  get hasSummary(): boolean {
+    return !!this.$element.summary && !!this.$element.description &&
+      !isShallowEqual(this.$element.summary, this.$element.description)
+  }
+
+  /**
+   * Short description of the element.
+   * Falls back to description if summary is not provided.
+   */
+  get summary(): RichTextOrEmpty {
+    return RichText.memoize(this, 'summary', preferSummary(this.$element))
+  }
+
+  /**
+   * Long description of the element.
+   * Falls back to summary if description is not provided.
+   */
   get description(): RichTextOrEmpty {
-    return RichText.memoize(this, this.$element.description)
+    return RichText.memoize(this, 'description', preferDescription(this.$element))
   }
 
   get technology(): string | null {

package/src/model/RelationModel.ts

@@ -83,7 +83,7 @@ export class RelationshipModel<A extends AnyAux = AnyAux> implements AnyRelation
   }
 
   get description(): RichTextOrEmpty {
-    return RichText.memoize(this, this.$relationship.description)
+    return RichText.memoize(this, 'description', this.$relationship.description)
   }
 
   get navigateTo(): LikeC4ViewModel<A> | null {

package/src/model/view/EdgeModel.ts

@@ -6,12 +6,13 @@ import {
   type DiagramEdge,
   type IteratorLike,
   type RelationshipLineType,
+  type RichTextOrEmpty,
   type scalar,
   type StepEdgeId,
   extractStep,
   isStepEdgeId,
+  RichText,
 } from '../../types'
-import { type RichTextOrEmpty, RichText } from '../../types'
 import type { DeploymentRelationModel } from '../DeploymentElementModel'
 import type { RelationshipModel } from '../RelationModel'
 import type { $View, WithTags } from '../types'
@@ -44,7 +45,7 @@ export class EdgeModel<A extends Any = Any, View extends $View<A> = $View<A>> im
   }
 
   get description(): RichTextOrEmpty {
-    return RichText.memoize(this, this.#edge.description)
+    return RichText.memoize(this, 'description', this.#edge.description)
   }
 
   get technology(): string | null {

package/src/model/view/LikeC4ViewModel.ts

@@ -150,7 +150,7 @@ export class LikeC4ViewModel<A extends Any = Any, V extends $View<A> = $View<A>>
   }
 
   get description(): RichTextOrEmpty {
-    return RichText.memoize(this, this.$view.description)
+    return RichText.memoize(this, 'description', this.$view.description)
   }
 
   get tags(): aux.Tags<A> {

package/src/model/view/NodeModel.ts

@@ -49,7 +49,7 @@ export class NodeModel<A extends Any = Any, V extends $View<A> = $View<A>> imple
   }
 
   get description(): RichTextOrEmpty {
-    return RichText.memoize(this, this.#node.description)
+    return RichText.memoize(this, 'description', this.#node.description)
   }
 
   get technology(): string | null {

package/src/types/RichText.ts

@@ -1,7 +1,6 @@
 import { markdownToHtml, markdownToText, memoizeProp, nonexhaustive } from '../utils'
 import type { MarkdownOrString } from './scalar'
 
-const richtxt = Symbol.for('richtxt')
 const symb_text = Symbol.for('text')
 const symb_html = Symbol.for('html')
 
@@ -48,8 +47,8 @@ export class RichText {
    *    return RichText.memoize(this, this.$element.description)
    *  }
    */
-  static memoize(obj: object, source: MarkdownOrString | null | undefined): RichTextOrEmpty {
-    return memoizeProp(obj, richtxt, () => RichText.from(source))
+  static memoize(obj: object, tag: symbol | string, source: MarkdownOrString | null | undefined): RichTextOrEmpty {
+    return memoizeProp(obj, tag, () => RichText.from(source))
   }
 
   /**

package/src/types/_aux.ts

@@ -255,6 +255,28 @@ export type StrictDeploymentKind<A> = A extends infer T extends Any ? scalar.Dep
   : never
 export type StrictRelationKind<A> = A extends infer T extends Any ? scalar.RelationshipKind<RelationKind<T>> : never
 
+export type WithDescriptionAndTech = {
+  // short summary (displayed in the diagram)
+  readonly summary?: scalar.MarkdownOrString | null
+  // long description (displayed in the details panel, or in the diagram if summary is not set)
+  readonly description?: scalar.MarkdownOrString | null
+  readonly technology?: string | null
+}
+
+/**
+ * Returns summary if it is not null, otherwise returns description
+ */
+export function preferSummary(a: WithDescriptionAndTech): scalar.MarkdownOrString | null | undefined {
+  return a.summary ?? a.description
+}
+
+/**
+ * Returns description if it is not null, otherwise returns summary
+ */
+export function preferDescription(a: WithDescriptionAndTech): scalar.MarkdownOrString | null | undefined {
+  return a.description ?? a.summary
+}
+
 export type WithTags<A extends Any> = {
   readonly tags: Tags<A>
 }
@@ -275,6 +297,10 @@ export type WithMetadata<A extends Any> = {
   readonly metadata?: Metadata<A>
 }
 
+export type WithNotation = {
+  readonly notation?: string | null
+}
+
 /**
  * @see {@link LiteralUnion} from type-fest (https://github.com/sindresorhus/type-fest/blob/main/source/literal-union.d.ts)
  */

package/src/types/_common.ts

@@ -1,4 +1,11 @@
-import type { IsAny, Simplify, UnionToIntersection } from 'type-fest'
+import { omitBy } from 'remeda'
+import type {
+  Exact,
+  IsAny,
+  KeysOfUnion,
+  Simplify,
+  UnionToIntersection,
+} from 'type-fest'
 
 export type NonEmptyArray<T> = [T, ...T[]]
 
@@ -78,3 +85,18 @@ export interface Link {
  * Coalesce `V` to a string if it is `any`
  */
 export type Coalesce<V extends string, OrIfAny = string> = IsAny<V> extends true ? OrIfAny : V
+
+type ExactObject<T, InputType = unknown> =
+  & {
+    [KeyType in keyof T]: undefined extends T[KeyType] ? T[KeyType] | undefined : T[KeyType]
+  }
+  & Record<Exclude<keyof InputType, KeysOfUnion<T>>, never>
+
+/**
+ * Allows only exact properties of `U` to be present in `T` and omits undefined values
+ *
+ * See {@link Exact} for more details (this version is non-deep)
+ */
+export function omitUndefined<Expected, T extends ExactObject<Expected, T>>(a: T): Expected {
+  return omitBy(a, v => v === undefined) as Expected
+}

package/src/types/index.ts

@@ -13,6 +13,8 @@ export type {
   UnknownParsed,
 } from './_aux'
 
+export { preferDescription, preferSummary } from './_aux'
+
 export * from './const'
 export * from './expression'
 export * from './expression-model'

package/src/types/model-deployment.ts

@@ -1,11 +1,9 @@
 import { isTruthy } from 'remeda'
 import type * as aux from './_aux'
 import type { AnyAux, Unknown } from './_aux'
-import type { Link } from './_common'
 import type { FqnRef } from './fqnRef'
 import type { AbstractRelationship, ElementStyle } from './model-logical'
 import type { Icon } from './scalar'
-import type * as scalar from './scalar'
 import type { Color, ElementShape } from './styles'
 
 export interface DeploymentElementStyle extends ElementStyle {
@@ -17,30 +15,28 @@ export interface DeploymentElementStyle extends ElementStyle {
 // dprint-ignore
 export interface DeploymentNode<A extends AnyAux = Unknown>
   extends
+    aux.WithDescriptionAndTech,
     aux.WithOptionalTags<A>,
     aux.WithOptionalLinks,
-    aux.WithMetadata<A>
+    aux.WithMetadata<A>,
+    aux.WithNotation
 {
   element?: never
   // Full-qualified-name for Deployment model
   readonly id: aux.StrictDeploymentFqn<A>
   readonly kind: aux.DeploymentKind<A>
   readonly title: string
-  readonly description?: scalar.MarkdownOrString | null
-  readonly technology?: string | null
-  readonly tags?: aux.Tags<A> | null
-  readonly links?: readonly Link[] | null
   readonly style: DeploymentElementStyle
-  readonly notation?: string | null
-  readonly metadata?: aux.Metadata<A>
 }
 
 // dprint-ignore
 export interface DeployedInstance<A extends AnyAux = Unknown>
   extends
+    aux.WithDescriptionAndTech,
     aux.WithOptionalTags<A>,
     aux.WithOptionalLinks,
-    aux.WithMetadata<A>
+    aux.WithMetadata<A>,
+    aux.WithNotation
 {
   kind?: never
   /**
@@ -50,13 +46,7 @@ export interface DeployedInstance<A extends AnyAux = Unknown>
   readonly id: aux.StrictDeploymentFqn<A>
   readonly element: aux.StrictFqn<A>
   readonly title?: string
-  readonly description?: scalar.MarkdownOrString | null
-  readonly technology?: string | null
-  readonly tags?: aux.Tags<A> | null
-  readonly links?: readonly Link[] | null
   readonly style?: DeploymentElementStyle
-  readonly notation?: string
-  readonly metadata?: aux.Metadata<A>
 }
 
 export type DeploymentElement<A extends AnyAux = Unknown> = DeploymentNode<A> | DeployedInstance<A>
@@ -67,11 +57,11 @@ export type DeploymentElementRef<A extends AnyAux = Unknown> = {
 }
 
 export function isDeploymentNode<A extends AnyAux>(el: DeploymentElement<A>): el is DeploymentNode<A> {
-  return 'kind' in el && !isTruthy(el.element)
+  return isTruthy(el.kind) && !isTruthy(el.element)
 }
 
 export function isDeployedInstance<A extends AnyAux>(el: DeploymentElement<A>): el is DeployedInstance<A> {
-  return 'element' in el && isTruthy(el.element)
+  return isTruthy(el.element) && !isTruthy(el.kind)
 }
 
 /**

package/src/types/model-logical.ts

@@ -1,6 +1,5 @@
 import type * as aux from './_aux'
 import type { AnyAux } from './_aux'
-import type { Link } from './_common'
 import type { FqnRef } from './fqnRef'
 import type * as scalar from './scalar'
 import type {
@@ -74,23 +73,19 @@ export function ensureSizes<S extends WithSizes>({
 // dprint-ignore
 export interface Element<A extends AnyAux = AnyAux>
   extends
+    aux.WithDescriptionAndTech,
     aux.WithOptionalTags<A>,
     aux.WithOptionalLinks,
-    aux.WithMetadata<A>
+    aux.WithMetadata<A>,
+    aux.WithNotation
 {
   readonly id: aux.StrictFqn<A>
   readonly kind: aux.ElementKind<A>
   readonly title: string
-  readonly description?: scalar.MarkdownOrString | null
-  readonly technology?: string | null
-  readonly tags?: aux.Tags<A> | null
-  readonly links?: readonly Link[] | null
   readonly icon?: scalar.Icon
   readonly shape?: ElementShape
   readonly color?: Color
   readonly style?: ElementStyle
-  readonly notation?: string | null
-  readonly metadata?: aux.Metadata<A>
 }
 
 export const DefaultLineStyle: RelationshipLineType = 'dashed'
@@ -100,24 +95,20 @@ export const DefaultRelationshipColor: ThemeColor = 'gray'
 // dprint-ignore
 export interface AbstractRelationship<A extends AnyAux>
   extends
+    aux.WithDescriptionAndTech,
     aux.WithOptionalTags<A>,
     aux.WithOptionalLinks,
     aux.WithMetadata<A>
 {
   readonly id: scalar.RelationId
   readonly title?: string | null
-  readonly description?: scalar.MarkdownOrString | null
-  readonly technology?: string | null
   readonly kind?: aux.RelationKind<A>
   readonly color?: Color
   readonly line?: RelationshipLineType
   readonly head?: RelationshipArrowType
   readonly tail?: RelationshipArrowType
-  readonly tags?: aux.Tags<A> | null
-  readonly links?: readonly Link[] | null
   // Link to dynamic view
   readonly navigateTo?: aux.ViewId<A>
-  readonly metadata?: aux.Metadata<A>
 }
 
 /**

package/src/types/model-spec.ts

@@ -26,6 +26,9 @@ import type {
 export interface ElementSpecification {
   tags?: scalar.Tag[]
   title?: string
+  // short summary
+  summary?: scalar.MarkdownOrString
+  // long description
   description?: scalar.MarkdownOrString
   technology?: string
   notation?: string

package/src/types/view-computed.ts

@@ -1,5 +1,5 @@
 import type * as aux from './_aux'
-import type { Any } from './_aux'
+import type { AnyAux } from './_aux'
 import type { _stage, _type } from './const'
 import type { ElementStyle } from './model-logical'
 import type * as scalar from './scalar'
@@ -21,26 +21,33 @@ import type {
 } from './view-common'
 import type { DynamicViewDisplayVariant } from './view-parsed.dynamic'
 
-export interface ComputedNode<A extends Any = Any> extends aux.WithOptionalLinks {
+// dprint-ignore
+export interface ComputedNode<A extends AnyAux = AnyAux>
+  extends
+    aux.WithTags<A>,
+    aux.WithOptionalLinks
+{  
   id: scalar.NodeId
   kind: aux.ElementKind<A> | aux.DeploymentKind<A> | '@group'
   parent: scalar.NodeId | null
   /**
    * Reference to model element
    */
-  modelRef?: aux.Fqn<A> | undefined
+  modelRef?: aux.Fqn<A>
   /**
    * Reference to deployment element
    */
-  deploymentRef?: aux.DeploymentFqn<A> | undefined
+  deploymentRef?: aux.DeploymentFqn<A>
   title: string
+  /**
+   * Description of the node
+   * either summary or description
+   */
   description?: scalar.MarkdownOrString | null
   technology?: string | null
-  notation?: string
   children: scalar.NodeId[]
   inEdges: scalar.EdgeId[]
   outEdges: scalar.EdgeId[]
-  tags: aux.Tags<A>
   shape: ElementShape
   color: Color
   icon?: Icon
@@ -48,21 +55,22 @@ export interface ComputedNode<A extends Any = Any> extends aux.WithOptionalLinks
   navigateTo?: aux.StrictViewId<A> | null
   level: number
   // For compound nodes, the max depth of nested nodes
-  depth?: number
+  depth?: number | null
   /**
    * If this node was customized in the view
    */
   isCustomized?: boolean
+  notation?: string | null
 }
 
-export interface ComputedEdge<A extends Any = Any> extends aux.WithOptionalTags<A> {
+export interface ComputedEdge<A extends AnyAux = AnyAux> extends aux.WithOptionalTags<A> {
   id: scalar.EdgeId
   parent: scalar.NodeId | null
   source: scalar.NodeId
   target: scalar.NodeId
   label: string | null
   description?: scalar.MarkdownOrString | null
-  technology?: string
+  technology?: string | null
   relations: scalar.RelationId[]
   kind?: aux.RelationKind<A> | typeof scalar.StepEdgeKind
   notation?: string
@@ -85,7 +93,7 @@ export interface ComputedEdge<A extends Any = Any> extends aux.WithOptionalTags<
   dir?: 'forward' | 'back' | 'both'
 }
 
-interface BaseComputedViewProperties<A extends Any> extends BaseViewProperties<A>, ViewWithHash, ViewWithNotation {
+interface BaseComputedViewProperties<A extends AnyAux> extends BaseViewProperties<A>, ViewWithHash, ViewWithNotation {
   readonly [_stage]: 'computed'
   readonly autoLayout: ViewAutoLayout
   readonly nodes: ComputedNode<A>[]
@@ -97,17 +105,17 @@ interface BaseComputedViewProperties<A extends Any> extends BaseViewProperties<A
   readonly manualLayout?: ViewManualLayout | undefined
 }
 
-export interface ComputedElementView<A extends Any = Any> extends BaseComputedViewProperties<A> {
+export interface ComputedElementView<A extends AnyAux = AnyAux> extends BaseComputedViewProperties<A> {
   readonly [_type]: 'element'
   readonly viewOf?: aux.StrictFqn<A>
   readonly extends?: aux.StrictViewId<A>
 }
 
-export interface ComputedDeploymentView<A extends Any = Any> extends BaseComputedViewProperties<A> {
+export interface ComputedDeploymentView<A extends AnyAux = AnyAux> extends BaseComputedViewProperties<A> {
   readonly [_type]: 'deployment'
 }
 
-export interface ComputedDynamicView<A extends Any = Any> extends BaseComputedViewProperties<A> {
+export interface ComputedDynamicView<A extends AnyAux = AnyAux> extends BaseComputedViewProperties<A> {
   readonly [_type]: 'dynamic'
   /**
    * How to display the dynamic view

package/src/types/view-layouted.ts

@@ -27,10 +27,6 @@ export interface DiagramNode<A extends AnyAux = AnyAux> extends ComputedNode<A>,
    * (Absolute coordinates)
    */
   labelBBox: BBox
-
-  // description?: scalar.HtmlOrString | null
-  // technology?: scalar.HtmlOrString | null
-  // notation?: scalar.HtmlOrString | null
 }
 
 export interface DiagramEdge<A extends AnyAux = AnyAux> extends ComputedEdge<A> {