@likec4/core 1.8.1 → 1.10.0

package/src/model/__test__/fixture.ts

@@ -0,0 +1,333 @@
+import { mapToObj } from 'remeda'
+import type { LiteralUnion, Tagged, UnwrapTagged } from 'type-fest'
+import {
+  type ComputedLikeC4Model,
+  type Element,
+  type ElementKindSpecification,
+  type NonEmptyArray,
+  type Relation,
+  type RelationshipArrowType,
+  type RelationshipLineType,
+  type Tag,
+  type ThemeColor
+} from '../../types'
+
+/**
+              ┌──────────────────────────────────────────────────┐
+              │                      cloud                       │
+              │  ┌───────────────────────────────────────────┐   │
+              │  │                 frontend                  │   │
+┏━━━━━━━━━━┓  │  │   ┏━━━━━━━━━━━━━┓   ┏━━━━━━━━━━━━━━━━┓    │   │   ┏━━━━━━━━━━━┓
+┃          ┃  │  │   ┃             ┃   ┃                ┃    │   │   ┃           ┃
+┃ customer ┃──┼──┼──▶┃  dashboard  ┃   ┃   adminpanel   ┃◀───┼───┼───┃  support  ┃
+┃          ┃  │  │   ┃             ┃   ┃                ┃    │   │   ┃           ┃
+┗━━━━━━━━━━┛  │  │   ┗━━━━━━┳━━━━━━┛   ┗━━━━━━━━┳━━━━━━━┛    │   │   ┗━━━━━━━━━━━┛
+              │  └──────────┼───────────────────┼────────────┘   │
+              │             ├───────────────────┘                │
+              │             │                                    │
+              │  ┌──────────┼────────────────────────────────┐   │
+              │  │          ▼       backend                  │   │
+              │  │   ┏━━━━━━━━━━━━━┓       ┏━━━━━━━━━━━━━┓   │   │
+              │  │   ┃             ┃       ┃             ┃   │   │
+              │  │   ┃  graphlql   ┃──────▶┃   storage   ┃   │   │
+              │  │   ┃             ┃       ┃             ┃   │   │
+              │  │   ┗━━━━━━━━━━━━━┛       ┗━━━━━━┳━━━━━━┛   │   │
+              │  └────────────────────────────────┼──────────┘   │
+              └───────────────────────────────────┼──────────────┘
+                                                  │
+                                        ┌─────────┼─────────┐
+                                        │ amazon  │         │
+                                        │         ▼         │
+                                        │ ┏━━━━━━━━━━━━━━┓  │
+                                        │ ┃              ┃  │
+                                        │ ┃      s3      ┃  │
+                                        │ ┃              ┃  │
+                                        │ ┗━━━━━━━━━━━━━━┛  │
+                                        └───────────────────┘
+
+specification {
+  element actor
+  element system
+  element container
+  element component
+
+  tag old
+}
+
+model {
+
+  actor customer
+  actor support
+
+  system cloud {
+    container backend {
+      component graphql
+      component storage {
+        #old
+      }
+
+      graphql -> storage
+    }
+
+    container frontend {
+      component dashboard {
+        -> graphql
+      }
+      component adminPanel {
+        #old
+        -> graphql
+      }
+    }
+  }
+
+  customer -> dashboard
+  support -> adminPanel
+
+  system amazon {
+    component s3
+
+    cloud.backend.storage -> s3
+  }
+
+}
+
+ */
+type TestTag = 'old' | 'next' | 'aws' | 'storage' | 'communication' | 'legacy'
+
+const el = <Id extends string, Kind extends string>({
+  id,
+  kind,
+  title,
+  style,
+  tags,
+  ...props
+}: Partial<Omit<Element, 'id' | 'kind' | 'tags'>> & {
+  id: Id
+  kind: Kind
+  tags?: NonEmptyArray<TestTag>
+}) =>
+  ({
+    id: id as Tagged<Id, 'Fqn'>,
+    kind: kind as Tagged<Kind, 'ElementKind'>,
+    title: title ?? id,
+    description: null,
+    technology: null,
+    tags: tags as NonEmptyArray<Tag> ?? null,
+    links: null,
+    style: {
+      ...style
+    },
+    ...props
+  }) satisfies Element
+
+const fakeElementsArr = [
+  el({
+    id: 'customer',
+    kind: 'actor',
+    title: 'customer',
+    shape: 'person'
+  }),
+  el({
+    id: 'support',
+    kind: 'actor',
+    title: 'support',
+    shape: 'person'
+  }),
+  el({
+    id: 'cloud',
+    kind: 'system',
+    title: 'cloud',
+    tags: ['next', 'old']
+  }),
+  el({
+    id: 'cloud.backend',
+    kind: 'container',
+    title: 'backend'
+  }),
+  el({
+    id: 'cloud.frontend',
+    kind: 'container',
+    title: 'frontend',
+    shape: 'browser'
+  }),
+  el({
+    id: 'cloud.backend.graphql',
+    kind: 'component',
+    title: 'graphql'
+  }),
+  el({
+    id: 'email',
+    kind: 'system',
+    title: 'email'
+  }),
+  el({
+    id: 'cloud.backend.storage',
+    kind: 'component',
+    title: 'storage',
+    tags: ['storage', 'old']
+  }),
+  el({
+    id: 'cloud.frontend.adminPanel',
+    kind: 'component',
+    title: 'adminPanel',
+    tags: ['old']
+  }),
+  el({
+    id: 'cloud.frontend.dashboard',
+    kind: 'component',
+    title: 'dashboard',
+    tags: ['next']
+  }),
+  el({
+    id: 'amazon',
+    kind: 'system',
+    title: 'amazon',
+    tags: ['aws']
+  }),
+  el({
+    id: 'amazon.s3',
+    kind: 'component',
+    title: 's3',
+    shape: 'storage',
+    tags: ['aws', 'storage']
+  })
+] as const
+
+export type FakeElementIds = UnwrapTagged<(typeof fakeElementsArr)[number]['id']>
+export type FakeElementKinds = UnwrapTagged<(typeof fakeElementsArr)[number]['kind']>
+
+export const fakeElements = mapToObj(fakeElementsArr, e => [e.id as FakeElementIds, e])
+
+const rel = <Source extends FakeElementIds, Target extends FakeElementIds, Kind extends string>({
+  source,
+  target,
+  title,
+  kind,
+  tags,
+  ...props
+}: {
+  source: LiteralUnion<Source, string>
+  target: LiteralUnion<Target, string>
+  title?: string
+  kind?: LiteralUnion<Kind, string>
+  color?: ThemeColor
+  line?: RelationshipLineType
+  head?: RelationshipArrowType
+  tail?: RelationshipArrowType
+  tags?: NonEmptyArray<TestTag>
+}) =>
+  ({
+    id: `${source}:${target}` as Tagged<`${Source}:${Target}`, 'RelationID'>,
+    title: title ?? '',
+    source: source as Tagged<Source, 'Fqn'>,
+    target: target as Tagged<Target, 'Fqn'>,
+    ...(kind ? { kind: kind as Tagged<Kind, 'RelationshipKind'> } : {}),
+    tags: tags as NonEmptyArray<Tag> ?? null,
+    ...props
+  }) satisfies Relation
+
+const fakeRelationsArr = [
+  rel({
+    source: 'customer',
+    target: 'cloud.frontend.dashboard',
+    title: 'opens in browser'
+  }),
+  rel({
+    source: 'support',
+    target: 'cloud.frontend.adminPanel',
+    title: 'manages'
+  }),
+  rel({
+    source: 'cloud.backend.storage',
+    target: 'amazon.s3',
+    title: 'uploads',
+    tags: ['aws', 'storage', 'legacy']
+  }),
+  rel({
+    source: 'customer',
+    target: 'cloud',
+    title: 'uses'
+  }),
+  rel({
+    source: 'cloud.backend.graphql',
+    target: 'cloud.backend.storage',
+    title: 'stores',
+    tags: ['old', 'storage']
+  }),
+  rel({
+    source: 'cloud.frontend',
+    target: 'cloud.backend',
+    title: 'requests'
+  }),
+  rel({
+    source: 'cloud.frontend.dashboard',
+    target: 'cloud.backend.graphql',
+    kind: 'graphlql',
+    title: 'requests',
+    line: 'solid',
+    tags: ['next']
+  }),
+  rel({
+    source: 'cloud.frontend.adminPanel',
+    target: 'cloud.backend.graphql',
+    kind: 'graphlql',
+    title: 'fetches',
+    line: 'dashed',
+    tail: 'odiamond',
+    tags: ['old']
+  }),
+  rel({
+    source: 'cloud',
+    target: 'amazon',
+    title: 'uses',
+    head: 'diamond',
+    tail: 'odiamond',
+    tags: ['aws']
+  }),
+  rel({
+    source: 'cloud.backend',
+    target: 'email',
+    title: 'schedule',
+    tags: ['communication']
+  }),
+  rel({
+    source: 'cloud',
+    target: 'email',
+    title: 'uses',
+    tags: ['communication']
+  }),
+  rel({
+    source: 'email',
+    target: 'cloud',
+    title: 'notifies',
+    tags: ['communication']
+  })
+] as const
+
+export type FakeRelationIds = UnwrapTagged<(typeof fakeRelationsArr)[number]['id']>
+
+export const fakeRelations = mapToObj(fakeRelationsArr, r => [r.id as FakeRelationIds, r])
+
+export const fakeComputedModel = {
+  specification: {
+    tags: [],
+    relationships: {},
+    elements: {
+      actor: {
+        style: {}
+      },
+      system: {
+        style: {}
+      },
+      container: {
+        style: {}
+      },
+      component: {
+        style: {}
+      }
+    } satisfies Record<FakeElementKinds, ElementKindSpecification>
+  },
+  elements: fakeElements,
+  relations: fakeRelations,
+  views: {}
+} satisfies ComputedLikeC4Model

