@likec4/core 1.34.1 → 1.35.0

package/src/model/view/LikeC4ViewsFolder.ts

@@ -0,0 +1,151 @@
+import { isEmpty, last } from 'remeda'
+import type { aux, NonEmptyArray } from '../../types'
+import { invariant, memoizeProp } from '../../utils'
+import type { LikeC4Model } from '../LikeC4Model'
+import { LikeC4ViewModel } from './LikeC4ViewModel'
+
+export class LikeC4ViewsFolder<A extends aux.Any = aux.Any> {
+  public readonly $model: LikeC4Model<A>
+
+  /**
+   * Path to this view folder, processed by {@link normalizeViewPath}
+   *
+   * @example
+   * "Folder 1/Folder 2/Folder 3"
+   */
+  public readonly path: string
+
+  /**
+   * Title of this view folder.
+   *
+   * @example
+   * // title is the last segment of the path
+   * path = "Folder 1/Folder 2/Folder 3"
+   * title = "Folder 3"
+   */
+  public readonly title: string
+
+  /**
+   * Whether this is the root view folder.
+   *
+   * !NOTE
+   * Root folder is special folder with an empty path and used only for internal purposes. \
+   * It is not visible to the user and should not be used in the code.
+   */
+  public readonly isRoot: boolean
+
+  protected readonly parentPath: string | undefined
+
+  protected readonly defaultViewId: aux.StrictViewId<A> | undefined
+
+  constructor(
+    $model: LikeC4Model<A>,
+    path: NonEmptyArray<string>,
+    defaultViewId: aux.StrictViewId<A> | undefined,
+  ) {
+    this.$model = $model
+    this.path = path.join('/')
+    this.isRoot = this.path === ''
+    this.title = last(path)
+    if (this.isRoot) {
+      this.parentPath = undefined
+    } else {
+      this.parentPath = path.slice(0, -1).join('/')
+    }
+    this.defaultViewId = defaultViewId
+  }
+
+  /**
+   * Default view of this view folder.\
+   * It is for the case when there is a view at the same path as this folder.\
+   * (if there are multiple views at the same path, the first one is chosen)
+   *
+   * @example
+   * ```
+   * // Assume the following views exist:
+   * const views = [
+   *   "Folder 1/ Folder 2 / View",
+   *   "Folder 1/ Folder 2 / View / Subview",
+   * ]
+   * ```
+   * Group with path `Folder 1/ Folder 2 / View`\
+   * will have default view `Folder 1/ Folder 2 / View`
+   */
+  get defaultView(): LikeC4ViewModel<A> | null {
+    if (!this.defaultViewId) {
+      return null
+    }
+    return this.$model.view(this.defaultViewId)
+  }
+
+  /**
+   * Returns path to this view folder as an array of ancestors (excluding root) and this view folder as the last element
+   *
+   * @throws Error if this is the root folder.
+   */
+  get breadcrumbs(): [...LikeC4ViewsFolder<A>[], this] {
+    invariant(!this.isRoot, 'Root view folder has no breadcrumbs')
+    return memoizeProp(this, 'breadcrumbs', () => {
+      const parent = this.parent
+      if (parent) {
+        if (parent.isRoot) {
+          return [parent, this]
+        }
+        return [...parent.breadcrumbs, this]
+      }
+      return [this]
+    })
+  }
+
+  /**
+   * Returns parent folder
+   *
+   * @throws Error if this is the root folder.
+   */
+  get parent(): LikeC4ViewsFolder<A> | null {
+    invariant(!this.isRoot, 'Root view folder has no parent')
+    if (isEmpty(this.parentPath)) {
+      return null
+    }
+    return this.$model.viewFolder(this.parentPath)
+  }
+
+  /**
+   * Returns sorted set of children
+   * - First folders
+   * - Then views
+   */
+  get children(): ReadonlySet<LikeC4ViewsFolder<A> | LikeC4ViewModel<A>> {
+    return this.$model.viewFolderItems(this.path)
+  }
+
+  /**
+   * Returns sorted array of children folders
+   */
+  get folders(): ReadonlyArray<LikeC4ViewsFolder<A>> {
+    return memoizeProp(this, 'folders', () => {
+      const folders: LikeC4ViewsFolder<A>[] = []
+      for (const child of this.children) {
+        if (child instanceof LikeC4ViewsFolder) {
+          folders.push(child)
+        }
+      }
+      return folders
+    })
+  }
+
+  /**
+   * Returns all views in this view folder.
+   */
+  get views(): ReadonlyArray<LikeC4ViewModel<A>> {
+    return memoizeProp(this, 'views', () => {
+      const views: LikeC4ViewModel<A>[] = []
+      for (const child of this.children) {
+        if (child instanceof LikeC4ViewModel) {
+          views.push(child)
+        }
+      }
+      return views
+    })
+  }
+}

package/src/theme/__test__/theme-index.ts

