@likec4/core 1.8.1 → 1.10.0

package/src/types/view.ts

@@ -1,14 +1,14 @@
-import { isNullish } from 'remeda'
+import { isArray, isNullish } from 'remeda'
+import type { Tagged } from 'type-fest'
 import type { IconUrl, NonEmptyArray, Point, XYPoint } from './_common'
 import type { ElementKind, ElementShape, ElementStyle, Fqn, Link, Tag } from './element'
 import type { ElementExpression, ElementPredicateExpression, Expression } from './expression'
-import type { Opaque } from './opaque'
 import type { RelationID, RelationshipArrowType, RelationshipKind, RelationshipLineType } from './relation'
-import type { ThemeColor } from './theme'
+import type { Color, ThemeColorValues } from './theme'
 import type { ElementNotation } from './view-notation'
 
 // Full-qualified-name
-export type ViewID = Opaque<string, 'ViewID'>
+export type ViewID = Tagged<string, 'ViewID'>
 
 export type ViewRulePredicate =
   | {
@@ -30,7 +30,7 @@ export interface ViewRuleStyle {
   targets: ElementExpression[]
   notation?: string
   style: ElementStyle & {
-    color?: ThemeColor
+    color?: Color
     shape?: ElementShape
     icon?: IconUrl
   }
@@ -76,6 +76,8 @@ export interface BasicView<ViewType extends 'element' | 'dynamic'> {
    * If the view is changed manually this field contains the layout data.
    */
   readonly manualLayout?: ViewManualLayout | undefined
+
+  readonly customColorDefinitions: CustomColorDefinitions
 }
 
 export interface BasicElementView extends BasicView<'element'> {
@@ -98,13 +100,24 @@ export interface DynamicViewStep {
   readonly description?: string
   readonly technology?: string
   readonly notation?: string
-  readonly color?: ThemeColor
+  // Notes for walkthrough
+  readonly notes?: string
+  readonly color?: Color
   readonly line?: RelationshipLineType
   readonly head?: RelationshipArrowType
   readonly tail?: RelationshipArrowType
   readonly isBackward?: boolean
+  // Link to dynamic view
+  readonly navigateTo?: ViewID
+  __parallel?: never
+}
+
+export interface DynamicViewParallelSteps {
+  readonly __parallel: DynamicViewStep[]
 }
 
+export type DynamicViewStepOrParallel = DynamicViewStep | DynamicViewParallelSteps
+
 export type DynamicViewIncludeRule = {
   include: ElementPredicateExpression[]
 }
@@ -117,11 +130,17 @@ export type DynamicViewRule = DynamicViewIncludeRule | ViewRuleStyle | ViewRuleA
 export interface DynamicView extends BasicView<'dynamic'> {
   readonly __: 'dynamic'
 
-  readonly steps: DynamicViewStep[]
+  readonly steps: DynamicViewStepOrParallel[]
 
   readonly rules: DynamicViewRule[]
 }
 
+export function isDynamicViewParallelSteps(step: DynamicViewStepOrParallel): step is DynamicViewParallelSteps {
+  return '__parallel' in step && isArray(step.__parallel)
+}
+
+export type CustomColorDefinitions = { [key: string]: ThemeColorValues }
+
 export type LikeC4View = ElementView | DynamicView
 
 export function isDynamicView(view: LikeC4View): view is DynamicView {
@@ -139,23 +158,34 @@ export function isScopedElementView(view: LikeC4View): view is ScopedElementView
   return isElementView(view) && 'viewOf' in view
 }
 
-export type NodeId = Fqn
+export type NodeId = Tagged<string, 'Fqn'>
 
-export type EdgeId = Opaque<string, 'EdgeId'>
-export type StepEdgeIdLiteral = `step-${number}`
-export type StepEdgeId = Opaque<StepEdgeIdLiteral, 'EdgeId'>
-export function StepEdgeId(step: number): StepEdgeId {
-  return `step-${String(step).padStart(3, '0')}` as StepEdgeId
+export type EdgeId = Tagged<string, 'EdgeId'>
+export type StepEdgeIdLiteral = `step-${number}` | `step-${number}.${number}`
+export type StepEdgeId = Tagged<StepEdgeIdLiteral, 'EdgeId'>
+export function StepEdgeId(step: number, parallelStep?: number): StepEdgeId {
+  const id = `step-${String(step).padStart(2, '0')}` as StepEdgeId
+  return parallelStep ? `${id}.${parallelStep}` as StepEdgeId : id
 }
 
 export function isStepEdgeId(id: string): id is StepEdgeId {
   return id.startsWith('step-')
 }
+
 export function extractStep(id: EdgeId): number {
   if (!isStepEdgeId(id)) {
     throw new Error(`Invalid step edge id: ${id}`)
   }
-  return Number(id.slice('step-'.length))
+  return parseFloat(id.slice('step-'.length))
+}
+
+// Get the prefix of the parallel steps
+// i.e. step-01.1 -> step-01.
+export function getParallelStepsPrefix(id: string): string | null {
+  if (isStepEdgeId(id) && id.includes('.')) {
+    return id.slice(0, id.indexOf('.') + 1)
+  }
+  return null
 }
 
 export interface ComputedNode {
@@ -175,7 +205,7 @@ export interface ComputedNode {
   /**
    * @deprecated Use `style` instead
    */
-  color: ThemeColor
+  color: Color
   /**
    * @deprecated Use `style` instead
    */
@@ -201,11 +231,16 @@ export interface ComputedEdge {
   technology?: string
   relations: RelationID[]
   kind?: RelationshipKind
-  color?: ThemeColor
+  notation?: string
+  // Notes for walkthrough
+  notes?: string
+  color?: Color
   line?: RelationshipLineType
   head?: RelationshipArrowType
   tail?: RelationshipArrowType
   tags?: NonEmptyArray<Tag>
+  // Link to dynamic view
+  navigateTo?: ViewID
   /**
    * If this edge is derived from custom relationship predicate
    */

package/src/utils/compare-natural.spec.ts

@@ -0,0 +1,37 @@
+import { sort as remedaSort } from 'remeda'
+import { describe, expect, it } from 'vitest'
+import { compareNatural } from './compare-natural'
+
+describe('compareNatural', () => {
+  const sort = (array: Array<string | undefined>) => remedaSort(array, compareNatural)
+
+  it('should move undefined to the end', () => {
+    expect(
+      sort([
+        undefined,
+        'apple',
+        undefined,
+        'banana'
+      ])
+    ).toEqual([
+      'apple',
+      'banana',
+      undefined,
+      undefined
+    ])
+  })
+
+  it('should sort array of strings', () => {
+    expect(sort([
+      'apple1',
+      'apple11',
+      'apple2',
+      'apple10'
+    ])).toEqual([
+      'apple1',
+      'apple2',
+      'apple10',
+      'apple11'
+    ])
+  })
+})

package/src/utils/compare-natural.ts

@@ -0,0 +1,14 @@
+import compare from 'natural-compare-lite'
+import { isString } from 'remeda'
+
+
+export function compareNatural(a: string | undefined, b: string | undefined): -1 | 0 | 1 {
+  if (a === b) return 0
+  if (isString(a)) {
+    if (isString(b)) {
+      return compare(a, b)
+    }
+    return 1
+  }
+  return isString(b) ? -1 : 0
+}

package/src/utils/fqn.spec.ts

@@ -1,3 +1,4 @@
+import { prop } from 'remeda'
 import { describe, expect, it } from 'vitest'
 import type { Element, Fqn } from '../types'
 import {
@@ -7,7 +8,9 @@ import {
   isAncestor,
   isDescendantOf,
   notDescendantOf,
-  parentFqn
+  parentFqn,
+  sortByFqnHierarchically,
+  sortNaturalByFqn
 } from './fqn'
 
 const el = (id: string): Element => ({ id }) as unknown as Element
@@ -88,7 +91,13 @@ describe('notDescendantOf', () => {
 
 describe('compareFqnHierarchically', () => {
   it('should compare hierarchically', () => {
-    expect(['a', 'b', 'a.b', 'a.b.c', 'a.c.c'].sort(compareFqnHierarchically)).toEqual([
+    expect([
+      'a',
+      'b',
+      'a.b',
+      'a.b.c',
+      'a.c.c'
+    ].sort(compareFqnHierarchically)).toEqual([
       'a',
       'b',
       'a.b',
@@ -103,3 +112,91 @@ describe('compareFqnHierarchically', () => {
     ).toEqual(['aaa', 'aa', 'a', 'aaa.c', 'aa.b', 'a.c', 'a.b'])
   })
 })
+
+describe('sortNaturalByFqn', () => {
+  it('should sort hierarchically', () => {
+    expect(
+      sortNaturalByFqn([
+        el('a.b'),
+        el('a'),
+        el('a.c.a.b'),
+        el('a.c.c'),
+        el('b'),
+        el('a.b.c')
+      ]).map(prop('id'))
+    ).toEqual([
+      'a',
+      'b',
+      'a.b',
+      'a.b.c',
+      'a.c.c',
+      'a.c.a.b'
+    ])
+  })
+
+  it('should sort natural', () => {
+    expect(
+      sortNaturalByFqn([
+        el('b'),
+        el('a.c.c'),
+        el('a'),
+        el('a.b1'),
+        el('a.b2'),
+        el('a.b10'),
+        el('a.b2.c')
+      ]).map(prop('id'))
+    ).toEqual([
+      'a',
+      'b',
+      'a.b1',
+      'a.b2',
+      'a.b10',
+      'a.b2.c',
+      'a.c.c'
+    ])
+  })
+})
+
+describe('sortByFqnHierarchically', () => {
+  it('should sort hierarchically', () => {
+    expect(
+      sortByFqnHierarchically([
+        el('a.b'),
+        el('a'),
+        el('a.b.c'),
+        el('a.c.a.b'),
+        el('a.c.c'),
+        el('b')
+      ]).map(prop('id'))
+    ).toEqual([
+      'a',
+      'b',
+      'a.b',
+      'a.b.c',
+      'a.c.c',
+      'a.c.a.b'
+    ])
+  })
+
+  it('should preserve initial order', () => {
+    expect(
+      sortByFqnHierarchically([
+        el('b'),
+        el('a.c.c'),
+        el('a'),
+        el('a.b10'),
+        el('a.b2.c'),
+        el('a.b1'),
+        el('a.b2')
+      ]).map(prop('id'))
+    ).toEqual([
+      'b',
+      'a',
+      'a.b10',
+      'a.b1',
+      'a.b2',
+      'a.c.c',
+      'a.b2.c'
+    ])
+  })
+})

package/src/utils/fqn.ts

@@ -1,4 +1,5 @@
 import type { Element, Fqn } from '../types'
+import { compareNatural } from './compare-natural'
 import { isString } from './guards'
 
 type Predicate<T> = (x: T) => boolean
@@ -61,7 +62,7 @@ export function commonAncestor(first: Fqn, second: Fqn) {
 export function parentFqn(fqn: Fqn): Fqn | null {
   const lastDot = fqn.lastIndexOf('.')
   if (lastDot > 0) {
-    return fqn.substring(0, lastDot) as Fqn
+    return fqn.slice(0, lastDot) as Fqn
   }
   return null
 }
@@ -81,9 +82,12 @@ export function ancestorsFqn(fqn: Fqn): Fqn[] {
   if (path.length === 0) {
     return []
   }
-  return path.reduce((acc, _, idx) => {
-    const ancestor = path.slice(0, idx + 1).join('.')
-    acc.unshift(ancestor as Fqn)
+  return path.reduce((acc, part, idx) => {
+    if (idx === 0) {
+      acc.push(part as Fqn)
+      return acc
+    }
+    acc.unshift(`${acc[0]}.${part}` as Fqn)
     return acc
   }, [] as Fqn[])
 }
@@ -98,7 +102,7 @@ export function ancestorsFqn(fqn: Fqn): Fqn[] {
  *                    - Positive number if a is deeper than b.
  *                    - Negative number if b is deeper than a.
  */
-export function compareFqnHierarchically<T extends string = string>(a: T, b: T): number {
+export function compareFqnHierarchically<T extends string = string>(a: T, b: T): -1 | 0 | 1 {
   const depthA = a.split('.').length
   const depthB = b.split('.').length
   switch (true) {
@@ -117,3 +121,39 @@ export function compareFqnHierarchically<T extends string = string>(a: T, b: T):
 export function compareByFqnHierarchically<T extends { id: string }>(a: T, b: T) {
   return compareFqnHierarchically(a.id, b.id)
 }
+
+type IterableContainer<T = unknown> = ReadonlyArray<T> | readonly []
+type ReorderedArray<T extends IterableContainer> = {
+  -readonly [P in keyof T]: T[number]
+}
+
+export function sortByFqnHierarchically<T extends { id: string }, A extends IterableContainer<T>>(
+  array: A
+): ReorderedArray<A> {
+  return array
+    .map(item => ({ item, fqn: item.id.split('.') }))
+    .sort((a, b) => {
+      return a.fqn.length - b.fqn.length
+    })
+    .map(({ item }) => item) as ReorderedArray<A>
+}
+
+export function sortNaturalByFqn<T extends { id: string }, A extends IterableContainer<T>>(
+  array: A
+): ReorderedArray<A> {
+  return array
+    .map(item => ({ item, fqn: item.id.split('.') }))
+    .sort((a, b) => {
+      if (a.fqn.length !== b.fqn.length) {
+        return a.fqn.length - b.fqn.length
+      }
+      for (let i = 0; i < a.fqn.length; i++) {
+        const compare = compareNatural(a.fqn[i], b.fqn[i])
+        if (compare !== 0) {
+          return compare
+        }
+      }
+      return 0
+    })
+    .map(({ item }) => item) as ReorderedArray<A>
+}

package/src/utils/index.ts

@@ -1,3 +1,4 @@
+export * from './compare-natural'
 export * from './fqn'
 export * from './guards'
 export * from './promises'

package/src/utils/relations.spec.ts

@@ -1,8 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import type { Fqn, Relation, RelationID } from '../types'
-import { compareRelations, Relations } from './relations'
-
-const { isAnyBetween, isAnyInOut, isBetween, isIncoming, isInside, isOutgoing } = Relations
+import { compareRelations, isAnyBetween, isAnyInOut, isBetween, isIncoming, isInside, isOutgoing } from './relations'
 
 const relations = [
   {
@@ -172,7 +170,7 @@ describe('compareRelations', () => {
     }
   }
   function sorted(...relations: Array<{ source: string; target: string }>) {
-    return relations.sort(compareRelations).map(r => r.source + ' -> ' + r.target)
+    return relations.toSorted(compareRelations).map(r => r.source + ' -> ' + r.target)
   }
 
   it('should sort by source and target', () => {

package/src/utils/relations.ts

@@ -22,24 +22,24 @@ export const compareRelations = <T extends { source: string; target: string }>(a
     return -1
   }
   const compareParents = parentA && parentB ? compareFqnHierarchically(parentA, parentB) : 0
-  if (compareParents === 0) {
-    const compareSource = compareFqnHierarchically(a.source, b.source)
-    if (compareSource !== 0) {
-      return compareSource
-    }
-    return compareFqnHierarchically(a.target, b.target)
+  if (compareParents !== 0) {
+    return compareParents
   }
-  return compareParents
+  const compareSource = compareFqnHierarchically(a.source, b.source)
+  if (compareSource !== 0) {
+    return compareSource
+  }
+  return compareFqnHierarchically(a.target, b.target)
 }
 
-const isInside = (parent: Fqn): RelationPredicate => {
+export const isInside = (parent: Fqn): RelationPredicate => {
   const prefix = parent + '.'
   return (rel: Relation) => {
     return rel.source.startsWith(prefix) && rel.target.startsWith(prefix)
   }
 }
 
-const isBetween = (source: Fqn, target: Fqn): RelationPredicate => {
+export const isBetween = (source: Fqn, target: Fqn): RelationPredicate => {
   const sourcePrefix = source + '.'
   const targetPrefix = target + '.'
   return (rel: Relation) => {
@@ -50,12 +50,12 @@ const isBetween = (source: Fqn, target: Fqn): RelationPredicate => {
   }
 }
 
-const isAnyBetween = (source: Fqn, target: Fqn): RelationPredicate => {
+export const isAnyBetween = (source: Fqn, target: Fqn): RelationPredicate => {
   const predicates = [isBetween(source, target), isBetween(target, source)]
   return (rel) => predicates.some(p => p(rel))
 }
 
-const isIncoming = (target: Fqn): RelationPredicate => {
+export const isIncoming = (target: Fqn): RelationPredicate => {
   const targetPrefix = target + '.'
   return (rel: Relation) => {
     return (
@@ -65,7 +65,7 @@ const isIncoming = (target: Fqn): RelationPredicate => {
   }
 }
 
-const isOutgoing = (source: Fqn): RelationPredicate => {
+export const isOutgoing = (source: Fqn): RelationPredicate => {
   const sourcePrefix = source + '.'
   return (rel: Relation) => {
     return (
@@ -75,14 +75,14 @@ const isOutgoing = (source: Fqn): RelationPredicate => {
   }
 }
 
-const isAnyInOut = (source: Fqn): RelationPredicate => {
+export const isAnyInOut = (source: Fqn): RelationPredicate => {
   const predicates = [isIncoming(source), isOutgoing(source)]
   return (rel: Relation) => {
     return predicates.some(p => p(rel))
   }
 }
 
-const hasRelation = <R extends { source: Fqn; target: Fqn }>(rel: R) => {
+export const hasRelation = <R extends { source: Fqn; target: Fqn }>(rel: R) => {
   return <E extends { id: Fqn }>(element: E) => {
     return (
       rel.source === element.id
@@ -92,13 +92,3 @@ const hasRelation = <R extends { source: Fqn; target: Fqn }>(rel: R) => {
     )
   }
 }
-
-export const Relations = {
-  isInside,
-  isBetween,
-  isAnyBetween,
-  isIncoming,
-  isOutgoing,
-  isAnyInOut,
-  hasRelation
-} as const

package/dist/colors/element.d.ts

@@ -1,69 +0,0 @@
-export declare const ElementColors: {
-    readonly primary: {
-        fill: "#3b82f6";
-        stroke: "#2563eb";
-        hiContrast: "#eff6ff";
-        loContrast: "#bfdbfe";
-    };
-    readonly blue: {
-        fill: "#3b82f6";
-        stroke: "#2563eb";
-        hiContrast: "#eff6ff";
-        loContrast: "#bfdbfe";
-    };
-    readonly secondary: {
-        fill: "#0284c7";
-        stroke: "#0369a1";
-        hiContrast: "#f0f9ff";
-        loContrast: "#B6ECF7";
-    };
-    readonly sky: {
-        fill: "#0284c7";
-        stroke: "#0369a1";
-        hiContrast: "#f0f9ff";
-        loContrast: "#B6ECF7";
-    };
-    readonly muted: {
-        fill: "#64748b";
-        stroke: "#475569";
-        hiContrast: "#f8fafc";
-        loContrast: "#cbd5e1";
-    };
-    readonly slate: {
-        fill: "#64748b";
-        stroke: "#475569";
-        hiContrast: "#f8fafc";
-        loContrast: "#cbd5e1";
-    };
-    readonly gray: {
-        readonly fill: "#737373";
-        readonly stroke: "#525252";
-        readonly hiContrast: "#fafafa";
-        readonly loContrast: "#d4d4d4";
-    };
-    readonly red: {
-        readonly fill: "#AC4D39";
-        readonly stroke: "#853A2D";
-        readonly hiContrast: "#FBD3CB";
-        readonly loContrast: "#f5b2a3";
-    };
-    readonly green: {
-        readonly fill: "#428a4f";
-        readonly stroke: "#2d5d39";
-        readonly hiContrast: "#f8fafc";
-        readonly loContrast: "#c2f0c2";
-    };
-    readonly amber: {
-        readonly fill: "#A35829";
-        readonly stroke: "#7E451D";
-        readonly hiContrast: "#FFE0C2";
-        readonly loContrast: "#f9b27c";
-    };
-    readonly indigo: {
-        readonly fill: "#6366f1";
-        readonly stroke: "#4f46e5";
-        readonly hiContrast: "#eef2ff";
-        readonly loContrast: "#c7d2fe";
-    };
-};
-//# sourceMappingURL=element.d.ts.map

package/dist/colors/element.js

@@ -1,75 +0,0 @@
-const blue = {
-    fill: '#3b82f6',
-    stroke: '#2563eb',
-    hiContrast: '#eff6ff',
-    loContrast: '#bfdbfe'
-};
-const sky = {
-    fill: '#0284c7',
-    stroke: '#0369a1',
-    hiContrast: '#f0f9ff',
-    loContrast: '#B6ECF7'
-};
-const slate = {
-    fill: '#64748b',
-    stroke: '#475569',
-    hiContrast: '#f8fafc',
-    loContrast: '#cbd5e1'
-};
-export const ElementColors = {
-    primary: blue,
-    blue,
-    secondary: sky,
-    sky,
-    muted: slate,
-    slate,
-    gray: {
-        // fill: colors.neutral[500],
-        // stroke: colors.neutral[600],
-        // hiContrast: colors.neutral[50],
-        // loContrast: colors.neutral[200],
-        fill: '#737373',
-        stroke: '#525252',
-        hiContrast: '#fafafa',
-        loContrast: '#d4d4d4'
-    },
-    red: {
-        // fill: colors.red[500],
-        // stroke: colors.red[600],
-        // hiContrast: colors.red[50],
-        // loContrast: colors.red[200],
-        fill: '#AC4D39',
-        // fill: '#b54548',
-        stroke: '#853A2D',
-        // hiContrast: '#fef2f2',
-        // loContrast: '#fecaca',
-        // hiContrast: '#191111', // colors.gray[900],
-        // loContrast: '#3b1219' // colors.gray[800],
-        hiContrast: '#FBD3CB',
-        // hiContrast: '#f8fafc',
-        // loContrast: '#fdd8d8' // radix black red 12
-        loContrast: '#f5b2a3'
-    },
-    green: {
-        fill: '#428a4f',
-        stroke: '#2d5d39',
-        hiContrast: '#f8fafc',
-        loContrast: '#c2f0c2'
-    },
-    amber: {
-        fill: '#A35829',
-        stroke: '#7E451D',
-        hiContrast: '#FFE0C2',
-        loContrast: '#f9b27c'
-    },
-    indigo: {
-        // fill: colors.indigo[500],
-        // stroke: colors.indigo[600],
-        // hiContrast: colors.indigo[50],
-        // loContrast: colors.indigo[200],
-        fill: '#6366f1',
-        stroke: '#4f46e5',
-        hiContrast: '#eef2ff',
-        loContrast: '#c7d2fe'
-    }
-};