package/src/model/index.ts

@@ -0,0 +1,2 @@
+export * from './LikeC4Model'
+export * from './LikeC4ViewModel'

package/src/model/types.ts

@@ -0,0 +1,10 @@
+import type { Fqn as CoreFqn } from '../types/element'
+import type { RelationID as CoreRelationID } from '../types/relation'
+import type { EdgeId as CoreEdgeId, ViewID as CoreViewID } from '../types/view'
+
+import type { LiteralUnion } from 'type-fest'
+
+export type Fqn = LiteralUnion<CoreFqn, string>
+export type RelationID = LiteralUnion<CoreRelationID, string>
+export type ViewID = LiteralUnion<CoreViewID, string>
+export type EdgeId = LiteralUnion<CoreEdgeId, string>

package/src/types/_common.ts

@@ -1,8 +1,10 @@
-import type { Opaque } from './opaque'
+import type { Tagged } from 'type-fest'
 
 export type NonEmptyArray<T> = [T, ...T[]]
 
-export type IconUrl = Opaque<string, 'IconUrl'>
+export type IconUrl = Tagged<string, 'IconUrl'>
+
+export type CustomColor = string
 
 export type Point = readonly [x: number, y: number]
 

package/src/types/element.ts

@@ -1,9 +1,9 @@
+import type { Tagged } from 'type-fest'
 import type { IconUrl, NonEmptyArray } from './_common'
