@cohesivesystems/presentation-react 0.1.0-alpha.1

package/src/projected-document-workspace-projection-renderer-diagnostics.ts

@@ -0,0 +1,342 @@
+import type {
+  PresentationModuleDefinition,
+} from '@cohesivesystems/presentation-core'
+import type {
+  DocumentWorkspaceProjectionRendererRegistry,
+  DocumentWorkspaceProjectionRendererResolution,
+  DocumentWorkspaceRuntimeSnapshot,
+} from './document-workspace-runtime'
+import {
+  resolveDocumentWorkspaceProjectionCapability,
+  resolveDocumentWorkspaceProjectionRenderer,
+} from './document-workspace-runtime'
+import type {
+  PresentationProjectionDiagnostic,
+} from '@cohesivesystems/presentation-core'
+import {
+  createPresentationEnumDiscriminator,
+  matchesPresentationEnum,
+} from '@cohesivesystems/presentation-core'
+import {
+  coordinationActionKinds,
+  coordinationTriggerKinds,
+} from '@cohesivesystems/presentation-contracts'
+
+export interface ProjectDocumentWorkspaceProjectionRendererDiagnosticsOptions<
+  TContext,
+  TComponentSystem = unknown,
+  TDesignSystem = unknown,
+> {
+  readonly componentSet?: string | null
+  readonly module: PresentationModuleDefinition | null
+  readonly projectionRenderers: DocumentWorkspaceProjectionRendererRegistry<
+    TContext,
+    TComponentSystem,
+    TDesignSystem
+  >
+  readonly runtime: DocumentWorkspaceRuntimeSnapshot
+  readonly sourceId?: string
+}
+
+/**
+ * Reports projection renderer coverage for the document views exposed by the
+ * active workspace runtime. The same semantic resolver used for rendering is
+ * used here so the developer toolbar reports stale component bindings and
+ * unhandled IR projection semantics as actionable frontend TODOs.
+ */
+export function projectDocumentWorkspaceProjectionRendererDiagnostics<
+  TContext,
+  TComponentSystem = unknown,
+  TDesignSystem = unknown,
+>({
+  componentSet,
+  module,
+  projectionRenderers,
+  runtime,
+  sourceId = 'document-workspace-projection-renderers',
+}: ProjectDocumentWorkspaceProjectionRendererDiagnosticsOptions<
+  TContext,
+  TComponentSystem,
+  TDesignSystem
+>): readonly PresentationProjectionDiagnostic[] {
+  return [
+    ...runtime.projectionViewIds.flatMap((viewId) =>
+      projectProjectionRendererDiagnostics({
+        componentSet,
+        module,
+        projectionRenderers,
+        runtime,
+        sourceId,
+        viewId,
+      }),
+    ),
+    ...projectProjectionCoordinationDiagnostics({
+      componentSet,
+      module,
+      projectionRenderers,
+      runtime,
+      sourceId,
+    }),
+  ]
+}
+
+function projectProjectionRendererDiagnostics<
+  TContext,
+  TComponentSystem = unknown,
+  TDesignSystem = unknown,
+>({
+  componentSet,
+  module,
+  projectionRenderers,
+  runtime,
+  sourceId,
+  viewId,
+}: ProjectDocumentWorkspaceProjectionRendererDiagnosticsOptions<
+  TContext,
+  TComponentSystem,
+  TDesignSystem
+> & {
+  readonly viewId: string
+}) {
+  const resolution = resolveDocumentWorkspaceProjectionRenderer({
+    componentSet,
+    module,
+    registry: projectionRenderers,
+    runtime,
+    viewId,
+  })
+  const projection = resolution.projection
+
+  if (!projection) {
+    return [
+      {
+        details: { viewId },
+        id: `document-projection.${viewId}.missing-projection`,
+        message:
+          `Document workspace view '${viewId}' does not resolve to a declared ` +
+          'document projection.',
+        severity: 'warning',
+        source: sourceId ?? 'document-workspace-projection-renderers',
+        subject: {
+          id: viewId,
+          kind: 'document-projection-view',
+        },
+      } satisfies PresentationProjectionDiagnostic,
+    ]
+  }
+
+  const diagnostics: PresentationProjectionDiagnostic[] = []
+  if (!resolution.renderer) {
+    diagnostics.push({
+      details: createProjectionRendererDiagnosticDetails(resolution, viewId),
+      id: `document-projection.${projection.Id}.missing-renderer`,
+      message: `Document projection '${projection.Name}' has no frontend renderer binding.`,
+      severity: 'warning',
+      source: sourceId ?? 'document-workspace-projection-renderers',
+      subject: {
+        id: projection.Id,
+        kind: 'document-projection',
+        name: projection.Name,
+      },
+    })
+  }
+
+  if (resolution.renderer && isCompatibilityRendererSource(resolution.resolutionSource)) {
+    diagnostics.push({
+      details: createProjectionRendererDiagnosticDetails(resolution, viewId),
+      id: `document-projection.${projection.Id}.semantic-renderer-fallback`,
+      category: resolution.componentRole ? 'unbound' : 'missing-binding',
+      interpretation: {
+        status: resolution.componentRole ? 'unbound' : 'locally-interpreted',
+        target: 'document-projection-component-role',
+      },
+      message: resolution.componentRole
+        ? `Document projection '${projection.Name}' declares component role ` +
+          `'${resolution.componentRole}', but rendering fell back to ` +
+          `'${resolution.resolutionSource}'.`
+        : `Document projection '${projection.Name}' rendered through ` +
+          `'${resolution.resolutionSource}' because it has no ProjectionRenderer ` +
+          'target component role binding.',
+      severity: 'warning',
+      source: sourceId ?? 'document-workspace-projection-renderers',
+      suggestedNextStep: resolution.componentRole
+        ? `Bind frontend component role '${resolution.componentRole}' in the document projection component pack.`
+        : 'Declare a ProjectionRenderer target binding with ComponentRole for this projection and bind that role in the frontend component pack.',
+      subject: {
+        id: projection.Id,
+        kind: 'document-projection',
+        name: projection.Name,
+      },
+    })
+  }
+
+  if (
+    resolution.renderer &&
+    resolution.componentKey &&
+    resolution.resolutionSource === 'component-key'
+  ) {
+    diagnostics.push({
+      category: 'escape-hatch',
+      details: createProjectionRendererDiagnosticDetails(resolution, viewId),
+      id: `document-projection.${projection.Id}.component-key-escape-hatch`,
+      interpretation: {
+        status: 'escape-hatch',
+        target: 'document-projection-component-key',
+      },
+      message:
+        `Document projection '${projection.Name}' rendered through concrete ` +
+        `component key '${resolution.componentKey}' as an escape hatch.`,
+      severity: 'warning',
+      source: sourceId ?? 'document-workspace-projection-renderers',
+      suggestedNextStep:
+        'Prefer ComponentRole for document projections and keep ComponentKey only for adapter-specific overrides.',
+      subject: {
+        id: projection.Id,
+        kind: 'document-projection',
+        name: projection.Name,
+      },
+    })
+  }
+
+  if (resolution.rendererKey) {
+    diagnostics.push({
+      category: 'escape-hatch',
+      details: createProjectionRendererDiagnosticDetails(resolution, viewId),
+      id: `document-projection.${projection.Id}.legacy-renderer-key`,
+      interpretation: {
+        status: 'escape-hatch',
+        target: 'document-projection-component-role',
+      },
+      message:
+        `Document projection '${projection.Name}' declares renderer key ` +
+        `'${resolution.rendererKey}'. Document projection dispatch now uses ` +
+        'ProjectionRenderer target component roles and semantic projection interpretation.',
+      severity: 'warning',
+      source: sourceId ?? 'document-workspace-projection-renderers',
+      suggestedNextStep:
+        'Replace the renderer key with a ProjectionRenderer target binding that declares ComponentRole.',
+      subject: {
+        id: projection.Id,
+        kind: 'document-projection',
+        name: projection.Name,
+      },
+    })
+  }
+
+  return diagnostics
+}
+
+function isCompatibilityRendererSource(
+  source: DocumentWorkspaceProjectionRendererResolution<
+    unknown,
+    unknown,
+    unknown
+  >['resolutionSource'],
+) {
+  return source === 'projection-kind' ||
+    source === 'semantic-reference-kind' ||
+    source === 'subject-kind'
+}
+
+function projectProjectionCoordinationDiagnostics<
+  TContext,
+  TComponentSystem = unknown,
+  TDesignSystem = unknown,
+>({
+  componentSet,
+  module,
+  projectionRenderers,
+  runtime,
+  sourceId = 'document-workspace-projection-renderers',
+}: ProjectDocumentWorkspaceProjectionRendererDiagnosticsOptions<
+  TContext,
+  TComponentSystem,
+  TDesignSystem
+>) {
+  const revealTargetProjectionIds = new Set(
+    runtime.documentProfile.Coordination
+      .filter((coordination) =>
+        matchesPresentationEnum(coordination.Trigger.Kind, selectionChangedTriggerKind) &&
+        matchesPresentationEnum(coordination.Action.Kind, revealSemanticSelectionActionKind),
+      )
+      .flatMap((coordination) => coordination.Action.TargetProjectionIds),
+  )
+
+  return [...revealTargetProjectionIds].flatMap((projectionId) => {
+    const projection = runtime.projections.find((candidate) => candidate.Id === projectionId)
+    if (!projection) {
+      return []
+    }
+
+    const hasRevealCapability = resolveDocumentWorkspaceProjectionCapability({
+      capability: 'revealSemanticSelection',
+      componentSet,
+      module,
+      projection,
+      registry: projectionRenderers,
+    })
+    if (hasRevealCapability) {
+      return []
+    }
+
+    return [
+      {
+        details: {
+          coordinationActionKind: 'RevealSemanticSelection',
+          projectionKind: projection.Kind,
+          semanticReferenceKind: projection.Coordinates?.SemanticReferenceKind ?? null,
+          subjectKind: projection.Subject.Kind,
+          viewId: projection.ViewId,
+        },
+        id: `document-projection.${projection.Id}.missing-reveal-semantic-selection`,
+        message:
+          `Document projection '${projection.Name}' is targeted by semantic ` +
+          'selection reveal coordination, but this frontend adapter has not ' +
+          'declared a reveal interpretation for it.',
+        severity: 'warning',
+        source: sourceId,
+        subject: {
+          id: projection.Id,
+          kind: 'document-projection',
+          name: projection.Name,
+        },
+      } satisfies PresentationProjectionDiagnostic,
+    ]
+  })
+}
+
+function createProjectionRendererDiagnosticDetails<
+  TContext,
+  TComponentSystem,
+  TDesignSystem,
+>(
+  resolution: DocumentWorkspaceProjectionRendererResolution<
+    TContext,
+    TComponentSystem,
+    TDesignSystem
+  >,
+  viewId: string,
+) {
+  return {
+    componentKey: resolution.componentKey,
+    componentRole: resolution.componentRole,
+    projectionKind: resolution.projection?.Kind ?? null,
+    rendererKey: resolution.rendererKey,
+    resolutionSource: resolution.resolutionSource,
+    semanticReferenceKind: resolution.projection?.Coordinates?.SemanticReferenceKind ?? null,
+    subjectKind: resolution.projection?.Subject.Kind ?? null,
+    viewId,
+  }
+}
+
+const selectionChangedTriggerKind = createPresentationEnumDiscriminator(
+  coordinationTriggerKinds,
+  'selectionChanged',
+  'SelectionChanged',
+)
+
+const revealSemanticSelectionActionKind = createPresentationEnumDiscriminator(
+  coordinationActionKinds,
+  'revealSemanticSelection',
+  'RevealSemanticSelection',
+)

