@likec4/core 1.32.2 → 1.33.0

package/src/types/model-deployment.ts

@@ -5,6 +5,7 @@ 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-logical.ts

@@ -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/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

@@ -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

@@ -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

@@ -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/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,
+  })
+}