-import type { Opaque } from './opaque'
-import type { ThemeColor } from './theme'
+import type { Color, ThemeColor } from './theme'
 
 // Full-qualified-name
-export type Fqn = Opaque<string, 'Fqn'>
+export type Fqn = Tagged<string, 'Fqn'>
 
 export function AsFqn(name: string, parent?: Fqn | null) {
   return (parent ? parent + '.' + name : name) as Fqn
@@ -13,7 +13,7 @@ export const BorderStyles = ['solid', 'dashed', 'dotted', 'none'] as const
 
 export type BorderStyle = typeof BorderStyles[number]
 
-export type ElementKind = Opaque<string, 'ElementKind'>
+export type ElementKind = Tagged<string, 'ElementKind'>
 export const ElementShapes = [
   'rectangle',
   'person',
@@ -34,7 +34,7 @@ export interface ElementStyle {
   opacity?: number
 }
 
-export type Tag = Opaque<string, 'Tag'>
+export type Tag = Tagged<string, 'Tag'>
 
 export interface TagSpec {
   readonly id: Tag
@@ -42,8 +42,11 @@ export interface TagSpec {
 }
 
 export interface Link {
-  readonly title?: string,
+  readonly title?: string
+  // Value from Likec4 DSL
   readonly url: string
+  // Relative to workspace root (if url is relative),
+  readonly relative?: string
 }
 
 export interface Element {
@@ -56,7 +59,7 @@ export interface Element {
   readonly links: NonEmptyArray<Link> | null
   readonly icon?: IconUrl
   readonly shape?: ElementShape
-  readonly color?: ThemeColor
+  readonly color?: Color
   readonly style?: ElementStyle
   readonly notation?: string
   readonly metadata?: { [key: string]: string }
@@ -65,7 +68,7 @@ export interface Element {
 export interface ElementKindSpecificationStyle {
   shape?: ElementShape
   icon?: IconUrl
-  color?: ThemeColor
+  color?: Color
   border?: BorderStyle
   opacity?: number
 }

package/src/types/expression.ts

@@ -2,7 +2,7 @@ import type { IconUrl } from './_common'
 import type { BorderStyle, ElementKind, ElementShape, Fqn, Tag } from './element'
 import type { WhereOperator } from './operators'
 import type { RelationshipArrowType, RelationshipLineType } from './relation'
-import type { ThemeColor } from './theme'
+import type { Color } from './theme'
 import type { ViewID } from './view'
 
 interface BaseExpr {
@@ -46,7 +46,7 @@ export interface CustomElementExpr extends Omit<BaseExpr, 'custom'> {
     technology?: string
     notation?: string
     shape?: ElementShape
-    color?: ThemeColor
+    color?: Color
     icon?: IconUrl
     border?: BorderStyle
     opacity?: number
@@ -161,7 +161,11 @@ export interface CustomRelationExpr extends Omit<BaseExpr, 'customRelation'> {
     description?: string
     technology?: string
     notation?: string
-    color?: ThemeColor
+    // Link to dynamic view
+    navigateTo?: ViewID
+    // Notes for walkthrough
+    notes?: string
+    color?: Color
     line?: RelationshipLineType
     head?: RelationshipArrowType
     tail?: RelationshipArrowType

package/src/types/index.ts

@@ -2,7 +2,6 @@ export * from './_common'
 export * from './element'
 export * from './expression'
 export * from './model'
-export * from './opaque'
 export * from './operators'
 export * from './overview-graph'
 export * from './relation'

package/src/types/model.ts

@@ -1,15 +1,25 @@
-import type { Element, Fqn } from './element'
-import type { Relation, RelationID } from './relation'
+import type { UnwrapTagged } from 'type-fest'
+import type { Element, ElementKind, ElementKindSpecification, Fqn, Tag } from './element'
+import type { Relation, RelationID, RelationshipKindSpecification } from './relation'
 import type { ComputedView, LikeC4View, ViewID } from './view'
 
-export interface LikeC4Model {
+/**
+ * Parsed elements, relations, and views.
+ */
+export interface ParsedLikeC4Model {
+  specification: {
+    tags: Tag[]
+    elements: Record<UnwrapTagged<ElementKind>, ElementKindSpecification>
+    relationships: Record<UnwrapTagged<ElementKind>, RelationshipKindSpecification>
+  }
   elements: Record<Fqn, Element>
   relations: Record<RelationID, Relation>
   views: Record<ViewID, LikeC4View>
 }
 
-export interface LikeC4ComputedModel {
-  elements: Record<Fqn, Element>
-  relations: Record<RelationID, Relation>
+/**
+ * Same as `ParsedLikeC4Model` but with computed views.
+ */
+export interface ComputedLikeC4Model extends Omit<ParsedLikeC4Model, 'views'> {
   views: Record<ViewID, ComputedView>
 }

package/src/types/relation.ts

@@ -1,10 +1,11 @@
+import type { Tagged } from 'type-fest'
 import type { NonEmptyArray } from './_common'
 import type { Fqn, Link, Tag } from './element'
-import type { Opaque } from './opaque'
-import type { ThemeColor } from './theme'
+import type { Color, ThemeColor } from './theme'
+import type { ViewID } from './view'
 
-export type RelationID = Opaque<string, 'RelationID'>
-export type RelationshipKind = Opaque<string, 'RelationshipKind'>
+export type RelationID = Tagged<string, 'RelationID'>
+export type RelationshipKind = Tagged<string, 'RelationshipKind'>
 
 export type RelationshipLineType = 'dashed' | 'solid' | 'dotted'
 
@@ -25,6 +26,7 @@ export const DefaultLineStyle = 'dashed' satisfies RelationshipLineType
 export const DefaultArrowType = 'normal' satisfies RelationshipArrowType
 export const DefaultRelationshipColor = 'gray' satisfies ThemeColor
 
+// TODO: rename to Relationship
 export interface Relation {
   readonly id: RelationID
   readonly source: Fqn
@@ -34,10 +36,21 @@ export interface Relation {
   readonly technology?: string
   readonly tags?: NonEmptyArray<Tag>
   readonly kind?: RelationshipKind
-  readonly color?: ThemeColor
+  readonly color?: Color
   readonly line?: RelationshipLineType
   readonly head?: RelationshipArrowType
   readonly tail?: RelationshipArrowType
   readonly links?: NonEmptyArray<Link>
+  // Link to dynamic view
+  readonly navigateTo?: ViewID
   readonly metadata?: { [key: string]: string }
 }
+
+export interface RelationshipKindSpecification {
+  readonly technology?: string
+  readonly notation?: string
+  readonly color?: Color
+  readonly line?: RelationshipLineType
+  readonly head?: RelationshipArrowType
+  readonly tail?: RelationshipArrowType
+}

package/src/types/theme.ts

@@ -1,20 +1,31 @@
-export type ThemeColor =
-  | 'amber'
-  | 'blue'
-  | 'gray'
-  | 'slate'
-  | 'green'
-  | 'indigo'
-  | 'muted'
-  | 'primary'
-  | 'red'
-  | 'secondary'
-  | 'sky'
+import type { LiteralUnion } from 'type-fest'
+import type { CustomColor } from './_common'
+
+const ThemeColors = [
+  'amber',
+  'blue',
+  'gray',
+  'slate',
+  'green',
+  'indigo',
+  'muted',
+  'primary',
+  'red',
+  'secondary',
+  'sky'
+] as const
+export type ThemeColor = typeof ThemeColors[number]
 
 export type HexColorLiteral = `#${string}`
 
 export type ColorLiteral = HexColorLiteral
 
+export type Color = LiteralUnion<ThemeColor, string>
+
+export function isThemeColor(color: Color): color is ThemeColor {
+  return color in ThemeColors
+}
+
 export interface ElementThemeColorValues {
   fill: ColorLiteral
   stroke: ColorLiteral
@@ -34,6 +45,11 @@ export interface RelationshipThemeColorValues {
   labelColor: ColorLiteral
 }
 
+export interface ThemeColorValues {
+  elements: ElementThemeColorValues
+  relationships: RelationshipThemeColorValues
+}
+
 export type RelationshipThemeColors = {
   [key in ThemeColor]: RelationshipThemeColorValues
 }

package/src/types/view-notation.ts

@@ -1,10 +1,9 @@
-import type { RequireAtLeastOne } from 'type-fest'
-import type { BorderStyle, ElementKind, ElementShape } from './element'
-import type { ThemeColor } from './theme'
+import type { ElementKind, ElementShape } from './element'
+import type { Color } from './theme'
 
 export type ElementNotation = {
   kinds: ElementKind[]
   shape: ElementShape
-  color: ThemeColor
+  color: Color
   title: string
 }