@likec4/core 1.2.0 → 1.2.1

package/src/types/theme.ts

@@ -0,0 +1,46 @@
+export type ThemeColor =
+  | 'amber'
+  | 'blue'
+  | 'gray'
+  | 'slate'
+  | 'green'
+  | 'indigo'
+  | 'muted'
+  | 'primary'
+  | 'red'
+  | 'secondary'
+  | 'sky'
+
+export type HexColorLiteral = `#${string}`
+
+export type ColorLiteral = HexColorLiteral
+
+export interface ElementThemeColorValues {
+  fill: ColorLiteral
+  stroke: ColorLiteral
+  // Main text (title, etc.)
+  hiContrast: ColorLiteral
+  // Secondary text (description, etc.)
+  loContrast: ColorLiteral
+}
+
+export type ElementThemeColors = {
+  [key in ThemeColor]: ElementThemeColorValues
+}
+
+export interface RelationshipThemeColorValues {
+  lineColor: ColorLiteral
+  labelBgColor: ColorLiteral
+  labelColor: ColorLiteral
+}
+
+export type RelationshipThemeColors = {
+  [key in ThemeColor]: RelationshipThemeColorValues
+}
+
+export interface LikeC4Theme {
+  font: 'Helvetica' // for now only support Helvetica
+  shadow: ColorLiteral
+  relationships: RelationshipThemeColors
+  elements: ElementThemeColors
+}

package/src/types/view.ts

