@likec4/core 1.34.1 → 1.35.0

package/dist/utils/index.d.mts

@@ -2,7 +2,7 @@ export { D as DefaultMap } from '../shared/core.CywrQs86.mjs';
 export { I as IterableContainer, R as ReorderedArray, a as ancestorsFqn, c as commonAncestor, b as compareByFqnHierarchically, d as compareFqnHierarchically, h as hierarchyDistance, e as hierarchyLevel, i as isAncestor, f as isDescendantOf, g as isSameHierarchy, n as nameFromFqn, p as parentFqn, s as sortByFqnHierarchically, j as sortNaturalByFqn, k as sortParentsFirst } from '../shared/core.CF82MWyh.mjs';
 import { N as NonEmptyArray } from '../shared/core.DuSLYTG6.mjs';
 import { Tagged, Simplify, Or, IfNever, IsLiteral, And, GreaterThan, IsNever, IsEqual, ReadonlyTuple, IsNumericLiteral } from 'type-fest';
-export { ifilter, ifind, iflat, ihead, imap, ireduce, isIterable, isome, iunique, toArray, toSet } from './iterable/index.mjs';
+export { ifilter, ifind, ifirst, iflat, ihead, imap, ireduce, isIterable, isome, iunique, toArray, toSet } from './iterable/index.mjs';
 import '../shared/core.668kXpZq.mjs';
 
 /**
@@ -231,22 +231,20 @@ declare function commonHead<T>(sources: ReadonlyArray<T>, targets: ReadonlyArray
 
 declare function compareNatural(a: string | undefined, b: string | undefined): -1 | 0 | 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',
  * // ]
  */
 declare function compareNaturalHierarchically(separator?: string): (a: string | undefined, b: string | undefined) => number;

package/dist/utils/index.mjs

@@ -1,16 +1,16 @@
 export { i as invariant, a as nonNullable, n as nonexhaustive } from '../shared/core.D4npX2q8.mjs';
-export { S as Stack, c as commonHead, o as objectHash } from '../shared/core.CtKXPqN_.mjs';
-export { b as ancestorsFqn, d as commonAncestor, e as compareByFqnHierarchically, f as compareFqnHierarchically, c as compareNatural, a as compareNaturalHierarchically, h as hierarchyDistance, g as hierarchyLevel, i as isAncestor, j as isDescendantOf, o as isNonEmptyArray, k as isSameHierarchy, q as isString, n as nameFromFqn, p as parentFqn, s as sortByFqnHierarchically, l as sortNaturalByFqn, m as sortParentsFirst } from '../shared/core.C_C-3c1S.mjs';
+export { S as Stack, c as commonHead, o as objectHash } from '../shared/core.HUONfQfd.mjs';
+export { b as ancestorsFqn, d as commonAncestor, e as compareByFqnHierarchically, f as compareFqnHierarchically, c as compareNatural, a as compareNaturalHierarchically, h as hierarchyDistance, g as hierarchyLevel, i as isAncestor, j as isDescendantOf, o as isNonEmptyArray, k as isSameHierarchy, q as isString, n as nameFromFqn, p as parentFqn, s as sortByFqnHierarchically, l as sortNaturalByFqn, m as sortParentsFirst } from '../shared/core.DQj9iv_y.mjs';
 export { g as getOrCreate } from '../shared/core.DcS-0zys.mjs';
 export { a as markdownToHtml, b as markdownToText, m as memoizeProp } from '../shared/core.B0oEIXqd.mjs';
-export { b as BiMap, d as DefaultWeakMap, l as LinkedList, m as MultiMap, q as Queue, c as compareRelations, a as delay, p as promiseNextTick } from '../shared/core.XptQjhMA.mjs';
+export { b as BiMap, d as DefaultWeakMap, l as LinkedList, m as MultiMap, q as Queue, c as compareRelations, a as delay, p as promiseNextTick } from '../shared/core.b2BzqGz0.mjs';
 export { d as difference, e as equalsSet, i as hasAtLeast, a as intersection, b as stringHash, s as symmetricDifference, u as union } from '../shared/core.CpwrZi3D.mjs';
-export { D as DefaultMap } from '../shared/core.BMCb0wJI.mjs';
+export { D as DefaultMap } from '../shared/core.yaRvRnMW.mjs';
 export { i as ifilter } from '../shared/core.BH9nN-_I.mjs';
 export { i as ifind, a as ihead } from '../shared/core.DsMrjY2q.mjs';
