@cohesivesystems/presentation-core 0.1.0-alpha.1

package/src/presentation-projection-diagnostics.ts

@@ -0,0 +1,71 @@
+export type PresentationProjectionDiagnosticSeverity = 'error' | 'info' | 'warning'
+
+export type PresentationProjectionDiagnosticCategory =
+  | 'escape-hatch'
+  | 'incomplete-projection'
+  | 'local-interpretation'
+  | 'missing-binding'
+  | 'missing-definition'
+  | 'unsupported'
+  | 'unbound'
+
+export type PresentationProjectionInterpretationStatus =
+  | 'bound'
+  | 'escape-hatch'
+  | 'locally-interpreted'
+  | 'projected'
+  | 'unbound'
+  | 'unsupported'
+
+/** Stable reference to the IR element or frontend binding that produced a diagnostic. */
+export interface PresentationProjectionDiagnosticSubject {
+  readonly id: string
+  readonly kind: string
+  readonly name?: string | null
+}
+
+/** Projection/interpreter boundary that produced a diagnostic. */
+export interface PresentationProjectionInterpretation {
+  readonly status: PresentationProjectionInterpretationStatus
+  readonly target: string
+}
+
+/**
+ * Structured TODO emitted by projection interpreters when a backend-declared
+ * construct cannot yet be fully interpreted by the frontend.
+ */
+export interface PresentationProjectionDiagnostic {
+  readonly category?: PresentationProjectionDiagnosticCategory
+  readonly details?: Readonly<Record<string, unknown>>
+  readonly id: string
+  readonly interpretation?: PresentationProjectionInterpretation
+  readonly message: string
+  readonly severity: PresentationProjectionDiagnosticSeverity
+  readonly source: string
+  readonly subject?: PresentationProjectionDiagnosticSubject
+  readonly suggestedNextStep?: string
+}
+
+export function createPresentationProjectionDiagnostic(
+  diagnostic: PresentationProjectionDiagnostic,
+): PresentationProjectionDiagnostic {
+  return diagnostic
+}
+
+/** Collapses diagnostic streams from independent projection interpreters. */
+export function mergePresentationProjectionDiagnostics(
+  ...groups: readonly (readonly PresentationProjectionDiagnostic[] | null | undefined)[]
+): readonly PresentationProjectionDiagnostic[] {
+  const diagnostics = groups.flatMap((group) => group ?? [])
+  const seen = new Set<string>()
+
+  return diagnostics.filter((diagnostic) => {
+    const key = `${diagnostic.source}:${diagnostic.id}`
+    if (seen.has(key)) {
+      return false
+    }
+
+    seen.add(key)
+    return true
+  })
+}

package/src/presentation-projection-trace.ts