@@ -0,0 +1,263 @@
+import { isNullish } from 'remeda'
+import type { IconUrl, NonEmptyArray } from './_common'
+import type { ElementKind, ElementShape, ElementStyle, Fqn, Tag } from './element'
+import type { CustomElementExpr, ElementExpression, Expression } from './expression'
+import type { Opaque } from './opaque'
+import type { RelationID, RelationshipArrowType, RelationshipLineType } from './relation'
+import type { ColorLiteral, ThemeColor } from './theme'
+
+// Full-qualified-name
+export type ViewID = Opaque<string, 'ViewID'>
+
+export type ViewRuleExpression =
+  | {
+    include: Expression[]
+    exclude?: never
+  }
+  | {
+    include?: never
+    exclude: Expression[]
+  }
+export function isViewRuleExpression(rule: ViewRule): rule is ViewRuleExpression {
+  return (
+    ('include' in rule && Array.isArray(rule.include))
+    || ('exclude' in rule && Array.isArray(rule.exclude))
+  )
+}
+
+export interface ViewRuleStyle {
+  targets: ElementExpression[]
+  style: ElementStyle & {
+    color?: ThemeColor
+    shape?: ElementShape
+    icon?: IconUrl
+  }
+}
+export function isViewRuleStyle(rule: ViewRule): rule is ViewRuleStyle {
+  return 'style' in rule && 'targets' in rule
+}
+
+export type AutoLayoutDirection = 'TB' | 'BT' | 'LR' | 'RL'
+export interface ViewRuleAutoLayout {
+  autoLayout: AutoLayoutDirection
+}
+export function isViewRuleAutoLayout(rule: ViewRule): rule is ViewRuleAutoLayout {
+  return 'autoLayout' in rule
+}
+
+export type ViewRule = ViewRuleExpression | ViewRuleStyle | ViewRuleAutoLayout
+
+export interface BasicView<ViewType extends 'element' | 'dynamic' = 'element' | 'dynamic'> {
+  readonly __?: ViewType
+  readonly id: ViewID
+  readonly title: string | null
+  readonly description: string | null
+  readonly tags: NonEmptyArray<Tag> | null
+  readonly links: NonEmptyArray<string> | null
+
+  /**
+   * URI to the source file of this view.
+   * Undefined if the view is auto-generated.
+   */
+  readonly docUri?: string
+  /**
+   * For all views we find common ancestor path.
+   * This is used to generate relative paths, i.e.:
+   * - "" for views in the common ancestor directory (or root)
+   * - "subdir" for views in "<root>/subdir"
+   * - "subdir/subdir1" for views in "<root>/subdir/subdir1"
+   *
+   * Undefined if the view is auto-generated.
+   */
+  readonly relativePath?: string
+}
+
+export interface BasicElementView extends BasicView<'element'> {
+  readonly viewOf?: Fqn
+  readonly rules: ViewRule[]
+}
+export interface StrictElementView extends BasicElementView {
+  readonly viewOf: Fqn
+}
+
+export interface ExtendsElementView extends BasicElementView {
+  readonly extends: ViewID
+}
+export type ElementView = StrictElementView | ExtendsElementView | BasicElementView
+
+export interface DynamicViewStep {
+  readonly source: Fqn
+  readonly target: Fqn
+  readonly title: string | null
+  readonly isBackward?: boolean
+}
+
+export type DynamicViewIncludeRule = {
+  include: (ElementExpression | CustomElementExpr)[]
+}
+
+export function isDynamicViewIncludeRule(rule: DynamicViewRule): rule is DynamicViewIncludeRule {
+  return 'include' in rule && Array.isArray(rule.include)
+}
+
+export type DynamicViewRule = DynamicViewIncludeRule | ViewRuleStyle | ViewRuleAutoLayout
+export interface DynamicView extends BasicView<'dynamic'> {
+  readonly __: 'dynamic'
+
+  readonly steps: DynamicViewStep[]
+
+  readonly rules: DynamicViewRule[]
+}
+
+export type View = ElementView | DynamicView
+
+export function isDynamicView(view: View): view is DynamicView {
+  return view.__ === 'dynamic'
+}
+export function isElementView(view: View): view is ElementView {
+  return isNullish(view.__) || view.__ === 'element'
+}
+
+export function isExtendsElementView(view: View): view is ExtendsElementView {
+  return isElementView(view) && 'extends' in view
+}
+
+export function isStrictElementView(view: View): view is StrictElementView {
+  return isElementView(view) && 'viewOf' in view
+}
+
+export type NodeId = 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 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))
+}
+
+export interface ComputedNode {
+  id: NodeId
+  kind: ElementKind
+  parent: NodeId | null
+  title: string
+  description: string | null
+  technology: string | null
+  tags: NonEmptyArray<Tag> | null
+  links: NonEmptyArray<string> | null
+  children: NodeId[]
+  inEdges: EdgeId[]
+  outEdges: EdgeId[]
+  shape: ElementShape
+  /**
+   * @deprecated Use `style` instead
+   */
+  color: ThemeColor
+  /**
+   * @deprecated Use `style` instead
+   */
+  icon?: IconUrl
+  style: ElementStyle
+  navigateTo?: ViewID
+  level: number
+  // For compound nodes, the max depth of nested nodes
+  depth?: number
+}
+
+export interface ComputedEdge {
+  id: EdgeId
+  parent: NodeId | null
+  source: NodeId
+  target: NodeId
+  label: string | null
+  relations: RelationID[]
+  color?: ThemeColor
+  line?: RelationshipLineType
+  head?: RelationshipArrowType
+  tail?: RelationshipArrowType
+
+  /**
+   * For layouting purposes
+   * @default 'forward'
+   */
+  dir?: 'forward' | 'back'
+}
+
+export interface ComputedElementView extends Omit<ElementView, 'rules'> {
+  readonly extends?: ViewID
+  readonly autoLayout: ViewRuleAutoLayout['autoLayout']
+  readonly nodes: ComputedNode[]
+  readonly edges: ComputedEdge[]
+}
+export interface ComputedDynamicView extends Omit<DynamicView, 'rules' | 'steps'> {
+  readonly autoLayout: ViewRuleAutoLayout['autoLayout']
+  readonly nodes: ComputedNode[]
+  readonly edges: ComputedEdge[]
+}
+export function isComputedDynamicView(view: ComputedView): view is ComputedDynamicView {
+  return view.__ === 'dynamic'
+}
+
+export type ComputedView = ComputedElementView | ComputedDynamicView
+
+export function isComputedElementView(view: ComputedView): view is ComputedElementView {
+  return isNullish(view.__) || view.__ === 'element'
+}
+
+export type Point = readonly [x: number, y: number]
+
+// Bounding box
+export type BBox = {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+export interface DiagramLabel {
+  align: 'left' | 'right' | 'center'
+  fontStyle?: 'bold' | 'normal'
+  color?: ColorLiteral
+  fontSize: number
+  pt: Point
+  width: number
+  text: string
+}
+
+export interface DiagramNode extends ComputedNode {
+  width: number
+  height: number
+  position: Point // Absolute position, top left
+  // relative: Point // Top left, relative to parent
+  labels: DiagramLabel[]
+}
+
+export interface DiagramEdge extends ComputedEdge {
+  points: NonEmptyArray<Point>
+  // Polygons are used to draw arrows
+  headArrow?: NonEmptyArray<Point>
+  // Draw arrow from the last point of the edge to this point
+  headArrowPoint?: Point
+  tailArrow?: NonEmptyArray<Point>
+  // Draw arrow from the first point of the edge to this point
+  tailArrowPoint?: Point
+  labels?: NonEmptyArray<DiagramLabel>
+  labelBBox?: BBox
+}
+
+export interface DiagramView extends Omit<ComputedView, 'nodes' | 'edges'> {
+  readonly nodes: DiagramNode[]
+  readonly edges: DiagramEdge[]
+  readonly width: number
+  readonly height: number
+}

package/src/utils/fqn.spec.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest'
+import type { Element, Fqn } from '../types'
+import {
+  ancestorsFqn,
+  commonAncestor,
+  compareFqnHierarchically,
+  isAncestor,
+  isDescendantOf,
+  notDescendantOf,
+  parentFqn
+} from './fqn'
+
+const el = (id: string): Element => ({ id }) as unknown as Element
+
+describe('parentFqn', () => {
+  it('should return null if no parent', () => {
+    expect(parentFqn('a' as Fqn)).toBeNull()
+  })
+  it('should return parent', () => {
+    expect(parentFqn('a.b' as Fqn)).toBe('a')
+    expect(parentFqn('a.b.c' as Fqn)).toBe('a.b')
+  })
+})
+
+describe('ancestorsFqn', () => {
+  it('should return empty array if no parent', () => {
+    expect(ancestorsFqn('a' as Fqn)).toEqual([])
+  })
+  it('should return ancestors', () => {
+    expect(ancestorsFqn('a.b.c.d.e' as Fqn)).toEqual(['a.b.c.d', 'a.b.c', 'a.b', 'a'])
+  })
+})
+
+describe('commonAncestor', () => {
+  it('should return null if no common ancestor', () => {
+    expect(commonAncestor('a' as Fqn, 'b' as Fqn)).toBeNull()
+    expect(commonAncestor('a.b' as Fqn, 'c.d' as Fqn)).toBeNull()
+  })
+
+  it('should return common ancestor', () => {
+    expect(commonAncestor('a.b' as Fqn, 'a.c' as Fqn)).toBe('a')
+    expect(commonAncestor('a.b.c' as Fqn, 'a.b.e' as Fqn)).toBe('a.b')
+    expect(commonAncestor('a.b.c.d.e' as Fqn, 'a.b.c.d' as Fqn)).toBe('a.b.c')
+  })
+})
+
+describe('isAncestor', () => {
+  it('should return true if ancestor', () => {
+    expect(isAncestor('a' as Fqn, 'a.b' as Fqn)).toBe(true)
+    expect(isAncestor('a.b' as Fqn, 'a.b.c' as Fqn)).toBe(true)
+  })
+  it('should return false if not ancestor', () => {
+    expect(isAncestor('a' as Fqn, 'b' as Fqn)).toBe(false)
+    expect(isAncestor('a.b' as Fqn, 'a' as Fqn)).toBe(false)
+    expect(isAncestor('a.b' as Fqn, 'b.a' as Fqn)).toBe(false)
+  })
+})
+
+describe('isDescendantOf', () => {
+  const predicate = isDescendantOf(['a', 'b', 'a.b', 'a.b.c'].map(el))
+
+  it('should return true if isDescendantOf', () => {
+    expect(predicate(el('a'))).toBe(true)
+    expect(predicate(el('b.c'))).toBe(true)
+    expect(predicate(el('a.b.c.d.e'))).toBe(true)
+  })
+  it('should return false if not descendantOf', () => {
+    expect(predicate(el('c'))).toBe(false)
+    expect(predicate(el('ac'))).toBe(false)
+    expect(predicate(el('d.a.c'))).toBe(false)
+  })
+})
+
+describe('notDescendantOf', () => {
+  const predicate = notDescendantOf(['a', 'b', 'a.b', 'a.b.c'].map(el))
+
+  it('should return true if notDescendantOf', () => {
+    expect(predicate(el('c'))).toBe(true)
+    expect(predicate(el('ac'))).toBe(true)
+    expect(predicate(el('d.a.c'))).toBe(true)
+  })
+  it('should return false if descendantOf', () => {
+    expect(predicate(el('a'))).toBe(false)
+    expect(predicate(el('b.c'))).toBe(false)
+    expect(predicate(el('a.b.c.d.e'))).toBe(false)
+  })
+})
+
+describe('compareFqnHierarchically', () => {
+  it('should compare hierarchically', () => {
+    expect(['a', 'b', 'a.b', 'a.b.c', 'a.c.c'].sort(compareFqnHierarchically)).toEqual([
+      'a',
+      'b',
+      'a.b',
+      'a.b.c',
+      'a.c.c'
+    ])
+  })
+
+  it('should preserve initial order', () => {
+    expect(
+      ['aaa', 'aa', 'a', 'aaa.c', 'aa.b', 'a.c', 'a.b'].sort(compareFqnHierarchically)
+    ).toEqual(['aaa', 'aa', 'a', 'aaa.c', 'aa.b', 'a.c', 'a.b'])
+  })
+})

package/src/utils/fqn.ts

@@ -0,0 +1,112 @@
+import type { Element, Fqn } from '../types'
+import { isString } from './guards'
+
+export function nameFromFqn(fqn: Fqn) {
+  const lastDot = fqn.lastIndexOf('.')
+  if (lastDot > 0) {
+    return fqn.slice(lastDot + 1)
+  } else {
+    return fqn
+  }
+}
+
+export function isAncestor<E extends { id: Fqn }>(
+  ...args: [ancestor: string, another: string] | [ancestor: E, another: E]
+) {
+  const ancestor = isString(args[0]) ? args[0] : args[0].id
+  const another = isString(args[1]) ? args[1] : args[1].id
+  return another.startsWith(ancestor + '.')
+}
+
+export function isSameHierarchy<E extends { id: Fqn }>(one: E | Fqn, another: E | Fqn) {
+  const first = isString(one) ? one : one.id
+  const second = isString(another) ? another : another.id
+  return first === second || second.startsWith(first + '.') || first.startsWith(second + '.')
+}
+
+export function isDescendantOf<E extends { id: Fqn }>(ancestors: E[]): (e: E) => boolean {
+  const predicates = ancestors.flatMap(a => [(e: E) => e.id === a.id, (e: E) => isAncestor(a, e)])
+  return (e: E) => predicates.some(p => p(e))
+}
+
+export function notDescendantOf(ancestors: Element[]): (e: Element) => boolean {
+  const isDescendant = isDescendantOf(ancestors)
+  return (e: Element) => !isDescendant(e)
+}
+
+export function commonAncestor(first: Fqn, second: Fqn) {
+  const parentA = parentFqn(first)
+  const parentB = parentFqn(second)
+  if (parentA === parentB) {
+    return parentA
+  }
+  if (!parentA || !parentB) {
+    return null
+  }
+
+  const a = first.split('.')
+  const b = second.split('.')
+  let ancestor: Fqn | null = null
+
+  while (a.length > 1 && b.length > 1 && !!a[0] && a[0] === b[0]) {
+    ancestor = (ancestor ? `${ancestor}.${a[0]}` : a[0]) as Fqn
+    a.shift()
+    b.shift()
+  }
+  return ancestor
+}
+
+export function parentFqn(fqn: Fqn): Fqn | null {
+  const lastDot = fqn.lastIndexOf('.')
+  if (lastDot > 0) {
+    return fqn.substring(0, lastDot) as Fqn
+  }
+  return null
+}
+
+/**
+ * Get all ancestor elements (i.e. parent, parent’s parent, etc.)
+ * (from closest to root)
+ */
+export function ancestorsFqn(fqn: Fqn): Fqn[] {
+  const path = fqn.split('.')
+  path.pop()
+  if (path.length === 0) {
+    return []
+  }
+  return path.reduce((acc, _, idx) => {
+    const ancestor = path.slice(0, idx + 1).join('.')
+    acc.unshift(ancestor as Fqn)
+    return acc
+  }, [] as Fqn[])
+}
+
+/**
+ * Compares two fully qualified names (fqns) hierarchically based on their depth.
+ * From parent nodes to leaves
+ *
+ * @param {string} a - The first fqn to compare.
+ * @param {string} b - The second fqn to compare.
+ * @returns {number} - 0 if the fqns have the same depth.
+ *                    - 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 {
+  const depthA = a.split('.').length
+  const depthB = b.split('.').length
+  switch (true) {
+    case depthA > depthB: {
+      return 1
+    }
+    case depthA < depthB: {
+      return -1
+    }
+    default: {
+      return 0
+    }
+  }
+}
+
+export function compareByFqnHierarchically<T extends { id: string }>(a: T, b: T) {
+  return compareFqnHierarchically(a.id, b.id)
+}

package/src/utils/guards.ts

@@ -0,0 +1,10 @@
+import type { NonEmptyArray } from '../types'
+export { hasAtLeast } from 'remeda'
+
+export function isString(value: unknown): value is string {
+  return value != null && typeof value === 'string'
+}
+
+export function isNonEmptyArray<A>(arr: ArrayLike<A> | undefined): arr is NonEmptyArray<A> {
+  return !!arr && Array.isArray(arr) && arr.length > 0
+}

package/src/utils/index.ts

@@ -0,0 +1,4 @@
+export * from './fqn'
+export * from './guards'
+export * from './promises'
+export * from './relations'

package/src/utils/promises.ts

@@ -0,0 +1,9 @@
+const DELAY = 'LIKEC4_DELAY'
+
+export function delay(ms: number = 100) {
+  return new Promise(resolve => {
+    setTimeout(() => {
+      resolve(DELAY)
+    }, ms)
+  })
+}