@@ -0,0 +1,29 @@
+import type { HexColor } from "../../types";
+
+export const lightValue = {
+      elements: {
+        fill: "#2ec2fb" as HexColor,
+        stroke: "#1fabe1" as HexColor,
+        hiContrast: "#00002d" as HexColor,
+        loContrast: "#00153d" as HexColor,
+      },
+      relationships: {
+        lineColor: "#4ccdfb" as HexColor,
+        labelColor: "#6fd8fc" as HexColor,
+        labelBgColor: "#0084b2" as HexColor,
+      },
+    }
+
+export const darkValue = {
+      elements: {
+        fill: "#2c40dc" as HexColor,
+        stroke: "#1f32c4" as HexColor,
+        hiContrast: "#ffffff" as HexColor,
+        loContrast: "#fffeff" as HexColor,
+      },
+      relationships: {
+        lineColor: "#5362e1" as HexColor,
+        labelColor: "#7a87e9" as HexColor,
+        labelBgColor: "#0a259c" as HexColor,
+      },
+    }

package/src/theme/index.ts

@@ -1,7 +1,13 @@
 import { generateColors } from '@mantine/colors-generator'
+import chroma from 'chroma-js';
 import type { ColorLiteral, HexColor, LikeC4Theme, ThemeColorValues } from '../types'
 import { ElementColors } from './element'
 import { RelationshipColors } from './relationships'