@@ -0,0 +1,293 @@
+import type {
+  NavigationRouteDefinition,
+  PageHostDefinition,
+  ViewDefinition,
+} from '@cohesivesystems/presentation-contracts'
+import {
+  findNavigationRoute,
+  resolveNavigationRouteId,
+  type NavigationDefinitionProjection,
+} from './navigation'
+import {
+  getPresentationSurfaceDataSourceIds,
+  getPresentationSurfaceViewTree,
+  getPresentationViewProjectedActions,
+  getPresentationViewProjectedDataSourceIds,
+  getPresentationViewProjectedFieldIds,
+  getPresentationViewSemanticRole,
+  resolveNavigationTarget,
+} from './presentation-semantics'
+import { getRegionViewIds } from './presentation-view-tree'
+
+export interface PresentationProjectionTraceModule {
+  readonly Views: readonly ViewDefinition[]
+}
+
+export interface CreatePresentationProjectionTraceOptions<
+  TModule extends PresentationProjectionTraceModule,
+  TRoute extends NavigationRouteDefinition = NavigationRouteDefinition,
+  TPageHost extends PageHostDefinition = PageHostDefinition,
+> {
+  readonly componentSet?: string
+  readonly module: TModule | null
+  readonly navigation: NavigationDefinitionProjection<TRoute, TPageHost> | null
+  readonly pathname: string
+  readonly resolvePageHostRenderer?: PresentationProjectionTracePageHostRendererResolver<
+    TModule,
+    TRoute,
+    TPageHost
+  >
+  readonly resolveViewRenderer?: PresentationProjectionTraceViewRendererResolver<TModule>
+}
+
+export interface PresentationProjectionTracePageHostRendererResolutionContext<
+  TModule extends PresentationProjectionTraceModule,
+  TRoute extends NavigationRouteDefinition,
+  TPageHost extends PageHostDefinition,
+> {
+  readonly componentSet?: string
+  readonly module: TModule
+  readonly pageHost: TPageHost | null
+  readonly route: TRoute | null
+}
+
+export type PresentationProjectionTracePageHostRendererResolver<
+  TModule extends PresentationProjectionTraceModule,
+  TRoute extends NavigationRouteDefinition,
+  TPageHost extends PageHostDefinition,
+> = (
+  context: PresentationProjectionTracePageHostRendererResolutionContext<
+    TModule,
+    TRoute,
+    TPageHost
+  >,
+) => PresentationProjectionTracePageHostRenderer | null
+
+export interface PresentationProjectionTraceViewRendererResolutionContext<
+  TModule extends PresentationProjectionTraceModule,
+> {
+  readonly componentSet?: string
+  readonly module: TModule
+  readonly routeId: string | null
+  readonly view: ViewDefinition
+}
+
+export interface PresentationProjectionTraceViewRendererResolution {
+  readonly componentKey: string | null
+  readonly componentRole: string | null
+  readonly rendererResolved: boolean
+  readonly resolutionSource: string | null
+  readonly semanticRole?: string | null
+}
+
+export type PresentationProjectionTraceViewRendererResolver<
+  TModule extends PresentationProjectionTraceModule,
+> = (
+  context: PresentationProjectionTraceViewRendererResolutionContext<TModule>,
+) => PresentationProjectionTraceViewRendererResolution | null
+
+export interface PresentationProjectionTrace {
+  readonly dataSourceIds: readonly string[]
+  readonly moduleAvailable: boolean
+  readonly pageHost: PresentationProjectionTracePageHost | null
+  readonly pageHostRenderer: PresentationProjectionTracePageHostRenderer | null
+  readonly pathname: string
+  readonly route: PresentationProjectionTraceRoute | null
+  readonly surface: PresentationProjectionTraceSurface | null
+  readonly views: readonly PresentationProjectionTraceView[]
+}
+
+export interface PresentationProjectionTraceRoute {
+  readonly id: string
+  readonly label: string
+  readonly pageHostId: string
+  readonly pathTemplate: string
+}
+
+export interface PresentationProjectionTracePageHost {
+  readonly documentProfileId: string | null
+  readonly id: string
+  readonly kind: string
+  readonly viewId: string | null
+  readonly workspaceId: string | null
+}
+
+export interface PresentationProjectionTracePageHostRenderer {
+  readonly componentKey: string | null
+  readonly componentRole: string | null
+  readonly rendererKey: string | null
+  readonly resolutionSource: string | null
+  readonly semanticRole: string | null
+  readonly targetBindingSource: string | null
+}
+
+export interface PresentationProjectionTraceSurface {
+  readonly id: string
+  readonly rootViewId: string | null
+  readonly workspaceId: string | null
+}
+
+export interface PresentationProjectionTraceView {
+  readonly actionCount: number
+  readonly componentKey: string | null
+  readonly componentRole: string | null
+  readonly dataSourceIds: readonly string[]
+  readonly fieldIds: readonly string[]
+  readonly id: string
+  readonly kind: string
+  readonly name: string
+  readonly regions: readonly PresentationProjectionTraceRegion[]
+  readonly rendererResolved: boolean
+  readonly resolutionSource: string | null
+  readonly semanticRole: string
+  readonly subjectDataSourceId: string | null
+}
+
+export interface PresentationProjectionTraceRegion {
+  readonly dataSourceIds: readonly string[]
+  readonly id: string
+  readonly viewIds: readonly string[]
+}
+
+/**
+ * Builds a read-only trace of route, page-host, surface, view, and renderer
+ * resolution. Framework adapters can supply renderer resolver functions; the
+ * trace model itself remains pure presentation IR/runtime state.
+ */
+export function createPresentationProjectionTrace<
+  TModule extends PresentationProjectionTraceModule,
+  TRoute extends NavigationRouteDefinition = NavigationRouteDefinition,
+  TPageHost extends PageHostDefinition = PageHostDefinition,
+>({
+  componentSet,
+  module,
+  navigation,
+  pathname,
+  resolvePageHostRenderer,
+  resolveViewRenderer,
+}: CreatePresentationProjectionTraceOptions<
+  TModule,
+  TRoute,
+  TPageHost
+>): PresentationProjectionTrace {
+  const routeId = resolveNavigationRouteId(navigation, pathname)
+  const route = navigation && routeId
+    ? findNavigationRoute<TRoute>(navigation, routeId)
+    : null
+  const navigationTarget = navigation && route
+    ? resolveNavigationTarget<
+        NavigationDefinitionProjection<TRoute, TPageHost>,
+        TRoute,
+        TPageHost
+      >(navigation, route)
+    : null
+  const pageHost = navigationTarget?.pageHost ?? null
+  const rootViewId = pageHost?.View?.ViewId ?? null
+  const rootView = module && rootViewId
+    ? module.Views.find((view) => view.Id === rootViewId) ?? null
+    : null
+  const surface = pageHost
+    ? {
+        id: pageHost.Id,
+        rootView,
+        rootViewId,
+        workspaceRef: pageHost.Workspace,
+      }
+    : null
+  const viewTree = module
+    ? getPresentationSurfaceViewTree(module, { rootView })
+    : []
+  const pageHostRenderer = module && resolvePageHostRenderer
+    ? resolvePageHostRenderer({
+        componentSet,
+        module,
+        pageHost,
+        route,
+      })
+    : null
+
+  return {
+    dataSourceIds: module
+      ? getPresentationSurfaceDataSourceIds(module, { rootView })
+      : [],
+    moduleAvailable: Boolean(module),
+    pageHost: pageHost
+      ? {
+          documentProfileId: pageHost.Workspace?.DocumentProfileId ?? null,
+          id: pageHost.Id,
+          kind: String(pageHost.Kind),
+          viewId: rootViewId,
+          workspaceId: pageHost.Workspace?.WorkspaceId ?? null,
+        }
+      : null,
+    pageHostRenderer,
+    pathname,
+    route: route
+      ? {
+          id: route.Id,
+          label: route.Label,
+          pageHostId: route.PageHostId,
+          pathTemplate: route.PathTemplate,
+        }
+      : null,
+    surface: surface
+      ? {
+          id: surface.id,
+          rootViewId: surface.rootViewId,
+          workspaceId: surface.workspaceRef?.WorkspaceId ?? null,
+        }
+      : null,
+    views: module
+      ? viewTree.map((view) =>
+          createViewTrace({
+            componentSet,
+            module,
+            resolveViewRenderer,
+            routeId: route?.Id ?? null,
+            view,
+          }),
+        )
+      : [],
+  }
+}
+
+function createViewTrace<TModule extends PresentationProjectionTraceModule>({
+  componentSet,
+  module,
+  resolveViewRenderer,
+  routeId,
+  view,
+}: {
+  readonly componentSet?: string
+  readonly module: TModule
+  readonly resolveViewRenderer?: PresentationProjectionTraceViewRendererResolver<TModule>
+  readonly routeId: string | null
+  readonly view: ViewDefinition
+}): PresentationProjectionTraceView {
+  const resolution = resolveViewRenderer?.({
+    componentSet,
+    module,
+    routeId,
+    view,
+  }) ?? null
+
+  return {
+    actionCount: getPresentationViewProjectedActions(view).length,
+    componentKey: resolution?.componentKey ?? null,
+    componentRole: resolution?.componentRole ?? null,
+    dataSourceIds: getPresentationViewProjectedDataSourceIds(view),
+    fieldIds: getPresentationViewProjectedFieldIds(view),
+    id: view.Id,
+    kind: String(view.Kind),
+    name: view.Name,
+    regions: view.Regions.map((region) => ({
+      dataSourceIds: region.DataSourceIds,
+      id: region.Id,
+      viewIds: getRegionViewIds(region),
+    })),
+    rendererResolved: Boolean(resolution?.rendererResolved),
+    resolutionSource: resolution?.resolutionSource ?? null,
+    semanticRole: resolution?.semanticRole ?? getPresentationViewSemanticRole(view),
+    subjectDataSourceId: view.Subject.DataSourceId ?? null,
+  }
+}