package/src/projected-document-workspace-runtime-binding-diagnostics.ts

@@ -0,0 +1,208 @@
+import type {
+  PresentationModuleDefinition,
+} from '@cohesivesystems/presentation-core'
+import {
+  createPresentationProjectionDiagnostic,
+  type PresentationProjectionDiagnostic,
+} from '@cohesivesystems/presentation-core'
+import {
+  createPresentationEnumDiscriminator,
+  findPresentationComponentBinding,
+} from '@cohesivesystems/presentation-core'
+import type {
+  DocumentWorkspaceRuntimeSnapshot,
+} from './document-workspace-runtime'
+import {
+  workspaceRuntimeComponentRoles,
+} from '@cohesivesystems/presentation-contracts'
+import {
+  presentationBindingKinds,
+  presentationTargetKinds,
+} from '@cohesivesystems/presentation-contracts'
+
+export interface ProjectDocumentWorkspaceRuntimeBindingDiagnosticsOptions {
+  readonly componentSet?: string | null
+  readonly module: PresentationModuleDefinition | null
+  readonly runtime: DocumentWorkspaceRuntimeSnapshot
+  readonly sourceId?: string
+  readonly supportedComponentRoles?: readonly string[]
+}
+
+const defaultSupportedDocumentWorkspaceRuntimeRoles = [
+  workspaceRuntimeComponentRoles.documentWorkspace,
+] as const
+
+/**
+ * Reports whether the backend WorkspaceRuntime target binding is projected as
+ * a semantic component role that this frontend document workspace host
+ * interprets. The host still mounts the runtime locally, but this diagnostic
+ * keeps the target binding honest and prevents concrete ComponentKey bindings
+ * from quietly lingering.
+ */
+export function projectDocumentWorkspaceRuntimeBindingDiagnostics({
+  componentSet,
+  module,
+  runtime,
+  sourceId = 'document-workspace-runtime-binding',
+  supportedComponentRoles = defaultSupportedDocumentWorkspaceRuntimeRoles,
+}: ProjectDocumentWorkspaceRuntimeBindingDiagnosticsOptions): readonly PresentationProjectionDiagnostic[] {
+  if (!module) {
+    return []
+  }
+
+  const binding = findPresentationComponentBinding(module, {
+    bindingKind: createPresentationEnumDiscriminator(
+      presentationBindingKinds,
+      'workspaceRuntime',
+      'WorkspaceRuntime',
+    ),
+    componentSet,
+    id: runtime.workspace.Id,
+    targetKind: createPresentationEnumDiscriminator(
+      presentationTargetKinds,
+      'react',
+      'React',
+    ),
+  })
+  const componentKey = binding?.ComponentKey ?? null
+  const componentRole = binding?.ComponentRole ?? null
+  const supportedRoleSet = new Set(supportedComponentRoles)
+  const diagnostics: PresentationProjectionDiagnostic[] = []
+
+  if (!binding) {
+    diagnostics.push(
+      createWorkspaceRuntimeDiagnostic({
+        category: 'missing-binding',
+        componentKey,
+        componentRole,
+        idSuffix: 'missing-binding',
+        message:
+          `Document workspace '${runtime.workspace.Id}' has no WorkspaceRuntime ` +
+          'target binding for the active frontend target.',
+        severity: 'warning',
+        sourceId,
+        status: 'unbound',
+        suggestedNextStep:
+          'Declare a WorkspaceRuntime target binding with ComponentRole for this document workspace.',
+        runtime,
+      }),
+    )
+    return diagnostics
+  }
+
+  if (componentKey) {
+    diagnostics.push(
+      createWorkspaceRuntimeDiagnostic({
+        category: 'escape-hatch',
+        componentKey,
+        componentRole,
+        idSuffix: 'component-key-escape-hatch',
+        message:
+          `Document workspace '${runtime.workspace.Id}' declares concrete ` +
+          `workspace runtime component key '${componentKey}'.`,
+        severity: 'warning',
+        sourceId,
+        status: 'escape-hatch',
+        suggestedNextStep:
+          'Use WorkspaceRuntime ComponentRole for document workspace runtimes and reserve ComponentKey for adapter-specific overrides.',
+        runtime,
+      }),
+    )
+  }
+
+  if (!componentRole) {
+    diagnostics.push(
+      createWorkspaceRuntimeDiagnostic({
+        category: 'missing-binding',
+        componentKey,
+        componentRole,
+        idSuffix: 'missing-component-role',
+        message:
+          `Document workspace '${runtime.workspace.Id}' WorkspaceRuntime binding ` +
+          'does not declare a component role.',
+        severity: 'warning',
+        sourceId,
+        status: 'unbound',
+        suggestedNextStep:
+          `Set ComponentRole to '${workspaceRuntimeComponentRoles.documentWorkspace}'.`,
+        runtime,
+      }),
+    )
+    return diagnostics
+  }
+
+  const isSupportedRole = supportedRoleSet.has(componentRole)
+
+  diagnostics.push(
+    createWorkspaceRuntimeDiagnostic({
+      category: isSupportedRole ? 'local-interpretation' : 'missing-binding',
+      componentKey,
+      componentRole,
+      idSuffix: 'component-role-coverage',
+      message: isSupportedRole
+        ? `Document workspace '${runtime.workspace.Id}' WorkspaceRuntime role ` +
+          `'${componentRole}' is interpreted by the local document workspace host.`
+        : `Document workspace '${runtime.workspace.Id}' WorkspaceRuntime role ` +
+          `'${componentRole}' is not interpreted by the local document workspace host.`,
+      severity: isSupportedRole ? 'info' : 'warning',
+      sourceId,
+      status: isSupportedRole ? 'locally-interpreted' : 'unbound',
+      suggestedNextStep: isSupportedRole
+        ? undefined
+        : 'Bind this WorkspaceRuntime component role in the frontend document workspace host adapter.',
+      runtime,
+    }),
+  )
+
+  return diagnostics
+}
+
+function createWorkspaceRuntimeDiagnostic({
+  category,
+  componentKey,
+  componentRole,
+  idSuffix,
+  message,
+  runtime,
+  severity,
+  sourceId,
+  status,
+  suggestedNextStep,
+}: {
+  readonly category: PresentationProjectionDiagnostic['category']
+  readonly componentKey: string | null
+  readonly componentRole: string | null
+  readonly idSuffix: string
+  readonly message: string
+  readonly runtime: DocumentWorkspaceRuntimeSnapshot
+  readonly severity: PresentationProjectionDiagnostic['severity']
+  readonly sourceId: string
+  readonly status: NonNullable<PresentationProjectionDiagnostic['interpretation']>['status']
+  readonly suggestedNextStep?: string
+}) {
+  return createPresentationProjectionDiagnostic({
+    category,
+    details: {
+      componentKey,
+      componentRole,
+      documentProfileId: runtime.documentProfile.Id,
+      pageViewId: runtime.pageView.Id,
+      workspaceId: runtime.workspace.Id,
+      workspaceViewId: runtime.workspaceView.Id,
+    },
+    id: `document-workspace-runtime.${runtime.workspace.Id}.${idSuffix}`,
+    interpretation: {
+      status,
+      target: 'workspace-runtime-component-role',
+    },
+    message,
+    severity,
+    source: sourceId,
+    subject: {
+      id: runtime.workspace.Id,
+      kind: 'document-workspace-runtime',
+      name: runtime.workspace.Name,
+    },
+    suggestedNextStep,
+  })
+}

