@likec4/core 1.32.2 → 1.34.0

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/expression-model.ts

@@ -1,6 +1,6 @@
+import type * as aux from './_aux'
+import type { AnyAux } from './_aux'
 import type { ExclusiveUnion } from './_common'
-import type * as aux from './aux'
-import type { AnyAux } from './aux'
 import type { PredicateSelector } from './expression'
 import { FqnRef } from './fqnRef'
 import type { WhereOperator } from './operators'

package/src/types/expression.ts

@@ -1,6 +1,6 @@
+import type * as aux from './_aux'
+import type { AnyAux } from './_aux'
 import type { ExclusiveUnion } from './_common'
-import type * as aux from './aux'
-import type { AnyAux } from './aux'
 import { FqnRef } from './fqnRef'
 import type { WhereOperator } from './operators'
 import { type Icon } from './scalar'

package/src/types/fqnRef.ts

@@ -1,7 +1,7 @@
 import { isString } from 'remeda'
+import type * as aux from './_aux'
+import type { AnyAux, Unknown } from './_aux'
 import type { ExclusiveUnion } from './_common'
-import type * as aux from './aux'
-import type { AnyAux, Unknown } from './aux'
 import { GlobalFqn } from './scalar'
 
 export namespace FqnRef {

package/src/types/global.ts

@@ -1,6 +1,6 @@
 import type { NonEmptyTuple, Tagged } from 'type-fest'
+import type { Any } from './_aux'
 import type { NonEmptyArray } from './_common'
-import type { Any } from './aux'
 import type { DynamicViewIncludeRule } from './view-parsed.dynamic'
 import type { ElementViewPredicate, ElementViewRuleStyle } from './view-parsed.element'
 

package/src/types/index.ts

@@ -1,6 +1,6 @@
 export * from './_common'
 
-export type * as aux from './aux'
+export type * as aux from './_aux'
 
 export type {
   Any,
@@ -11,7 +11,7 @@ export type {
   UnknownComputed,
   UnknownLayouted,
   UnknownParsed,
-} from './aux'
+} from './_aux'
 
 export * from './const'
 export * from './expression'
@@ -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'

package/src/types/model-data.ts

@@ -1,7 +1,7 @@
 import type { IsAny } from 'type-fest'
+import type * as aux from './_aux'
+import type { Any } from './_aux'
 import type { NonEmptyArray } from './_common'
-import type * as aux from './aux'
-import type { Any } from './aux'
 import type { _stage } from './const'
 import type { ModelGlobals } from './global'
 import type { DeploymentElement, DeploymentRelationship } from './model-deployment'

package/src/types/model-deployment.ts

@@ -1,10 +1,11 @@
 import { isTruthy } from 'remeda'
+import type * as aux from './_aux'
+import type { AnyAux, Unknown } from './_aux'
 import type { Link } from './_common'
-import type * as aux from './aux'
-import type { AnyAux, Unknown } from './aux'
 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 {
@@ -25,12 +26,12 @@ export interface DeploymentNode<A extends AnyAux = Unknown>
   readonly id: aux.StrictDeploymentFqn<A>
   readonly kind: aux.DeploymentKind<A>
   readonly title: string
-  readonly description?: string | null
+  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 notation?: string | null
   readonly metadata?: aux.Metadata<A>
 }
 
@@ -49,7 +50,7 @@ export interface DeployedInstance<A extends AnyAux = Unknown>
   readonly id: aux.StrictDeploymentFqn<A>
   readonly element: aux.StrictFqn<A>
   readonly title?: string
-  readonly description?: string | null
+  readonly description?: scalar.MarkdownOrString | null
   readonly technology?: string | null
   readonly tags?: aux.Tags<A> | null
   readonly links?: readonly Link[] | null

package/src/types/model-dump.ts

@@ -1,5 +1,5 @@
+import type * as aux from './_aux'
 import type { KeysOf } from './_common'
-import type * as aux from './aux'
 import type { _stage } from './const'
 import type { ParsedLikeC4ModelData } from './model-data'
 

package/src/types/model-logical.ts

@@ -1,6 +1,6 @@
+import type * as aux from './_aux'
+import type { AnyAux } from './_aux'
 import type { Link } from './_common'
-import type * as aux from './aux'
-import type { AnyAux } from './aux'
 import type { FqnRef } from './fqnRef'
 import type * as scalar from './scalar'
 import type {
@@ -57,7 +57,7 @@ export interface Element<A extends AnyAux = AnyAux>
   readonly id: aux.StrictFqn<A>
   readonly kind: aux.ElementKind<A>
   readonly title: string
-  readonly description?: string | null
+  readonly description?: scalar.MarkdownOrString | null
   readonly technology?: string | null
   readonly tags?: aux.Tags<A> | null
   readonly links?: readonly Link[] | null
@@ -65,7 +65,7 @@ export interface Element<A extends AnyAux = AnyAux>
   readonly shape?: ElementShape
   readonly color?: Color
   readonly style?: ElementStyle
-  readonly notation?: string
+  readonly notation?: string | null
   readonly metadata?: aux.Metadata<A>
 }
 
@@ -82,7 +82,7 @@ export interface AbstractRelationship<A extends AnyAux>
 {
   readonly id: scalar.RelationId
   readonly title?: string | null
-  readonly description?: string | null
+  readonly description?: scalar.MarkdownOrString | null
   readonly technology?: string | null
   readonly kind?: aux.RelationKind<A>
   readonly color?: Color

package/src/types/model-spec.ts

@@ -1,6 +1,6 @@
 import type { IsNever } from 'type-fest'
-import type * as aux from './aux'
-import type { Any } from './aux'
+import type * as aux from './_aux'
+import type { Any } from './_aux'
 import type * as scalar from './scalar'
 import type {
   Icon,

package/src/types/operators.ts

@@ -1,8 +1,8 @@
 import { allPass, anyPass, isNot, isNullish, isString } from 'remeda'
 import { nonexhaustive } from '../utils/invariant'
+import type * as aux from './_aux'
+import type { Any } from './_aux'
 import type { NonEmptyArray } from './_common'
-import type * as aux from './aux'
-import type { Any } from './aux'
 
 export type EqualOperator<V> = {
   eq: V

package/src/types/scalar.ts

@@ -1,9 +1,54 @@
-import { isTruthy } from 'remeda'
+import { isString, isTruthy } from 'remeda'
 import type { Tagged } from 'type-fest'
-import { invariant } from '../utils/invariant'
+import { invariant } from '../utils'
 
 export type ProjectId<T = string> = Tagged<T, 'ProjectID'>
 
+export type MarkdownOrString = { txt: string; md?: never } | { md: string; txt?: never }
+
+/**
+ * Converts a MarkdownOrString object or a plain string into a simple string representation.
+ * This utility function handles different types of text content and normalizes them to a string format.
+ *
+ * @param value - The content to be flattened.
+ *   Can be one of:
+ *   - A plain string
+ *   - A MarkdownOrString object with either txt or md property
+ *   - undefined or null
+ *
+ * @returns The string content contained within the input value.
+ *   - Returns the input directly if it's already a string
+ *   - Returns the txt property if available in a MarkdownOrString object
+ *   - Falls back to the md property if txt is not available
+ *   - Returns null if:
+ *     - The input is null or undefined
+ *     - The resulting string value is empty, whitespace, or null
+ *
+ * @example
+ * // String input
+ * flattenMarkdownOrString("Hello world") // Returns: "Hello world"
+ * flattenMarkdownOrString("   ") // Returns: null
+ *
+ * // MarkdownOrString with txt property
+ * flattenMarkdownOrString({ txt: "Plain text" }) // Returns: "Plain text"
+ * flattenMarkdownOrString({ txt: "   " }) // Returns: null
+ *
+ * // MarkdownOrString with md property
+ * flattenMarkdownOrString({ md: "**Bold markdown**" }) // Returns: "**Bold markdown**"
+ *
+ * // Null input
+ * flattenMarkdownOrString(null) // Returns: null
+ */
+export function flattenMarkdownOrString(value: MarkdownOrString | string): string
+export function flattenMarkdownOrString(value: MarkdownOrString | string | undefined | null): string | null
+export function flattenMarkdownOrString(value: MarkdownOrString | string | undefined | null): string | null {
+  if (value === null || value === undefined) {
+    return null
+  }
+  const content = isString(value) ? value : value.txt ?? value.md
+  return isTruthy(content?.trim()) ? content : null
+}
+
 export type BuiltInIcon = 'none' | `${'aws' | 'azure' | 'gcp' | 'tech'}:${string}`
 export type Icon = Tagged<string, 'Icon'> | BuiltInIcon
 export type IconUrl = Icon

package/src/types/view-common.ts

@@ -1,6 +1,6 @@
+import type * as aux from './_aux'
+import type { AnyAux } from './_aux'
 import type { NonEmptyArray } from './_common'
-import type * as aux from './aux'
-import type { AnyAux } from './aux'
 import type { _stage } from './const'
 
 import type { BBox, Point, XYPoint } from './geometry'
@@ -106,7 +106,7 @@ export type ViewType = 'element' | 'dynamic' | 'deployment'
 export interface BaseViewProperties<A extends AnyAux> extends aux.WithOptionalTags<A>, aux.WithOptionalLinks {
   readonly id: aux.StrictViewId<A>
   readonly title: string | null
-  readonly description: string | null
+  readonly description: scalar.MarkdownOrString | null
   /**
    * For all views we find common ancestor path.
    * This is used to generate relative paths, i.e.:

package/src/types/view-computed.ts

@@ -1,5 +1,5 @@
-import type * as aux from './aux'
-import type { Any } from './aux'
+import type * as aux from './_aux'
+import type { Any } from './_aux'
 import type { _stage, _type } from './const'
 import type { ElementStyle } from './model-logical'
 import type * as scalar from './scalar'
@@ -26,16 +26,14 @@ export interface ComputedNode<A extends Any = Any> extends aux.WithOptionalLinks
   parent: scalar.NodeId | null
   /**
    * Reference to model element
-   * If 1 - node id is a reference
    */
   modelRef?: aux.Fqn<A> | undefined
   /**
    * Reference to deployment element
-   * If 1 - node id is a reference
    */
   deploymentRef?: aux.DeploymentFqn<A> | undefined
   title: string
-  description?: string | null
+  description?: scalar.MarkdownOrString | null
   technology?: string | null
   notation?: string
   children: scalar.NodeId[]
@@ -62,7 +60,7 @@ export interface ComputedEdge<A extends Any = Any> extends aux.WithOptionalTags<
   source: scalar.NodeId
   target: scalar.NodeId
   label: string | null
-  description?: string
+  description?: scalar.MarkdownOrString | null
   technology?: string
   relations: scalar.RelationId[]
   kind?: aux.RelationKind<A> | typeof scalar.StepEdgeKind

package/src/types/view-layouted.ts

@@ -1,6 +1,6 @@
+import type * as aux from './_aux'
+import type { AnyAux } from './_aux'
 import type { NonEmptyArray } from './_common'
-import type * as aux from './aux'
-import type { AnyAux } from './aux'
 import type { _stage, _type } from './const'
 import type { BBox, Point, XYPoint } from './geometry'
 import type {
@@ -26,6 +26,10 @@ 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> {
@@ -51,6 +55,11 @@ export interface DiagramEdge<A extends AnyAux = AnyAux> extends ComputedEdge<A>
    * @deprecated
    */
   dotpos?: string
+  // label: scalar.HtmlOrString | null
+  // description?: scalar.HtmlOrString | null
+  // technology?: scalar.HtmlOrString | null
+  // notation?: scalar.HtmlOrString | null
+  // notes?: scalar.HtmlOrString | null
 }
 
 interface BaseLayoutedViewProperties<A extends AnyAux> extends BaseViewProperties<A>, ViewWithHash, ViewWithNotation {

package/src/types/view-parsed.deployment.ts

@@ -1,5 +1,5 @@
+import type { AnyAux, Unknown } from './_aux'
 import type { ExclusiveUnion } from './_common'
-import type { AnyAux, Unknown } from './aux'
 import type { _type } from './const'
 import type { Expression, FqnExpr } from './expression'
 import type {

package/src/types/view-parsed.dynamic.ts

@@ -1,8 +1,8 @@
 import { isArray } from 'remeda'
 import type { MergeExclusive, Simplify } from 'type-fest'
+import type * as aux from './_aux'
+import type { AnyAux } from './_aux'
 import type { ExclusiveUnion } from './_common'
-import type * as aux from './aux'
-import type { AnyAux } from './aux'
 import type { _type } from './const'
 import type { ModelFqnExpr } from './expression-model'
 import { isStepEdgeId } from './scalar'

package/src/types/view-parsed.element.ts

@@ -1,6 +1,6 @@
+import type * as aux from './_aux'
+import type { AnyAux } from './_aux'
 import type { ExclusiveUnion } from './_common'
-import type * as aux from './aux'
-import type { AnyAux } from './aux'
 import type { _type } from './const'
 import type { ModelExpression, ModelFqnExpr } from './expression-model'
 import type { BorderStyle, Color, ShapeSize, SpacingSize, TextSize } from './styles'

package/src/types/view.ts

@@ -1,6 +1,6 @@
 import { isTruthy } from 'remeda'
-import type { Any } from './aux'
-import * as aux from './aux'
+import type { Any } from './_aux'
+import * as aux from './_aux'
 import type { _stage, _type, ExtractOnStage, ModelStage } from './const'
 import type { ViewType } from './view-common'
 import type {

package/src/utils/index.ts

@@ -54,9 +54,7 @@ export {
 export { memoizeProp } from './memoize-prop'
 export { delay, promiseNextTick } from './promises'
 
-export {
-  compareRelations,
-} from './relations'
+export { compareRelations } from './relations'
 
 export {
   difference,
@@ -66,10 +64,7 @@ export {
   union,
 } from './set'
 
-export {
-  stringHash,
-} from './string-hash'
+export { objectHash } from './object-hash'
+export { stringHash } from './string-hash'
 
-export {
-  objectHash,
-} from './object-hash'
+export { markdownToHtml, markdownToText } from './markdown'

package/src/utils/markdown/index.ts

@@ -0,0 +1,2 @@
+export { markdownToHtml } from './to-html'
+export { markdownToText } from './to-text'

package/src/utils/markdown/to-html.ts

@@ -0,0 +1,32 @@
+import rehypeRaw from 'rehype-raw'
+import rehypeSanitize from 'rehype-sanitize'
+import rehypeStringify from 'rehype-stringify'
+import remarkGfm from 'remark-gfm'
+import remarkParse from 'remark-parse'
+import remarkRehype from 'remark-rehype'
+import { unified } from 'unified'
+
+// let _remark
+function remark() {
+  return unified()
+    .use(remarkParse)
+    .use(remarkGfm)
+    .use(remarkRehype, {
+      // Tight paragraphs prevent extra newlines
+      allowDangerousHtml: true,
+      clobberPrefix: '',
+      tableCellPadding: false,
+      tight: true,
+    })
+    .use(rehypeRaw)
+    .use(rehypeSanitize)
+    .use(rehypeStringify, {
+      // Prevent extra closing newlines
+      closeSelfClosing: true,
+      tightSelfClosing: true,
+    })
+}
+
+export function markdownToHtml(markdown: string): string {
+  return String(remark().processSync(markdown.trim())).trim()
+}

package/src/utils/markdown/to-text.ts

@@ -0,0 +1,14 @@
+import { fromMarkdown } from 'mdast-util-from-markdown'
+import { toString } from 'mdast-util-to-string'
+
+/**
+ * Converts markdown to plain text, removing any markdown formatting.
+ * @param markdown - The markdown to convert.
+ * @returns The plain text.
+ */
+export function markdownToText(markdown: string): string {
+  return toString(fromMarkdown(markdown), {
+    includeHtml: false,
+    includeImageAlt: false,
+  })
+}

package/dist/types/aux.d.mts

@@ -1,3 +0,0 @@
-import 'type-fest';
-import '../shared/core.BuO4ncfY.mjs';
-export { y as AllKinds, A as Any, A as AnyAux, C as AnySpec, b as Aux, q as DeploymentFqn, u as DeploymentId, D as DeploymentKind, h as EdgeId, g as ElementId, l as ElementKind, F as Fqn, p as LooseDeploymentId, a3 as LooseDeploymentKind, o as LooseElementId, a2 as LooseElementKind, a4 as LooseRelationKind, L as LooseTag, a1 as LooseTags, x as LooseViewId, j as Metadata, k as MetadataKey, N as Never, I as NodeId, a0 as OrString, G as PickByStage, P as ProjectId, m as RelationId, R as RelationKind, J as Spec, S as SpecAux, s as Stage, q as StrictDeploymentFqn, X as StrictDeploymentKind, Q as StrictElementKind, F as StrictFqn, K as StrictProjectId, Y as StrictRelationKind, O as StrictTag, n as StrictViewId, v as Tag, T as Tags, U as Unknown, c as UnknownComputed, d as UnknownLayouted, e as UnknownParsed, V as ViewId, $ as WithLinks, B as WithMetadata, z as WithOptionalLinks, W as WithOptionalTags, Z as WithTags, H as setStage, t as toComputed, r as toLayouted, w as toParsed } from '../shared/core.CBxTtXMi.mjs';