package/src/presentation-query-form-state.ts

@@ -0,0 +1,54 @@
+import type { QueryFormDefinition } from './module'
+
+export interface PresentationQueryFormState<TValue = unknown> {
+  readonly appliedValue: TValue
+  readonly draftValue: TValue
+  readonly queryForm: QueryFormDefinition
+  readonly queryFormId: string
+}
+
+export type PresentationQueryFormStateMap = Readonly<
+  Record<string, PresentationQueryFormState>
+>
+
+export interface PresentationQueryFormStateContext {
+  readonly queryFormStates?: PresentationQueryFormStateMap
+}
+
+export function readPresentationQueryFormDraftValue<TValue = unknown>(
+  context: PresentationQueryFormStateContext,
+  dataSourceId: string,
+): TValue | undefined {
+  return findPresentationQueryFormStateForDataSource(context, dataSourceId, 'draft')
+    ?.draftValue as TValue | undefined
+}
+
+export function readPresentationQueryFormAppliedValue<TValue = unknown>(
+  context: PresentationQueryFormStateContext,
+  dataSourceId: string,
+): TValue | undefined {
+  return findPresentationQueryFormStateForDataSource(context, dataSourceId, 'applied')
+    ?.appliedValue as TValue | undefined
+}
+
+export function findPresentationQueryFormStateForDataSource(
+  { queryFormStates = {} }: PresentationQueryFormStateContext,
+  dataSourceId: string,
+  phase: 'applied' | 'draft',
+) {
+  return Object.values(queryFormStates).find((state) =>
+    phase === 'draft'
+      ? state.queryForm.Target.State.DraftDataSourceId === dataSourceId
+      : isAppliedQueryFormDataSource(state.queryForm, dataSourceId),
+  ) ?? null
+}
+
+function isAppliedQueryFormDataSource(
+  queryForm: QueryFormDefinition,
+  dataSourceId: string,
+) {
+  const state = queryForm.Target.State
+  return state.AppliedDataSourceId === dataSourceId ||
+    state.ResultDataSourceId === dataSourceId ||
+    state.SynchronizedDataSourceIds.includes(dataSourceId)
+}