+export { ifirst, ireduce } from './iterable/index.mjs';
 export { i as iflat, a as isIterable, b as iunique } from '../shared/core.8KM0D6va.mjs';
 export { i as imap, t as toArray, a as toSet } from '../shared/core.Btl47GOn.mjs';
-export { ireduce } from './iterable/index.mjs';
 export { i as isome } from '../shared/core.BoyJPEen.mjs';
 import '../shared/core.DbRvwARP.mjs';
 import '../shared/core.ByrmCl9I.mjs';

package/dist/utils/iterable/index.d.mts

@@ -39,6 +39,23 @@ declare function ifind<T>(predicate: (item: T) => boolean): (iterable: Iterable<
 declare function ifind<T, S extends T>(iterable: Iterable<T>, predicate: (item: T) => item is S): S | undefined;
 declare function ifind<T>(iterable: Iterable<T>, predicate: (item: T) => boolean): T | undefined;
 
+/**
+ * Takes the first N elements from an iterable.
+ * Composable first version of `ifirst`.
+ * @signature
+ *   ifirst(count)(data)
+ */
+declare 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]>
+ */
+declare function ifirst<T>(iterable: Iterable<T>, count: number): IteratorLike<T>;
+
 declare function iflat(): <T>(iterable: Iterable<IteratorLike<T>>) => IteratorLike<T>;
 declare function iflat<T>(iterable: Iterable<IteratorLike<T>>): IteratorLike<T>;
 
@@ -97,4 +114,4 @@ declare function toSet<T>(iterable: Iterable<T>): Set<T>;
 declare function iunique(): <T>(iterable: Iterable<T>) => IteratorLike<T>;
 declare function iunique<T>(iterable: Iterable<T>): IteratorLike<T>;
 
-export { ifilter, ifind, iflat, ihead, imap, ireduce, isIterable, isome, iunique, toArray, toSet };
+export { ifilter, ifind, ifirst, iflat, ihead, imap, ireduce, isIterable, isome, iunique, toArray, toSet };

package/dist/utils/iterable/index.mjs

@@ -3,10 +3,30 @@ export { i as iflat, a as isIterable, b as iunique } from '../../shared/core.8KM
 import { t } from '../../shared/core.BH9nN-_I.mjs';
 export { i as ifilter } from '../../shared/core.BH9nN-_I.mjs';
 export { i as ifind, a as ihead } from '../../shared/core.DsMrjY2q.mjs';
-export { i as imap, t as toArray, a as toSet } from '../../shared/core.Btl47GOn.mjs';
 import { i as invariant } from '../../shared/core.D4npX2q8.mjs';
+export { i as imap, t as toArray, a as toSet } from '../../shared/core.Btl47GOn.mjs';
 export { i as isome } from '../../shared/core.BoyJPEen.mjs';
 