+import { isDeepEqual } from 'remeda'
+
+const CONTRAST_MIN_WITH_FOREGROUND = 60
+const CONTRAST_START_TONE_DIFFERENCE = 2
+const CONTRAST_STEP_TONE_DIFFERENCE = 1
 
 export const defaultTheme: LikeC4Theme = {
   elements: ElementColors,
@@ -57,12 +63,15 @@ export function computeColorValues(color: ColorLiteral): ThemeColorValues {
   if (color.match(/^#([0-9a-f]{3}){1,2}$/i)) {
     const colors = generateColors(color)
 
+    const fillColor = colors[6]
+    const contrastedColors = getContrastedColorsAPCA(fillColor)
+    
     return {
       elements: {
-        fill: colors[6] as HexColor,
+        fill: fillColor as HexColor,
         stroke: colors[7] as HexColor,
-        hiContrast: colors[0] as HexColor,
-        loContrast: colors[1] as HexColor,
+        hiContrast: contrastedColors[0] as HexColor,
+        loContrast: contrastedColors[1] as HexColor,
       },
       relationships: {
         lineColor: colors[4] as HexColor,
@@ -78,4 +87,41 @@ export function computeColorValues(color: ColorLiteral): ThemeColorValues {
   }
 }
 
+function getContrastedColorsAPCA(refColor: string): [string, string] {
+  const refColorChroma = chroma(refColor)
+
+  // Start with 2 steps tone difference in the CIELAB color space from reference
+  let lightColorRgb = refColorChroma.brighten(CONTRAST_START_TONE_DIFFERENCE);
+  let darkColorRgb = refColorChroma.darken(CONTRAST_START_TONE_DIFFERENCE);
+
+  let previousLight
+  let previousDark
+  let contrastWithLight
+  let contrastWithDark
+  do {
+    // Store previous colors for loop condition
+    previousLight = lightColorRgb
+    previousDark = darkColorRgb
+
+    // Change tone by 1 step each loop
+    lightColorRgb = lightColorRgb.brighten(CONTRAST_STEP_TONE_DIFFERENCE)
+    darkColorRgb = darkColorRgb.darken(CONTRAST_STEP_TONE_DIFFERENCE)
+
+    // Calculate contrast of each color with the reference color
+    contrastWithLight = chroma.contrastAPCA(refColorChroma, lightColorRgb);
+    contrastWithDark = chroma.contrastAPCA(refColorChroma, darkColorRgb);
+  }
+  // Stop if one of the contrast is high enough or if we reach max value for each (aka when they are equal between two rounds)
+  while (Math.abs(contrastWithLight) < CONTRAST_MIN_WITH_FOREGROUND
+    && Math.abs(contrastWithDark) < CONTRAST_MIN_WITH_FOREGROUND
+    && (!isDeepEqual(lightColorRgb, previousLight) || !isDeepEqual(darkColorRgb, previousDark)))
+
+  // Choose the max contrast between the two
+  if (Math.abs(contrastWithLight) > Math.abs(contrastWithDark)) {
+    return [lightColorRgb.brighten(0.4).hex(), lightColorRgb.hex()]
+  } else {
+    return [darkColorRgb.darken(0.4).hex(), darkColorRgb.hex()]
+  }
+}
+
 export { ElementColors, RelationshipColors }

package/src/types/model-spec.ts

@@ -1,6 +1,7 @@
 import type { IsNever } from 'type-fest'
 import type * as aux from './_aux'
 import type { Any } from './_aux'
+import type { Link, NonEmptyArray } from './_common'
 import type * as scalar from './scalar'
 import type {
   Icon,
@@ -24,8 +25,11 @@ import type {
  */
 export interface ElementSpecification {
   tags?: scalar.Tag[]
+  title?: string
+  description?: scalar.MarkdownOrString
   technology?: string
   notation?: string
+  links?: NonEmptyArray<Link>
   style: {
     shape?: ElementShape
     icon?: Icon

package/src/utils/compare-natural.ts

@@ -13,22 +13,20 @@ export function compareNatural(a: string | undefined, b: string | undefined): -1
 }
 
 /**
- * Compares two strings hierarchically based on their depth.
+ * Compares two strings lexicographically first, then hierarchically based on their depth.\
  * From parent nodes to leaves
  *
  * @example
  * const lines = [
+ *   'b.c',
+ *   'b',
  *   'a.b.c',
- *   'a',
- *   'a.b',
- *   'a.c.c',
  * ]
  * lines.sort(compareNaturalHierarchically('.'))
  * // [
- * //   'a',
- * //   'a.b',
  * //   'a.b.c',
- * //   'a.c.c',
+ * //   'b',
+ * //   'b.c',
  * // ]
  */
 export function compareNaturalHierarchically(
@@ -40,10 +38,12 @@ export function compareNaturalHierarchically(
     if (!b) return 1
     const aParts = a.split(separator)
     const bParts = b.split(separator)
-    if (aParts.length !== bParts.length) {
-      return aParts.length - bParts.length
-    }
-    for (let i = 0; i < aParts.length; i++) {
+
+    // Find the minimum length to avoid out-of-bounds access
+    const minLength = Math.min(aParts.length, bParts.length)
+
+    // Compare segments until we find a difference
+    for (let i = 0; i < minLength; i++) {
       const aPart = aParts[i]!
       const bPart = bParts[i]!
       const comparison = compare(aPart, bPart)
@@ -51,6 +51,8 @@ export function compareNaturalHierarchically(
         return comparison
       }
     }
-    return 0
+
+    // If all common segments are equal, shorter paths come first
+    return aParts.length - bParts.length
   }
 }

package/src/utils/index.ts

@@ -41,6 +41,7 @@ export {
 export {
   ifilter,
   ifind,
+  ifirst,
   iflat,
   ihead,
   imap,

package/src/utils/iterable/first.ts

@@ -0,0 +1,48 @@
+import type { IteratorLike } from '../../types'
+import { invariant } from '../../utils/invariant'
+
+/**
+ * Takes the first N elements from an iterable.
+ * Composable first version of `ifirst`.
+ * @signature
+ *   ifirst(count)(data)
+ */
+export function ifirst<T>(count: number): (iterable: Iterable<T>) => IteratorLike<T>
+
+/**
+ * Takes the first N elements from an iterable.
+ * Data first version of `ifirst`.
+ * @signature
+ *   ifirst(data, count)
+ * @example
+ *   ifirst([1, 2, 3, 4, 5], 3) // => Iterable<[1, 2, 3]>
+ */
+export function ifirst<T>(iterable: Iterable<T>, count: number): IteratorLike<T>
+
+export function ifirst(
+  arg1: unknown,
+  arg2?: unknown,
+): IteratorLike<unknown> | ((it: Iterable<unknown>) => IteratorLike<unknown>) {
+  const count = (arg2 ?? arg1) as number
+  invariant(typeof count === 'number' && count >= 0, 'Count must be a non-negative number')
+
+  function* _first(iter: Iterable<unknown>): IteratorLike<unknown> {
+    let taken = 0
+    for (const value of iter) {
+      if (taken >= count) {
+        break
+      }
+      yield value
+      taken++
+    }
+    return
+  }
+
+  if (arg2 === undefined) {
+    // Composable version: ifirst(count)(iterable)
+    return (iterable: Iterable<unknown>) => _first(iterable)
+  }
+
+  // Data-first version: ifirst(iterable, count)
+  return _first(arg1 as Iterable<unknown>)
+}

package/src/utils/iterable/index.ts

@@ -5,6 +5,7 @@ export { isIterable } from './_types'
  */
 export { ifilter } from './filter'
 export { ifind } from './find'
+export { ifirst } from './first'
 export { iflat } from './flat'
 export { ihead } from './head'
 export { imap } from './map'

package/dist/shared/{core.Br7Fab9l.mjs → core.BajmN8zR.mjs}

@@ -4,18 +4,18 @@ import { i as invariant, n as nonexhaustive } from './core.D4npX2q8.mjs';
 import { o } from './core.BgvIuGGU.mjs';
 import { u } from './core.DbRvwARP.mjs';
 
-function isOnStage(value, stage) {
-  return value[_stage] === stage;
-}
-const _stage = "_stage";
-const _type = "_type";
-
 function n(e){return e==null}
 
 function t(...a){return u(e,a)}var e=(a,o)=>o.every(l=>l(a));
 
 function y(...a){return u(r,a)}var r=(a,o)=>o.some(e=>e(a));
 
+function isOnStage(value, stage) {
+  return value[_stage] === stage;
+}
+const _stage = "_stage";
+const _type = "_type";
+
 function flattenMarkdownOrString(value) {
   if (value === null || value === void 0) {
     return null;