package/src/presentation-renderer-registry.ts

@@ -0,0 +1,269 @@
+import {
+  presentationBindingKinds,
+  type PresentationBindingDefinition,
+  type ViewDefinition,
+} from '@cohesivesystems/presentation-contracts'
+import { getPresentationViewSemanticRole } from './presentation-semantics'
+import {
+  createPresentationEnumDiscriminator,
+  resolvePresentationComponentBinding,
+  type PresentationEnumDiscriminator,
+} from './target-bindings'
+
+/**
+ * Registry for composite view renderers, keyed by progressively more semantic
+ * matching strategies. Resolution prefers semantic roles and view kinds before
+ * using component bindings as an explicit escape hatch.
+ */
+export interface PresentationCompositeRendererRegistry<TRenderer = unknown> {
+  /** Renderers keyed by semantic component roles resolved from target bindings. */
+  readonly byComponentRole?: Readonly<Record<string, TRenderer>>
+
+  /** Renderers keyed by concrete component keys resolved from target bindings. */
+  readonly byComponentKey?: Readonly<Record<string, TRenderer>>
+
+  /** Renderers keyed by semantic view role. */
+  readonly bySemanticRole?: Readonly<Record<string, TRenderer>>
+
+  /** Renderers keyed by generated view kind discriminator values. */
+  readonly byViewKind?: Readonly<Record<string, TRenderer>>
+
+  /** Renderer used when no key, role, or kind-specific renderer matches. */
+  readonly fallback?: TRenderer
+}
+
+/**
+ * Complete renderer registry used by presentation projection runtimes. The
+ * renderer values are intentionally generic so core can resolve semantic
+ * bindings without depending on React, DOM, or any other adapter runtime.
+ */
+export interface PresentationRendererRegistry<
+  TViewRenderer = unknown,
+  TControlRenderer = unknown,
+  TValueRenderer = unknown,
+> {
+  /** Composite renderers that adapt whole semantic views. */
+  readonly composites?: PresentationCompositeRendererRegistry<TViewRenderer>
+
+  /** Control renderers keyed by presentation control ids or component keys. */
+  readonly controls?: Readonly<Record<string, TControlRenderer>>
+
+  /** Value renderers keyed by semantic value or field renderer ids. */
+  readonly values?: Readonly<Record<string, TValueRenderer>>
+}
+
+/**
+ * Minimal module projection needed to resolve component bindings without
+ * coupling renderer resolution to a full generated presentation module shape.
+ */
+export interface PresentationRendererBindingModuleProjection {
+  /** Binding targets declared by the presentation module. */
+  readonly Targets: readonly {
+    /** Bindings declared for this target. */
+    readonly Bindings: readonly PresentationBindingDefinition[]
+
+    /** Optional component set that scopes concrete component keys. */
+    readonly ComponentSet?: string | null
+
+    /** Target discriminator value, such as the generated React target kind. */
+    readonly Target: string | number
+  }[]
+}
+
+/**
+ * Combines renderer registries in declaration order, with later registries
+ * overriding earlier renderer keys and fallback renderers.
+ */
+export function mergePresentationRendererRegistries<
+  TViewRenderer = unknown,
+  TControlRenderer = unknown,
+  TValueRenderer = unknown,
+>(
+  ...registries: readonly PresentationRendererRegistry<
+    TViewRenderer,
+    TControlRenderer,
+    TValueRenderer
+  >[]
+): PresentationRendererRegistry<TViewRenderer, TControlRenderer, TValueRenderer> {
+  return {
+    composites: {
+      byComponentRole: mergeRecord(
+        registries.map((registry) => registry.composites?.byComponentRole),
+      ),
+      byComponentKey: mergeRecord(
+        registries.map((registry) => registry.composites?.byComponentKey),
+      ),
+      bySemanticRole: mergeRecord(
+        registries.map((registry) => registry.composites?.bySemanticRole),
+      ),
+      byViewKind: mergeRecord(
+        registries.map((registry) => registry.composites?.byViewKind),
+      ),
+      fallback: registries.reduce<TViewRenderer | undefined>(
+        (fallback, registry) => registry.composites?.fallback ?? fallback,
+        undefined,
+      ),
+    },
+    controls: mergeRecord(registries.map((registry) => registry.controls)),
+    values: mergeRecord(registries.map((registry) => registry.values)),
+  }
+}
+
+/**
+ * Strategy that selected a renderer for a presentation view.
+ */
+export type PresentationViewRendererResolutionSource =
+  | 'component-key'
+  | 'component-role'
+  | 'fallback'
+  | 'semantic-role'
+  | 'view-kind'
+
+/**
+ * Result of resolving a concrete renderer for a semantic presentation view.
+ */
+export interface PresentationViewRendererResolution<TRenderer = unknown> {
+  /** Component key resolved from target bindings, when one matched. */
+  readonly componentKey: string | null
+
+  /** Component role resolved from target bindings, when one matched. */
+  readonly componentRole: string | null
+
+  /** Renderer selected from the registry, or null when no renderer matched. */
+  readonly renderer: TRenderer | null
+
+  /** Resolution strategy that selected the renderer, or null when unresolved. */
+  readonly resolutionSource: PresentationViewRendererResolutionSource | null
+
+  /** Semantic role derived from the view definition and available to diagnostics. */
+  readonly semanticRole: string
+}
+
+export interface ResolvePresentationViewRendererOptions<
+  TRenderer,
+  TModule extends PresentationRendererBindingModuleProjection =
+    PresentationRendererBindingModuleProjection,
+> {
+  readonly componentSet?: string | null
+  readonly module: TModule
+  readonly registry: PresentationRendererRegistry<TRenderer>
+  readonly routeId?: string | null
+  readonly targetKind?: PresentationEnumDiscriminator | null
+  readonly view: ViewDefinition
+}
+
+/**
+ * Resolves the renderer for a semantic view by consulting semantic role and
+ * view kind first. Component bindings remain available as an explicit escape
+ * hatch for views that cannot yet be interpreted from the IR shape alone.
+ */
+export function resolvePresentationViewRenderer<
+  TRenderer,
+  TModule extends PresentationRendererBindingModuleProjection =
+    PresentationRendererBindingModuleProjection,
+>({
+  componentSet,
+  module,
+  registry,
+  routeId,
+  targetKind,
+  view,
+}: ResolvePresentationViewRendererOptions<
+  TRenderer,
+  TModule
+>): PresentationViewRendererResolution<TRenderer> {
+  const componentBinding = resolvePresentationComponentBinding(module, {
+    bindingKind: createPresentationEnumDiscriminator(
+      presentationBindingKinds,
+      'viewComponent',
+      'ViewComponent',
+    ),
+    componentSet,
+    id: view.Id,
+    routeId,
+    targetKind,
+  })
+  const componentKey = componentBinding.componentKey
+  const componentRole = componentBinding.componentRole
+  const composites = registry.composites
+  const semanticRole = getPresentationViewSemanticRole(view)
+
+  const semanticRoleRenderer = composites?.bySemanticRole?.[semanticRole]
+  if (semanticRoleRenderer !== undefined && semanticRoleRenderer !== null) {
+    return {
+      componentKey,
+      componentRole,
+      renderer: semanticRoleRenderer,
+      resolutionSource: 'semantic-role',
+      semanticRole,
+    }
+  }
+
+  const viewKindRenderer = composites?.byViewKind?.[String(view.Kind)]
+  if (viewKindRenderer !== undefined && viewKindRenderer !== null) {
+    return {
+      componentKey,
+      componentRole,
+      renderer: viewKindRenderer,
+      resolutionSource: 'view-kind',
+      semanticRole,
+    }
+  }
+
+  if (componentRole) {
+    const renderer = composites?.byComponentRole?.[componentRole]
+    if (renderer !== undefined && renderer !== null) {
+      return {
+        componentKey,
+        componentRole,
+        renderer,
+        resolutionSource: 'component-role',
+        semanticRole,
+      }
+    }
+  }
+
+  if (componentKey) {
+    const renderer = composites?.byComponentKey?.[componentKey]
+    if (renderer !== undefined && renderer !== null) {
+      return {
+        componentKey,
+        componentRole,
+        renderer,
+        resolutionSource: 'component-key',
+        semanticRole,
+      }
+    }
+  }
+
+  if (composites?.fallback !== undefined && composites.fallback !== null) {
+    return {
+      componentKey,
+      componentRole,
+      renderer: composites.fallback,
+      resolutionSource: 'fallback',
+      semanticRole,
+    }
+  }
+
+  return {
+    componentKey,
+    componentRole,
+    renderer: null,
+    resolutionSource: null,
+    semanticRole,
+  }
+}
+
+function mergeRecord<TValue>(
+  records: readonly (Readonly<Record<string, TValue>> | undefined)[],
+) {
+  const merged: Record<string, TValue> = {}
+  for (const record of records) {
+    if (record) {
+      Object.assign(merged, record)
+    }
+  }
+
+  return merged
+}