@likec4/language-server 1.13.0 → 1.15.0

package/src/generated-lib/icons.ts

@@ -342,7 +342,6 @@ export const LibIcons: string = `likec4lib { icons {
   azure:arc-data-services
   azure:arc-kubernetes
   azure:arc-machines
-  azure:arc-postgre-sql
   azure:arc-sql-managed-instance
   azure:arc-sql-server
   azure:atm-multistack

package/src/like-c4.langium

@@ -5,6 +5,7 @@ entry LikeC4Grammar:
     specifications+=SpecificationRule |
     models+=Model  |
     views+=ModelViews |
+    globals+=Globals |
     likec4lib+=LikeC4Lib
   )*
 ;
@@ -196,7 +197,7 @@ MetadataAttribute:
 ModelViews:
   name='views' '{' (
       views+=LikeC4ViewRule |
-      styles+=ViewRuleStyle
+      styles+=ViewRuleStyleOrGlobalRef
     )*
   '}';
 
@@ -266,13 +267,27 @@ ViewLayoutDirection returns string:
 
 ViewRule:
   ViewRulePredicate |
-  ViewRuleStyle |
+  ViewRuleGroup |
+  ViewRuleStyleOrGlobalRef |
   ViewRuleAutoLayout
 ;
 
+ViewRuleGroup:
+  'group' title=String? '{'
+    props+=(
+      ColorProperty |
+      BorderProperty |
+      OpacityProperty
+    )*
+    groupRules+=(
+      ViewRulePredicate |
+      ViewRuleGroup
+    )*
+  '}';
+
 DynamicViewRule:
   DynamicViewIncludePredicate |
-  ViewRuleStyle |
+  ViewRuleStyleOrGlobalRef |
   ViewRuleAutoLayout
 ;
 
@@ -440,6 +455,12 @@ ViewRuleStyle:
     )*
   '}';
 
+ViewRuleGlobalStyle:
+  'global' 'style' style=[GlobalStyleId];
+
+ViewRuleStyleOrGlobalRef:
+  ViewRuleStyle | ViewRuleGlobalStyle;
+
 ViewRuleAutoLayout:
   'autoLayout' direction=ViewLayoutDirection (
     rankSep=Number (
@@ -480,6 +501,31 @@ NavigateToProperty:
 RelationNavigateToProperty:
   key='navigateTo' value=DynamicViewRef;
 
+// Global -------------------------------------
+
+Globals:
+  name='global' '{'
+    (
+      styles+=(GlobalStyle | GlobalStyleGroup)*
+    )*
+  '}';
+
+GlobalStyleId:
+  name=IdTerminal;
+
+GlobalStyle:
+  'style' id=GlobalStyleId target=ElementExpressionsIterator '{'
+    props+=(
+      StyleProperty |
+      NotationProperty
+    )*
+  '}';
+
+GlobalStyleGroup:
+  'styleGroup' id=GlobalStyleId '{'
+    styles+=ViewRuleStyle*
+  '}';
+
 // Common properties -------------------------------------
 
 LinkProperty:
@@ -570,7 +616,7 @@ CustomColorId returns string:
   IdTerminal | ElementShape | ArrowType | LineOptions | 'element' | 'model';
 
 Id returns string:
-  IdTerminal | ElementShape | ThemeColor | ArrowType | LineOptions | 'element' | 'model';
+  IdTerminal | ElementShape | ThemeColor | ArrowType | LineOptions | 'element' | 'model' | 'group';
 
 fragment EqOperator:
   (

package/src/lsp/CompletionProvider.ts

@@ -1,11 +1,13 @@
-import { type GrammarAST, type MaybePromise } from 'langium'
+import { AstUtils, type GrammarAST, type MaybePromise } from 'langium'
 import {
   type CompletionAcceptor,
   type CompletionContext,
   type CompletionProviderOptions,
   DefaultCompletionProvider
 } from 'langium/lsp'
+import { anyPass } from 'remeda'
 import { CompletionItemKind, InsertTextFormat } from 'vscode-languageserver-types'
+import { ast } from '../ast'
 
 export class LikeC4CompletionProvider extends DefaultCompletionProvider {
   override readonly completionOptions = {
@@ -20,7 +22,15 @@ export class LikeC4CompletionProvider extends DefaultCompletionProvider {
     if (!this.filterKeyword(context, keyword)) {
       return
     }
-    if (['views', 'specification', 'model'].includes(keyword.value)) {
+    if (['title', 'description', 'technology'].includes(keyword.value)) {
+      return acceptor(context, {
+        label: keyword.value,
+        kind: CompletionItemKind.Property,
+        insertTextFormat: InsertTextFormat.Snippet,
+        insertText: `${keyword.value} '\${0}'`
+      })
+    }
+    if (['views', 'specification', 'model', 'with'].includes(keyword.value)) {
       return acceptor(context, {
         label: keyword.value,
         detail: `Insert ${keyword.value} block`,
@@ -29,6 +39,19 @@ export class LikeC4CompletionProvider extends DefaultCompletionProvider {
         insertText: `${keyword.value} {\n\t$0\n}`
       })
     }
+    if (keyword.value === 'group') {
+      return acceptor(context, {
+        label: keyword.value,
+        detail: `Insert group block`,
+        kind: CompletionItemKind.Class,
+        insertTextFormat: InsertTextFormat.Snippet,
+        insertText: [
+          'group \'${1:Title}\' {',
+          '\t$0',
+          '}'
+        ].join('\n')
+      })
+    }
     if (keyword.value === 'dynamic') {
       return acceptor(context, {
         label: keyword.value,
@@ -44,6 +67,51 @@ export class LikeC4CompletionProvider extends DefaultCompletionProvider {
         ].join('\n')
       })
     }
+    if (keyword.value === 'style' && context.node) {
+      if (AstUtils.hasContainerOfType(context.node, ast.isGlobalStyle)) {
+        return acceptor(context, {
+          label: keyword.value,
+          detail: `Insert ${keyword.value} block`,
+          kind: CompletionItemKind.Module,
+          insertTextFormat: InsertTextFormat.Snippet,
+          insertText: `${keyword.value} \${1:name} \${2:*} {\n\t\${3|color,shape,border,opacity,icon|} \$0\n}`
+        })
+      }
+      if (AstUtils.hasContainerOfType(context.node, anyPass([ast.isModelViews, ast.isGlobalStyleGroup]))) {
+        return acceptor(context, {
+          label: keyword.value,
+          detail: `Insert ${keyword.value} block`,
+          kind: CompletionItemKind.Module,
+          insertTextFormat: InsertTextFormat.Snippet,
+          insertText: `${keyword.value} \${1:*} {\n\t\${2|color,shape,border,opacity,icon|} \$0\n}`
+        })
+      }
+      return acceptor(context, {
+        label: keyword.value,
+        detail: `Insert ${keyword.value} block`,
+        kind: CompletionItemKind.Module,
+        insertTextFormat: InsertTextFormat.Snippet,
+        insertText: `${keyword.value} {\n\t\${1|color,shape,border,opacity,icon|} \$0\n}`
+      })
+    }
+    if (keyword.value === 'extend') {
+      return acceptor(context, {
+        label: keyword.value,
+        detail: `Extend another view`,
+        kind: CompletionItemKind.Class,
+        insertTextFormat: InsertTextFormat.Snippet,
+        insertText: 'extend ${1:element} {\n\t$0\n}'
+      })
+    }
+
+    if (keyword.value === 'autoLayout') {
+      return acceptor(context, {
+        label: keyword.value,
+        kind: CompletionItemKind.Class,
+        insertTextFormat: InsertTextFormat.Snippet,
+        insertText: 'autoLayout ${1|TopBottom,BottomTop,LeftRight,RightLeft|}$0'
+      })
+    }
     acceptor(context, {
       label: keyword.value,
       kind: this.getKeywordCompletionItemKind(keyword),

package/src/model/model-builder.ts

@@ -13,6 +13,7 @@ import { deepEqual as eq } from 'fast-equals'
 import type { Cancellation, LangiumDocument, LangiumDocuments, URI, WorkspaceCache } from 'langium'
 import { Disposable, DocumentState, interruptAndCheck } from 'langium'
 import {
+  entries,
   filter,
   flatMap,
   forEach,
@@ -45,8 +46,7 @@ import { isParsedLikeC4LangiumDocument } from '../ast'
 import { logError, logger, logWarnError } from '../logger'
 import { computeDynamicView, computeView, LikeC4ModelGraph } from '../model-graph'
 import type { LikeC4Services } from '../module'
-import { printDocs } from '../utils/printDocs'
-import { assignNavigateTo, resolveRelativePaths, resolveRulesExtendedViews } from '../view-utils'
+import { assignNavigateTo, resolveGlobalRules, resolveRelativePaths, resolveRulesExtendedViews } from '../view-utils'
 
 function buildModel(services: LikeC4Services, docs: ParsedLikeC4LangiumDocument[]): c4.ParsedLikeC4Model {
   const c4Specification: ParsedAstSpecification = {
@@ -211,6 +211,23 @@ function buildModel(services: LikeC4Services, docs: ParsedLikeC4LangiumDocument[
     indexBy(prop('id'))
   )
 
+  const parsedGlobals: {
+    styles: Record<c4.GlobalStyleID, c4.ViewRuleStyle[]>
+  } = {
+    styles: {}
+  }
+  Object.assign(parsedGlobals.styles, ...docs.map(d => d.c4Globals.styles))
+
+  const globals: {
+    styles: Record<c4.GlobalStyleID, c4.GlobalStyle>
+  } = {
+    styles: pipe(
+      entries(parsedGlobals.styles),
+      map(([id, styles]) => ({ id, styles })),
+      indexBy(prop('id'))
+    )
+  }
+
   function toC4View(doc: LangiumDocument) {
     const docUri = doc.uri.toString()
     return (parsedAstView: ParsedAstView): c4.LikeC4View => {
@@ -287,6 +304,7 @@ function buildModel(services: LikeC4Services, docs: ParsedLikeC4LangiumDocument[
     },
     elements,
     relations,
+    globals,
     views
   }
 }
@@ -396,6 +414,7 @@ export class LikeC4ModelBuilder {
         specification: model.specification,
         elements: model.elements,
         relations: model.relations,
+        globals: model.globals,
         views
       }
     })
@@ -441,7 +460,10 @@ export class LikeC4ModelBuilder {
           return null
         }
         const index = new LikeC4ModelGraph(model)
-        const result = isElementView(view) ? computeView(view, index) : computeDynamicView(view, index)
+        const resolvedView = resolveGlobalRules(view, model.globals.styles)
+        const result = isElementView(resolvedView)
+          ? computeView(resolvedView, index)
+          : computeDynamicView(resolvedView, index)
         if (!result.isSuccess) {
           logError(result.error)
           return null

package/src/model/model-parser.ts

@@ -30,15 +30,13 @@ import {
   ViewOps
 } from '../ast'
 import { elementRef, getFqnElementRef } from '../elementRef'
+import { isGlobalStyle, isGlobalStyleGroup, type NotationProperty } from '../generated/ast'
 import { logError, logger, logWarnError } from '../logger'
 import type { LikeC4Services } from '../module'
 import { stringHash } from '../utils'
 import { deserializeFromComment, hasManualLayout } from '../view-utils/manual-layout'
 import type { FqnIndex } from './fqn-index'
 import { parseWhereClause } from './model-parser-where'
-import {
-  type NotationProperty
-} from '../generated/ast'
 
 const { getDocument } = AstUtils
 
@@ -83,6 +81,7 @@ export class LikeC4ModelParser {
     const { isValid } = checksFromDiagnostics(doc)
     this.parseSpecification(doc, isValid)
     this.parseModel(doc, isValid)
+    this.parseGlobal(doc, isValid)
     this.parseViews(doc, isValid)
     return doc
   }
@@ -285,11 +284,57 @@ export class LikeC4ModelParser {
     }
   }
 
+  private parseGlobal(doc: ParsedLikeC4LangiumDocument, isValid: IsValidFn) {
+    const { parseResult, c4Globals } = doc
+
+    const globals = parseResult.value.globals.filter(isValid)
+    const styles = globals.flatMap(r => r.styles.filter(isValid))
+    for (const style of styles) {
+      try {
+        const globalStyleId = style.id.name as c4.GlobalStyleID
+        if (!isTruthy(globalStyleId)) {
+          continue
+        }
+        if (globalStyleId in c4Globals.styles) {
+          logger.warn(`Global style named "${globalStyleId}" is already defined`)
+          continue
+        }
+
+        const styles = this.parseGlobalStyleOrGroup(style, isValid)
+        if (styles.length > 0) {
+          c4Globals.styles[globalStyleId] = styles as c4.NonEmptyArray<c4.ViewRuleStyle>
+        }
+      } catch (e) {
+        logWarnError(e)
+      }
+    }
+  }
+
+  private parseGlobalStyleOrGroup(
+    astRule: ast.GlobalStyle | ast.GlobalStyleGroup,
+    isValid: IsValidFn
+  ): c4.ViewRuleStyle[] {
+    if (ast.isGlobalStyle(astRule)) {
+      return [this.parseGlobalStyle(astRule, isValid)]
+    }
+    if (ast.isGlobalStyleGroup(astRule)) {
+      return astRule.styles.map(s => this.parseViewRuleStyle(s, isValid))
+    }
+    nonexhaustive(astRule)
+  }
+
+  private parseGlobalStyle(astRule: ast.GlobalStyle, isValid: IsValidFn): c4.ViewRuleStyle {
+    const styleProps = astRule.props.filter(ast.isStyleProperty)
+    const targets = astRule.target
+    const notation = astRule.props.find(ast.isNotationProperty)
+    return this.parseRuleStyle(styleProps, targets, isValid, notation)
+  }
+
   private parseViews(doc: ParsedLikeC4LangiumDocument, isValid: IsValidFn) {
     const viewBlocks = doc.parseResult.value.views.filter(v => isValid(v))
     for (const viewBlock of viewBlocks) {
       const localStyles = viewBlock.styles
-        .flatMap(s => this.parseViewRuleStyle(s, isValid))
+        .flatMap(s => this.parseViewRuleStyleOrGlobalRef(s, isValid))
       const stylesToApply = localStyles
 
       for (const view of viewBlock.views) {
@@ -298,7 +343,9 @@ export class LikeC4ModelParser {
             continue
           }
           doc.c4Views.push(
-            ast.isElementView(view) ? this.parseElementView(view, stylesToApply, isValid) : this.parseDynamicElementView(view, stylesToApply, isValid)
+            ast.isElementView(view)
+              ? this.parseElementView(view, stylesToApply, isValid)
+              : this.parseDynamicElementView(view, stylesToApply, isValid)
           )
         } catch (e) {
           logWarnError(e)
@@ -498,8 +545,11 @@ export class LikeC4ModelParser {
 
   private parseRelationPredicate(astNode: ast.RelationPredicate, _isValid: IsValidFn): c4.RelationPredicateExpression {
     if (ast.isRelationPredicateWith(astNode)) {
-      const subject = ast.isRelationPredicateWhere(astNode.subject) ? astNode.subject.subject : astNode.subject
-      return this.parseRelationPredicateWith(astNode, subject)
+      let relation = ast.isRelationPredicateWhere(astNode.subject)
+        ? this.parseRelationPredicateWhere(astNode.subject)
+        : this.parseRelationExpr(astNode.subject)
+
+      return this.parseRelationPredicateWith(astNode, relation)
     }
     if (ast.isRelationPredicateWhere(astNode)) {
       return this.parseRelationPredicateWhere(astNode)
@@ -526,9 +576,8 @@ export class LikeC4ModelParser {
 
   private parseRelationPredicateWith(
     astNode: ast.RelationPredicateWith,
-    subject: ast.RelationExpression
+    relation: c4.RelationExpression | c4.RelationWhereExpr
   ): c4.CustomRelationExpr {
-    const relation = this.parseRelationExpr(subject)
     const props = astNode.custom?.props ?? []
     return props.reduce(
       (acc, prop) => {
@@ -604,12 +653,25 @@ export class LikeC4ModelParser {
     if (ast.isViewRulePredicate(astRule)) {
       return this.parseViewRulePredicate(astRule, isValid)
     }
-    if (ast.isViewRuleStyle(astRule)) {
-      return this.parseViewRuleStyle(astRule, isValid)
+    if (ast.isViewRuleStyleOrGlobalRef(astRule)) {
+      return this.parseViewRuleStyleOrGlobalRef(astRule, isValid)
     }
     if (ast.isViewRuleAutoLayout(astRule)) {
       return toAutoLayout(astRule)
     }
+    if (ast.isViewRuleGroup(astRule)) {
+      return this.parseViewRuleGroup(astRule, isValid)
+    }
+    nonexhaustive(astRule)
+  }
+
+  private parseViewRuleStyleOrGlobalRef(astRule: ast.ViewRuleStyleOrGlobalRef, isValid: IsValidFn): c4.ViewRuleStyleOrGlobalRef {
+    if (ast.isViewRuleStyle(astRule)) {
+      return this.parseViewRuleStyle(astRule, isValid)
+    }
+    if (ast.isViewRuleGlobalStyle(astRule)) {
+      return this.parseViewRuleGlobalStyle(astRule, isValid)
+    }
     nonexhaustive(astRule)
   }
 
@@ -620,7 +682,39 @@ export class LikeC4ModelParser {
     return this.parseRuleStyle(styleProps, targets, isValid, notation)
   }
 
-  private parseRuleStyle(styleProperties: ast.StyleProperty[], elementExpressionsIterator: ast.ElementExpressionsIterator, isValid: IsValidFn, notationProperty?: NotationProperty): c4.ViewRuleStyle {
+  private parseViewRuleGroup(astNode: ast.ViewRuleGroup, _isValid: IsValidFn): c4.ViewRuleGroup {
+    const groupRules = [] as c4.ViewRuleGroup['groupRules']
+    for (const rule of astNode.groupRules) {
+      try {
+        if (!_isValid(rule)) {
+          continue
+        }
+        if (ast.isViewRulePredicate(rule)) {
+          groupRules.push(this.parseViewRulePredicate(rule, _isValid))
+          continue
+        }
+        if (ast.isViewRuleGroup(rule)) {
+          groupRules.push(this.parseViewRuleGroup(rule, _isValid))
+          continue
+        }
+        nonexhaustive(rule)
+      } catch (e) {
+        logWarnError(e)
+      }
+    }
+    return {
+      title: toSingleLine(astNode.title) ?? null,
+      groupRules,
+      ...toElementStyle(astNode.props, _isValid)
+    }
+  }
+
+  private parseRuleStyle(
+    styleProperties: ast.StyleProperty[],
+    elementExpressionsIterator: ast.ElementExpressionsIterator,
+    isValid: IsValidFn,
+    notationProperty?: NotationProperty
+  ): c4.ViewRuleStyle {
     const styleProps = toElementStyle(styleProperties, isValid)
     const notation = removeIndent(notationProperty?.value)
     const targets = this.parseElementExpressionsIterator(elementExpressionsIterator)
@@ -633,6 +727,12 @@ export class LikeC4ModelParser {
     }
   }
 
+  private parseViewRuleGlobalStyle(astRule: ast.ViewRuleGlobalStyle, _isValid: IsValidFn): c4.ViewRuleGlobalStyle {
+    return {
+      styleId: astRule.style.$refText as c4.GlobalStyleID
+    }
+  }
+
   private parseViewManualLaout(node: ast.DynamicView | ast.ElementView): c4.ViewManualLayout | undefined {
     const commentNode = CstUtils.findCommentNode(node.$cstNode, ['BLOCK_COMMENT'])
     if (!commentNode || !hasManualLayout(commentNode.text)) {
@@ -729,7 +829,11 @@ export class LikeC4ModelParser {
     return step
   }
 
-  private parseElementView(astNode: ast.ElementView, additionalStyles: c4.ViewRuleStyle[], isValid: IsValidFn): ParsedAstElementView {
+  private parseElementView(
+    astNode: ast.ElementView,
+    additionalStyles: c4.ViewRuleStyleOrGlobalRef[],
+    isValid: IsValidFn
+  ): ParsedAstElementView {
     const body = astNode.body
     invariant(body, 'ElementView body is not defined')
     const astPath = this.getAstNodePath(astNode)
@@ -770,14 +874,17 @@ export class LikeC4ModelParser {
       description,
       tags,
       links: isNonEmptyArray(links) ? links : null,
-      rules: [...additionalStyles, ...body.rules.flatMap(n => {
-        try {
-          return isValid(n) ? this.parseViewRule(n, isValid) : []
-        } catch (e) {
-          logWarnError(e)
-          return []
-        }
-      })],
+      rules: [
+        ...additionalStyles,
+        ...body.rules.flatMap(n => {
+          try {
+            return isValid(n) ? this.parseViewRule(n, isValid) : []
+          } catch (e) {
+            logWarnError(e)
+            return []
+          }
+        })
+      ],
       ...(viewOf && { viewOf }),
       ...(manualLayout && { manualLayout })
     }
@@ -794,7 +901,11 @@ export class LikeC4ModelParser {
     return view
   }
 
-  private parseDynamicElementView(astNode: ast.DynamicView, additionalStyles: c4.ViewRuleStyle[], isValid: IsValidFn): ParsedAstDynamicView {
+  private parseDynamicElementView(
+    astNode: ast.DynamicView,
+    additionalStyles: c4.ViewRuleStyleOrGlobalRef[],
+    isValid: IsValidFn
+  ): ParsedAstDynamicView {
     const body = astNode.body
     invariant(body, 'DynamicElementView body is not defined')
     // only valid props
@@ -827,14 +938,17 @@ export class LikeC4ModelParser {
       description,
       tags,
       links: isNonEmptyArray(links) ? links : null,
-      rules: [...additionalStyles, ...body.rules.flatMap(n => {
-        try {
-          return isValid(n) ? this.parseDynamicViewRule(n, isValid) : []
-        } catch (e) {
-          logWarnError(e)
-          return []
-        }
-      }, [] as Array<c4.DynamicViewRule>)],
+      rules: [
+        ...additionalStyles,
+        ...body.rules.flatMap(n => {
+          try {
+            return isValid(n) ? this.parseDynamicViewRule(n, isValid) : []
+          } catch (e) {
+            logWarnError(e)
+            return []
+          }
+        }, [] as Array<c4.DynamicViewRule>)
+      ],
       steps: body.steps.reduce((acc, n) => {
         try {
           if (isValid(n)) {
@@ -857,8 +971,8 @@ export class LikeC4ModelParser {
     if (ast.isDynamicViewIncludePredicate(astRule)) {
       return this.parseDynamicViewIncludePredicate(astRule, isValid)
     }
-    if (ast.isViewRuleStyle(astRule)) {
-      return this.parseViewRuleStyle(astRule, isValid)
+    if (ast.isViewRuleStyleOrGlobalRef(astRule)) {
+      return this.parseViewRuleStyleOrGlobalRef(astRule, isValid)
     }
     if (ast.isViewRuleAutoLayout(astRule)) {
       return toAutoLayout(astRule)
@@ -866,7 +980,10 @@ export class LikeC4ModelParser {
     nonexhaustive(astRule)
   }
 
-  private parseDynamicViewIncludePredicate(astRule: ast.DynamicViewIncludePredicate, isValid: IsValidFn): c4.DynamicViewIncludeRule {
+  private parseDynamicViewIncludePredicate(
+    astRule: ast.DynamicViewIncludePredicate,
+    isValid: IsValidFn
+  ): c4.DynamicViewIncludeRule {
     const include = [] as c4.ElementPredicateExpression[]
     let iter: ast.DynamicViewPredicateIterator | undefined = astRule.predicates
     while (iter) {

package/src/model-graph/compute-view/__test__/fixture.ts

@@ -11,6 +11,10 @@ import {
   type ElementWhereExpr,
   type Expression as C4Expression,
   type Fqn,
+  isElementRef,
+  isElementWhere,
+  isRelationExpression,
+  isRelationWhere,
   type NonEmptyArray,
   type Relation,
   type RelationID,
@@ -20,6 +24,7 @@ import {
   type Tag,
   type ViewID,
   type ViewRule,
+  type ViewRuleGroup,
   type ViewRulePredicate,
   type ViewRuleStyle,
   type WhereOperator
@@ -362,8 +367,6 @@ export type Expression =
   | IncomingExpr
   | OutgoingExpr
   | RelationExpr
-  | ElementWhereExpr
-  | RelationWhereExpr
 
 export function $custom(
   expr: ElementRefExpr,
@@ -465,9 +468,41 @@ export function $expr(expr: Expression | C4Expression): C4Expression {
   }
 }
 
-export function $include(expr: Expression | C4Expression): ViewRulePredicate {
+type CustomProps = {
+  where?: WhereOperator<TestTag, string>
+  with?: {
+    title?: string
+    description?: string
+    technology?: string
+    shape?: ElementShape
+    color?: Color
+    border?: BorderStyle
+    icon?: string
+    opacity?: number
+    navigateTo?: string
+  } & Omit<C4CustomRelationExpr['customRelation'], 'relation' | 'navigateTo'>
+}
+export function $include(expr: Expression | C4Expression, props?: CustomProps): ViewRulePredicate {
+  let _expr = props?.where ? $where(expr, props.where) : $expr(expr)
+  if (props?.with) {
+    if (isRelationExpression(_expr) || isRelationWhere(_expr)) {
+      _expr = {
+        customRelation: {
+          relation: _expr,
+          ...props.with as any
+        }
+      }
+    } else if (isElementRef(_expr) || isElementWhere(_expr)) {
+      _expr = {
+        custom: {
+          expr: _expr,
+          ...props.with as any
+        }
+      }
+    }
+  }
   return {
-    include: [$expr(expr)]
+    include: [_expr]
   }
 }
 export function $exclude(expr: Expression | C4Expression): ViewRulePredicate {
@@ -475,6 +510,12 @@ export function $exclude(expr: Expression | C4Expression): ViewRulePredicate {
     exclude: [$expr(expr)]
   }
 }
+export function $group(groupRules: ViewRuleGroup['groupRules']): ViewRuleGroup {
+  return {
+    title: null,
+    groupRules
+  }
+}
 
 export function $style(element: ElementRefExpr, style: ViewRuleStyle['style']): ViewRuleStyle {
   return {