package/src/projected-navigation-provider.tsx

@@ -0,0 +1,104 @@
+import { useCallback, useMemo, type Context, type PropsWithChildren } from 'react'
+import { useNavigate, useResolvedPath } from 'react-router'
+
+import {
+  createNavigationHref,
+  type NavigationDefinitionProjection,
+  type PresentationNavigationRuntime,
+} from '@cohesivesystems/presentation-core'
+import {
+  PresentationNavigationRuntimeContext,
+} from './navigation-runtime-context'
+
+export interface ProjectedNavigationContextValue<TNavigation extends NavigationDefinitionProjection = NavigationDefinitionProjection> extends PresentationNavigationRuntime {
+  readonly navigation: TNavigation | null
+}
+
+export interface ProjectedNavigationProviderProps<
+  TNavigation extends NavigationDefinitionProjection,
+> extends PropsWithChildren {
+  readonly context?: Context<ProjectedNavigationContextValue<TNavigation>>
+  readonly navigation: TNavigation | null
+}
+
+/**
+ * Generic React binding for semantic navigation definitions. App-specific
+ * navigation contexts can be layered on top, but href creation and route
+ * execution stay owned by the presentation projection runtime.
+ */
+export function ProjectedNavigationProvider<
+  TNavigation extends NavigationDefinitionProjection,
+>({
+  children,
+  context,
+  navigation,
+}: ProjectedNavigationProviderProps<TNavigation>) {
+  const navigate = useNavigate()
+  const rootPath = useResolvedPath('/')
+  const createHref = useCallback<ProjectedNavigationContextValue['createHref']>(
+    (routeId, parameters) =>
+      navigation ? createNavigationHref(navigation, routeId, parameters) : null,
+    [navigation],
+  )
+  const navigateHref = useCallback<ProjectedNavigationContextValue['navigateHref']>(
+    (href) => {
+      if (href.length > 0) {
+        void navigate(toRootRelativeHref(href, rootPath.pathname), {
+          flushSync: true,
+          relative: 'path',
+        })
+      }
+    },
+    [navigate, rootPath.pathname],
+  )
+  const navigateRoute = useCallback<ProjectedNavigationContextValue['navigateRoute']>(
+    (routeId, parameters) => {
+      const href = createHref(routeId, parameters)
+      if (href) {
+        navigateHref(href)
+      }
+    },
+    [createHref, navigateHref],
+  )
+  const runtime = useMemo<PresentationNavigationRuntime>(
+    () => ({
+      createHref,
+      navigateHref,
+      navigateRoute,
+    }),
+    [createHref, navigateHref, navigateRoute],
+  )
+  const contextValue = useMemo<ProjectedNavigationContextValue<TNavigation>>(
+    () => ({
+      ...runtime,
+      navigation,
+    }),
+    [navigation, runtime],
+  )
+  const ApplicationNavigationContext = context
+
+  return (
+    <PresentationNavigationRuntimeContext.Provider value={runtime}>
+      {ApplicationNavigationContext ? (
+        <ApplicationNavigationContext.Provider value={contextValue}>
+          {children}
+        </ApplicationNavigationContext.Provider>
+      ) : (
+        children
+      )}
+    </PresentationNavigationRuntimeContext.Provider>
+  )
+}
+
+function toRootRelativeHref(href: string, rootPathname: string) {
+  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(href) || href.startsWith('//')) {
+    return href
+  }
+
+  if (href.startsWith('/')) {
+    return href
+  }
+
+  const root = rootPathname === '/' ? '' : rootPathname.replace(/\/+$/g, '')
+  return `${root}/${href.replace(/^\/+/g, '')}`
+}