+function ifirst(arg1, arg2) {
+  const count = arg2 ?? arg1;
+  invariant(typeof count === "number" && count >= 0, "Count must be a non-negative number");
+  function* _first(iter) {
+    let taken = 0;
+    for (const value of iter) {
+      if (taken >= count) {
+        break;
+      }
+      yield value;
+      taken++;
+    }
+    return;
+  }
+  if (arg2 === void 0) {
+    return (iterable) => _first(iterable);
+  }
+  return _first(arg1);
+}
+
 function ireduce(arg1, arg2, arg3) {
   const reducer = n(arg3) ? arg2 : arg1;
   const initialValue = arg3 ?? arg2;
@@ -21,4 +41,4 @@ function ireduce(arg1, arg2, arg3) {
   return n(arg3) ? _reduce(arg1) : _reduce;
 }
 
-export { ireduce };
+export { ifirst, ireduce };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@likec4/core",
-  "version": "1.34.1",
+  "version": "1.35.0",
   "license": "MIT",
   "homepage": "https://likec4.dev",
   "author": "Denis Davydkov <denis@davydkov.com>",
@@ -106,15 +106,16 @@
     "unified": "11.0.5"
   },
   "devDependencies": {
+    "@types/chroma-js": "^3.1.1",
     "@dagrejs/dagre": "1.1.5",
-    "@mantine/colors-generator": "8.1.2",
+    "@mantine/colors-generator": "8.2.1",
     "@types/extend": "3.0.4",
     "@types/hast": "3.0.4",
     "@types/mdast": "4.0.4",
     "@types/natural-compare-lite": "^1.4.2",
     "@types/object-hash": "^3.0.6",
     "@types/unist": "3.0.3",
-    "@types/node": "~20.19.1",
+    "@types/node": "~20.19.2",
     "chroma-js": "^3.1.2",
     "defu": "^6.1.4",
     "fdir": "6.4.6",
@@ -126,11 +127,11 @@
     "object-hash": "^3.0.0",
     "obliterator": "^2.0.5",
     "remeda": "^2.23.1",
-    "turbo": "2.5.4",
+    "turbo": "2.5.5",
     "typescript": "5.8.3",
     "unbuild": "3.5.0",
     "vitest": "3.2.4",
-    "@likec4/tsconfig": "1.34.1"
+    "@likec4/tsconfig": "1.35.0"
   },
   "scripts": {
     "typecheck": "tsc -b --verbose",

package/src/compute-view/element-view/predicates/relation-direct.ts

@@ -1,5 +1,5 @@
-import { concat, constant, flatMap, hasAtLeast, map, partition, pipe, piped, prop, when } from 'remeda'
-import type { RelationshipModel } from '../../../model'
+import { concat, constant, filter, flatMap, hasAtLeast, map, partition, pipe, piped, prop, when } from 'remeda'
+import type { ElementModel, RelationshipModel } from '../../../model'
 import { ConnectionModel } from '../../../model'
 import { type AnyAux, type ModelRelationExpr, FqnRef, ModelFqnExpr } from '../../../types'
 import { invariant, isSameHierarchy } from '../../../utils'
@@ -16,6 +16,8 @@ import {
 } from './_utils'
 
 const isWildcard = ModelFqnExpr.isWildcard
+const isAncestorOrDescendantOf = (a: ElementModel<AnyAux>, b: ElementModel<AnyAux>) =>
+  a.isAncestorOf(b) || a.isDescendantOf(b)
 
 export const DirectRelationExprPredicate: PredicateExecutor<ModelRelationExpr.Direct<AnyAux>> = {
   include: ({ expr: { source, target, isBidirectional = false }, memory, model, stage, where, filterWhere }) => {
@@ -75,6 +77,7 @@ export const DirectRelationExprPredicate: PredicateExecutor<ModelRelationExpr.Di
                 concat(
                   pipe(
                     outgoing,
+                    filter(r => !isAncestorOrDescendantOf(source, r.target)),
                     map(outgoing =>
                       new ConnectionModel(
                         source,
@@ -85,6 +88,7 @@ export const DirectRelationExprPredicate: PredicateExecutor<ModelRelationExpr.Di
                   ),
                   pipe(
                     incoming,
+                    filter(r => !isAncestorOrDescendantOf(source, r.source)),
                     map(incoming =>
                       new ConnectionModel(
                         incoming.source,
@@ -133,6 +137,7 @@ export const DirectRelationExprPredicate: PredicateExecutor<ModelRelationExpr.Di
                 concat(
                   pipe(
                     outgoing,
+                    filter(r => !isAncestorOrDescendantOf(target, r.target)),
                     map(outgoing =>
                       new ConnectionModel(
                         target,
@@ -143,6 +148,7 @@ export const DirectRelationExprPredicate: PredicateExecutor<ModelRelationExpr.Di
                   ),
                   pipe(
                     incoming,
+                    filter(r => !isAncestorOrDescendantOf(target, r.source)),
                     map(incoming =>
                       new ConnectionModel(
                         incoming.source,

package/src/model/DeploymentModel.ts

@@ -30,8 +30,8 @@ import {
   type IncomingFilter,
   type OutgoingFilter,
   type RelationOrId,
-  getId,
 } from './types'
+import { getId } from './utils'
 import type { LikeC4ViewModel } from './view/LikeC4ViewModel'
 
 export class LikeC4DeploymentModel<A extends Any = Any> {

package/src/model/LikeC4Model.ts

@@ -1,4 +1,4 @@
-import { entries, map, pipe, prop, sort, sortBy, values } from 'remeda'
+import { entries, hasAtLeast, map, pipe, prop, sort, sortBy, split, values } from 'remeda'
 import type {
   Any,
   Aux,
@@ -17,7 +17,7 @@ import type {
 } from '../types'
 import { type ProjectId, _stage, GlobalFqn, isGlobalFqn, isOnStage, whereOperatorAsPredicate } from '../types'
 import type * as aux from '../types/_aux'
-import { compareNatural, ifilter, invariant, memoizeProp, nonNullable } from '../utils'
+import { compareNatural, compareNaturalHierarchically, ifilter, invariant, memoizeProp, nonNullable } from '../utils'
 import { ancestorsFqn, commonAncestor, parentFqn, sortParentsFirst } from '../utils/fqn'
 import { DefaultMap } from '../utils/mnemonist'
 import type {
@@ -36,9 +36,10 @@ import {
   type IncomingFilter,
   type OutgoingFilter,
   type RelationOrId,
-  getId,
 } from './types'
+import { getId, getViewFolderPath, normalizeViewPath, VIEW_FOLDERS_SEPARATOR } from './utils'
 import { LikeC4ViewModel } from './view/LikeC4ViewModel'
+import { LikeC4ViewsFolder } from './view/LikeC4ViewsFolder'
 import type { NodeModel } from './view/NodeModel'
 
 export class LikeC4Model<A extends Any = aux.Unknown> {
@@ -68,6 +69,16 @@ export class LikeC4Model<A extends Any = aux.Unknown> {
 
   protected readonly _views = new Map<aux.ViewId<A>, LikeC4ViewModel<A>>()
 
+  protected readonly _rootViewFolder: LikeC4ViewsFolder<A>
+  protected readonly _viewFolders = new Map<string, LikeC4ViewsFolder<A>>()
+
+  protected readonly _viewFolderItems = new DefaultMap<
+    string,
+    Set<LikeC4ViewsFolder<A> | LikeC4ViewModel<A>>
+  >(
+    () => new Set(),
+  )
+
   protected readonly _allTags = new DefaultMap<
     aux.Tag<A>,
     Set<ElementModel<A> | RelationshipModel<A> | LikeC4ViewModel<A>>
@@ -165,17 +176,65 @@ export class LikeC4Model<A extends Any = aux.Unknown> {
     this.deployment = new LikeC4DeploymentModel(this)
 
     if (isOnStage($data, 'computed') || isOnStage($data, 'layouted')) {
+      const compare = compareNaturalHierarchically(VIEW_FOLDERS_SEPARATOR)
       const views = pipe(
         values($data.views as Record<string, $View<A>>),
-        sort((a, b) => compareNatural(a.title ?? 'untitled', b.title ?? 'untitled')),
+        map(view => ({
+          view,
+          path: normalizeViewPath(view.title ?? view.id),
+          folderPath: view.title && getViewFolderPath(view.title) || '',
+        })),
+        // Sort hierarchically by groups, but keep same order within groups
+        sort((a, b) => compare(a.folderPath, b.folderPath)),
       )
-      for (const view of views) {
-        const vm = new LikeC4ViewModel(this, view)
+
+      const getOrCreateFolder = (path: string) => {
+        let folder = this._viewFolders.get(path)
+        if (!folder) {
+          const segments = split(path, VIEW_FOLDERS_SEPARATOR)
+          invariant(hasAtLeast(segments, 1), `View group path "${path}" must have at least one element`)
+          let defaultView
+          // Root group has "index" as default view
+          if (path === '') {
+            defaultView = views.find(view => view.view.id === 'index')
+          } else {
+            defaultView = views.find(view => view.path === path)
+          }
+          folder = new LikeC4ViewsFolder(this, segments, defaultView?.view.id)
+          this._viewFolders.set(path, folder)
+        }
+        return folder
+      }
+
+      this._rootViewFolder = getOrCreateFolder('')
+
+      // Process view groups
+      // Sort in natural order to preserve hierarchy
+      for (const { folderPath } of views) {
+        if (this._viewFolders.has(folderPath)) {
+          continue
+        }
+        // Create groups for each segment of the path
+        split(folderPath, VIEW_FOLDERS_SEPARATOR).reduce((parent, segment) => {
+          const path = [...parent, segment]
+          const folder = getOrCreateFolder(path.join(VIEW_FOLDERS_SEPARATOR))
+          this._viewFolderItems.get(parent.join(VIEW_FOLDERS_SEPARATOR)).add(folder)
+          return path
+        }, [] as string[])
+      }
+
+      for (const { view, folderPath } of views) {
+        const vm = new LikeC4ViewModel(this, view, getOrCreateFolder(folderPath))
+        this._viewFolderItems.get(folderPath).add(vm)
         this._views.set(view.id, vm)
         for (const tag of vm.tags) {
           this._allTags.get(tag).add(vm)
         }
       }
+    } else {
+      // Model is not computed or layouted, but we still need to create root folder
+      this._rootViewFolder = new LikeC4ViewsFolder(this, [''], undefined)
+      this._viewFolders.set(this._rootViewFolder.path, this._rootViewFolder)
     }
   }
 
@@ -254,6 +313,21 @@ export class LikeC4Model<A extends Any = aux.Unknown> {
     }))
   }
 
+  /**
+   * Returns the element with the given FQN.
+   *
+   * @throws Error if element is not found\
+   * Use {@link findElement} if you don't want to throw an error
+   *
+   * @note Method is type-safe for typed model
+
+   * @example
+   * model.element('cloud.frontend')
+   * // or object with id property of scalar.Fqn
+   * model.element({
+   *   id: 'dashboard',
+   * })
+   */
   public element(el: ElementOrFqn<A>): ElementModel<A> {
     if (el instanceof ElementModel) {
       return el
@@ -261,6 +335,16 @@ export class LikeC4Model<A extends Any = aux.Unknown> {
     const id = getId(el)
     return nonNullable(this._elements.get(id), `Element ${id} not found`)
   }
+
+  /**
+   * Returns the element with the given FQN.
+   *
+   * @returns Element if found, null otherwise
+   * @note Method is not type-safe as {@link element}
+   *
+   * @example
+   * model.findElement('cloud.frontend')
+   */
   public findElement(el: aux.LooseElementId<A>): ElementModel<A> | null {
     return this._elements.get(getId(el)) ?? null
   }
@@ -342,15 +426,69 @@ export class LikeC4Model<A extends Any = aux.Unknown> {
 
   /**
    * Returns a specific view by its ID.
+   * @note Method is type-safe for typed model
+   * @throws Error if view is not found\
+   * Use {@link findView} if you don't want to throw an error
+   *
+   * @example
+   * model.view('index')
+   * // or object with id property of scalar.ViewId
+   * model.view({
+   *   id: 'index',
+   * })
    */
   public view(viewId: aux.ViewId<A> | { id: scalar.ViewId<aux.ViewId<A>> }): LikeC4ViewModel<A, $View<A>> {
     const id = getId(viewId)
     return nonNullable(this._views.get(id), `View ${id} not found`)
   }
+
+  /**
+   * Returns a specific view by its ID.
+   * @note Method is not type-safe as {@link view}
+   *
+   * @example
+   * model.findView('index')
+   */
   public findView(viewId: aux.LooseViewId<A>): LikeC4ViewModel<A, $View<A>> | null {
     return this._views.get(viewId as aux.ViewId<A>) ?? null
   }
 
+  /**
+   * Returns a view folder by its path.
+   * Path is extracted from the view title, e.g. "Group 1/Group 2/View" -> "Group 1/Group 2"
+   * @throws Error if view folder is not found.
+   */
+  public viewFolder(path: string): LikeC4ViewsFolder<A> {
+    return nonNullable(this._viewFolders.get(path), `View folder ${path} not found`)
+  }
+
+  /**
+   * Root folder is a special one with an empty path and used only for internal purposes.
+   * It is not visible to the user and should be used only to get top-level folders and views.
+   */
+  get rootViewFolder(): LikeC4ViewsFolder<A> {
+    return this._rootViewFolder
+  }
+
+  /**
+   * Whether the model has any view folders.
+   */
+  get hasViewFolders(): boolean {
+    // Root view folder is always present
+    return this._viewFolders.size > 1
+  }
+
+  /**
+   * Returns all children of a view folder.
+   * Path is extracted from the view title, e.g. "Group 1/Group 2/View" -> "Group 1/Group 2"
+   *
+   * @throws Error if view folder is not found.
+   */
+  public viewFolderItems(path: string): ReadonlySet<LikeC4ViewsFolder<A> | LikeC4ViewModel<A>> {
+    invariant(this._viewFolders.has(path), `View folder ${path} not found`)
+    return this._viewFolderItems.get(path)
+  }
+
   /**
    * Returns the parent element of given element.
    * @see ancestors
@@ -452,7 +590,8 @@ export class LikeC4Model<A extends Any = aux.Unknown> {
   }
 
   /**
-   * Returns all tags used in the model, sorted alphabetically.
+   * Returns array of all tags used in the model, sorted naturally.\
+   * Use {@link specification.tags} to get all defined tags
    */
   get tags(): aux.Tags<A> {
     return memoizeProp(this, 'tags', () => sort([...this._allTags.keys()], compareNatural))

package/src/model/index.ts

@@ -36,6 +36,7 @@ export { LikeC4DeploymentModel } from './DeploymentModel'
 
 export { EdgeModel } from './view/EdgeModel'
 export { LikeC4ViewModel } from './view/LikeC4ViewModel'
+export { LikeC4ViewsFolder } from './view/LikeC4ViewsFolder'
 export { NodeModel } from './view/NodeModel'
 
 export type {
@@ -62,3 +63,10 @@ export type {
 } from '../types'
 
 export { RichText, type RichTextEmpty, type RichTextOrEmpty } from '../types'
+
+export {
+  extractViewTitleFromPath,
+  getViewFolderPath,
+  normalizeViewPath,
+  VIEW_FOLDERS_SEPARATOR,
+} from './utils'

package/src/model/types.ts

@@ -16,7 +16,7 @@ import type { LikeC4ViewModel } from './view/LikeC4ViewModel'
 export type IncomingFilter = 'all' | 'direct' | 'to-descendants'
 export type OutgoingFilter = 'all' | 'direct' | 'from-descendants'
 
-type AnyScalar<V extends string> =
+export type AnyScalar<V extends string> =
   | Tagged<V, 'Fqn'>
   | Tagged<V, 'DeploymentFqn'>
   | Tagged<V, 'ViewId'>
@@ -24,13 +24,6 @@ type AnyScalar<V extends string> =
   | Tagged<V, 'EdgeId'>
   | Tagged<V, 'RelationId'>
 
-/**
- * Utility function to extract `id` from the given element.
- */
-export function getId<Id extends string, Scalar extends AnyScalar<Id>>(element: Id | { id: Scalar }): Scalar {
-  return typeof element === 'string' ? element as unknown as Scalar : element.id
-}
-
 export type ElementOrFqn<A extends AnyAux> = aux.ElementId<A> | { id: aux.Fqn<A> }
 
 export type DeploymentOrFqn<A extends AnyAux> = aux.DeploymentId<A> | { id: aux.DeploymentFqn<A> }

package/src/model/utils.ts

@@ -0,0 +1,66 @@
+import { hasAtLeast } from 'remeda'
+import type { NonEmptyArray } from '../types'
+import { invariant } from '../utils'
+import type { AnyScalar } from './types'
+
+/**
+ * Utility function to extract `id` from the given element.
+ */
+export const getId = <Id extends string, Scalar extends AnyScalar<Id>>(element: Id | { id: Scalar }): Scalar => {
+  return typeof element === 'string' ? element as unknown as Scalar : element.id
+}
+
+export const VIEW_FOLDERS_SEPARATOR = '/'
+
+const splitViewTitle = (title: string): NonEmptyArray<string> => {
+  invariant(!title.includes('\n'), 'View title cannot contain newlines')
+  if (title.includes(VIEW_FOLDERS_SEPARATOR)) {
+    const segments = title
+      .split(VIEW_FOLDERS_SEPARATOR)
+      .map(s => s.trim())
+      .filter(s => s.length > 0)
+    if (hasAtLeast(segments, 1)) {
+      return segments
+    }
+    return ['']
+  }
+  return [title.trim()]
+}
+
+/**
+ * Normalizes view path by removing spaces from segments, removing empty segments,
+ * and removing leading/trailing slashes
+ * @example
+ * normalizeViewPath('One / Tw o / Thre e') === 'One/Tw o/Thre e'
+ */
+export const normalizeViewPath = (title: string): string => {
+  return splitViewTitle(title).join(VIEW_FOLDERS_SEPARATOR)
+}
+
+/**
+ * Returns view group path if it is used as a path
+ * Returns empty string if it is not a path
+ * @example
+ * getViewFolderPath('One / Tw o / Thre e') === 'One/Tw o'
+ * getViewFolderPath('One') === ''
+ */
+export const getViewFolderPath = (title: string): string | null => {
+  const segments = splitViewTitle(title)
+  if (!hasAtLeast(segments, 2)) {
+    return null
+  }
+  return segments.slice(0, -1).join(VIEW_FOLDERS_SEPARATOR)
+}
+
+/**
+ * Returns view title if it is used as a path
+ * @example
+ * getViewTitleFromPath('One / Tw o / Thre e') === 'Thre e'
+ * getViewTitleFromPath('One') === 'One'
+ */
+export const extractViewTitleFromPath = (title: string): string => {
+  if (!title.includes(VIEW_FOLDERS_SEPARATOR)) {
+    return title.trim()
+  }
+  return splitViewTitle(title).pop() ?? title
+}

package/src/model/view/LikeC4ViewModel.ts

@@ -7,10 +7,9 @@ import type {
   scalar,
   ViewWithType,
 } from '../../types'
-import { _stage, _type } from '../../types'
-import { type RichTextOrEmpty, RichText } from '../../types'
+import { type RichTextOrEmpty, _stage, _type, RichText } from '../../types'
 import type * as aux from '../../types/_aux'
-import { DefaultMap, ifind, nonNullable } from '../../utils'
+import { DefaultMap, ifind, memoizeProp, nonNullable } from '../../utils'
 import type { ElementModel } from '../ElementModel'
 import type { LikeC4Model } from '../LikeC4Model'
 import {
@@ -18,9 +17,10 @@ import {
   type EdgeOrId,
   type NodeOrId,
   type WithTags,
-  getId,
 } from '../types'
+import { extractViewTitleFromPath, getId, normalizeViewPath } from '../utils'
 import { type EdgesIterator, EdgeModel } from './EdgeModel'
+import type { LikeC4ViewsFolder } from './LikeC4ViewsFolder'
 import { type NodesIterator, NodeModel } from './NodeModel'
 
 export type ViewsIterator<A extends Any, V extends $View<A> = $View<A>> = IteratorLike<LikeC4ViewModel<A, V>>
@@ -44,9 +44,29 @@ export class LikeC4ViewModel<A extends Any = Any, V extends $View<A> = $View<A>>
   public readonly $view: V
   public readonly $model: LikeC4Model<A>
 
-  constructor(model: LikeC4Model<A>, view: V) {
+  public readonly title: string | null
+
+  /**
+   * View folder this view belongs to.
+   * If view is top-level, this is the root folder.
+   */
+  public readonly folder: LikeC4ViewsFolder<A>
+  /**
+   * Path to this view, processed by {@link normalizeViewPath}
+   *
+   * @example
+   * "Group 1/Group 2/View"
+   */
+  public readonly viewPath: string
+
+  constructor(
+    model: LikeC4Model<A>,
+    view: V,
+    folder: LikeC4ViewsFolder<A>,
+  ) {
     this.$model = model
     this.$view = view
+    this.folder = folder
     for (const node of view.nodes) {
       const el = new NodeModel<A, V>(this, Object.freeze(node))
       this.#nodes.set(node.id, el)
@@ -79,6 +99,9 @@ export class LikeC4ViewModel<A extends Any = Any, V extends $View<A> = $View<A>>
       }
       this.#edges.set(edge.id, edgeModel)
     }
+
+    this.title = this.$view.title ? extractViewTitleFromPath(this.$view.title) : null
+    this.viewPath = this.$view.title ? normalizeViewPath(this.$view.title) : this.$view.id
   }
 
   get _type(): V[_type] {
@@ -89,8 +112,40 @@ export class LikeC4ViewModel<A extends Any = Any, V extends $View<A> = $View<A>>
     return this.$view.id
   }
 
-  get title(): string | null {
-    return this.$view.title
+  /**
+   * Returns title if defined, otherwise returns its {@link id}
+   */
+  get titleOrId(): string {
+    return this.title ?? this.id
+  }
+
+  /**
+   * Returns title if defined, otherwise returns `Untitled`.
+   */
+  get titleOrUntitled(): string {
+    return this.title ?? 'Untitled'
+  }
+
+  /**
+   * Returns path to this view as an array of groups and this view as the last element
+   * If view is top-level, returns only this view.
+   *
+   * @example
+   * viewPath = "Group 1/Group 2/View"
+   *
+   * breadcrumbs = [
+   *   "Group 1",             // folder
+   *   "Group 1/Group 2",     // folder
+   *   "Group 1/Group 2/View" // view
+   * ]
+   */
+  get breadcrumbs(): [...LikeC4ViewsFolder<A>[], this] {
+    return memoizeProp(this, 'breadcrumbs', () => {
+      if (!this.folder.isRoot) {
+        return [...this.folder.breadcrumbs, this]
+      }
+      return [this]
+    })
   }
 
   get description(): RichTextOrEmpty {