package/src/projected-presentation-flow-host.tsx

@@ -0,0 +1,46 @@
+import type { ReactNode } from 'react'
+
+import type {
+  FlowDefinition,
+  FlowStateDefinition,
+  ViewDefinition,
+} from '@cohesivesystems/presentation-core'
+import type {
+  PresentationFlowInstance,
+  PresentationFlowRuntimeSnapshot,
+} from './presentation-flow-runtime'
+
+export interface ProjectedPresentationFlowHostProps {
+  readonly fallback?: ReactNode
+  readonly renderView: (context: ProjectedPresentationFlowViewRenderContext) => ReactNode
+  readonly runtime: PresentationFlowRuntimeSnapshot
+}
+
+export interface ProjectedPresentationFlowViewRenderContext {
+  readonly flow: FlowDefinition
+  readonly instance: PresentationFlowInstance
+  readonly state: FlowStateDefinition
+  readonly view: ViewDefinition
+}
+
+export function ProjectedPresentationFlowHost({
+  fallback = null,
+  renderView,
+  runtime,
+}: ProjectedPresentationFlowHostProps) {
+  const { activeFlow, activeInstance, activeState, activeView } = runtime
+  if (!activeFlow || !activeInstance || !activeState || !activeView) {
+    return <>{fallback}</>
+  }
+
+  return (
+    <>
+      {renderView({
+        flow: activeFlow,
+        instance: activeInstance,
+        state: activeState,
+        view: activeView,
+      })}
+    </>
+  )
+}