@cohesivesystems/presentation-react 0.1.0-alpha.1

package/src/page-host-projection.ts

@@ -0,0 +1,356 @@
+import type { ReactNode } from 'react'
+
+import type {
+  NavigationDefinitionProjection,
+  NavigationTarget,
+} from '@cohesivesystems/presentation-core'
+import type {
+  NavigationRouteDefinition,
+  PageHostDefinition,
+} from '@cohesivesystems/presentation-contracts'
+
+/**
+ * Route parameter values resolved by the frontend router for a projected
+ * navigation route. Values are strings because this sits at the router binding
+ * boundary; semantic conversion belongs in the page-host or data-source layer.
+ */
+export type RouteParameterValues = Readonly<Record<string, string | undefined>>
+
+/**
+ * Complete rendering context for a resolved page host. Page-host renderers are
+ * the adapting boundary between semantic navigation/page-host IR and concrete
+ * React route components.
+ *
+ * @typeParam TModule - Presentation module shape available to the renderer.
+ * @typeParam TNavigation - Navigation graph shape used to resolve the route.
+ * @typeParam TRoute - Concrete navigation route type.
+ * @typeParam TPageHost - Concrete page-host type mounted by the route.
+ * @typeParam TProjectionContext - App-specific runtime context supplied by the navigation projection.
+ */
+export interface PageHostRenderContext<
+  TModule,
+  TNavigation extends NavigationDefinitionProjection<TRoute, TPageHost>,
+  TRoute extends NavigationRouteDefinition,
+  TPageHost extends PageHostDefinition,
+  TProjectionContext,
+> {
+  /** App-specific projection context carried through navigation rendering. */
+  readonly context: TProjectionContext
+
+  /** Presentation module that owns views, targets, workspaces, and bindings. */
+  readonly module: TModule
+
+  /** Navigation graph that produced the current route/page-host pairing. */
+  readonly navigation: TNavigation
+
+  /** Resolved semantic target for the active route. */
+  readonly navigationTarget: NavigationTarget<TRoute, TPageHost>
+
+  /** Page host mounted by the active route. */
+  readonly pageHost: TPageHost
+
+  /** Raw route parameters captured by the frontend router. */
+  readonly parameters: RouteParameterValues
+
+  /** Active route definition from the navigation graph. */
+  readonly route: TRoute
+}
+
+/**
+ * React renderer for a resolved page host.
+ */
+export type PageHostComponentRenderer<
+  TModule,
+  TNavigation extends NavigationDefinitionProjection<TRoute, TPageHost>,
+  TRoute extends NavigationRouteDefinition,
+  TPageHost extends PageHostDefinition,
+  TProjectionContext,
+> = (
+  context: PageHostRenderContext<
+    TModule,
+    TNavigation,
+    TRoute,
+    TPageHost,
+    TProjectionContext
+  >,
+) => ReactNode
+
+/**
+ * Registry of concrete page-host renderers keyed by adapter component key.
+ * The semantic navigation runtime resolves which component key applies; this
+ * registry supplies the React implementation for that key.
+ */
+export type PageHostComponentRegistry<
+  TComponentKey extends string,
+  TModule,
+  TNavigation extends NavigationDefinitionProjection<TRoute, TPageHost>,
+  TRoute extends NavigationRouteDefinition,
+  TPageHost extends PageHostDefinition,
+  TProjectionContext,
+> = Readonly<
+  Partial<
+    Record<
+      TComponentKey,
+      PageHostComponentRenderer<
+        TModule,
+        TNavigation,
+        TRoute,
+        TPageHost,
+        TProjectionContext
+      >
+    >
+  >
+>
+
+/**
+ * Convenience registry type for apps that use the standard generated
+ * navigation, route, and page-host shapes.
+ */
+export type SimplePageHostComponentRegistry<
+  TComponentKey extends string,
+  TModule,
+  TProjectionContext,
+> = PageHostComponentRegistry<
+  TComponentKey,
+  TModule,
+  NavigationDefinitionProjection,
+  NavigationRouteDefinition,
+  PageHostDefinition,
+  TProjectionContext
+>
+
+/**
+ * Convenience render-context type for apps that use the standard generated
+ * navigation, route, and page-host shapes.
+ */
+export type SimplePageHostRenderContext<
+  TModule,
+  TProjectionContext,
+> = PageHostRenderContext<
+  TModule,
+  NavigationDefinitionProjection,
+  NavigationRouteDefinition,
+  PageHostDefinition,
+  TProjectionContext
+>
+
+/**
+ * Convenience unknown-renderer type for apps that use the standard generated
+ * navigation, route, and page-host shapes.
+ */
+export type SimpleUnknownPageHostRenderer<
+  TModule,
+  TProjectionContext,
+> = UnknownPageHostRenderer<
+  TModule,
+  NavigationDefinitionProjection,
+  NavigationRouteDefinition,
+  PageHostDefinition,
+  TProjectionContext
+>
+
+/**
+ * Context passed when a route cannot be projected to a concrete page-host
+ * renderer. Unknown renderers should produce diagnostics, not throw, so route
+ * and binding problems remain visible inside the app shell.
+ */
+export interface UnknownPageHostRenderContext<
+  TModule,
+  TNavigation extends NavigationDefinitionProjection<TRoute, TPageHost>,
+  TRoute extends NavigationRouteDefinition,
+  TPageHost extends PageHostDefinition,
+  TProjectionContext,
+> {
+  /** Component key that failed to resolve, when one was present. */
+  readonly componentKey?: string | null
+
+  /** App-specific projection context carried through navigation rendering. */
+  readonly context: TProjectionContext
+
+  /** Presentation module available during route projection. */
+  readonly module: TModule
+
+  /** Navigation graph being projected. */
+  readonly navigation: TNavigation
+
+  /** Resolved navigation target, or null when no route matched. */
+  readonly navigationTarget: NavigationTarget<TRoute, TPageHost> | null
+
+  /** Page host selected by the route, or null when the route references none. */
+  readonly pageHost: TPageHost | null
+
+  /** Raw route parameters captured by the frontend router. */
+  readonly parameters: RouteParameterValues
+
+  /** Failure mode that prevented a page host from rendering. */
+  readonly reason:
+    | 'missing-page-host'
+    | 'missing-component-binding'
+    | 'unknown-component-key'
+    | 'unmatched-route'
+
+  /** Active route, or null when no route matched the current URL. */
+  readonly route: TRoute | null
+}
+
+/**
+ * Renderer for page-host projection failures.
+ */
+export type UnknownPageHostRenderer<
+  TModule,
+  TNavigation extends NavigationDefinitionProjection<TRoute, TPageHost>,
+  TRoute extends NavigationRouteDefinition,
+  TPageHost extends PageHostDefinition,
+  TProjectionContext,
+> = (
+  context: UnknownPageHostRenderContext<
+    TModule,
+    TNavigation,
+    TRoute,
+    TPageHost,
+    TProjectionContext
+  >,
+) => ReactNode
+
+/**
+ * Inputs required to render a page host after router matching and semantic
+ * navigation resolution have already occurred.
+ */
+export interface RenderPageHostOptions<
+  TComponentKey extends string,
+  TModule,
+  TNavigation extends NavigationDefinitionProjection<TRoute, TPageHost>,
+  TRoute extends NavigationRouteDefinition,
+  TPageHost extends PageHostDefinition,
+  TProjectionContext,
+> {
+  /** Concrete component key resolved from target bindings or caller policy. */
+  readonly componentKey?: string | null
+
+  /** Registry that maps component keys to React page-host renderers. */
+  readonly componentRegistry: PageHostComponentRegistry<
+    TComponentKey,
+    TModule,
+    TNavigation,
+    TRoute,
+    TPageHost,
+    TProjectionContext
+  >
+
+  /** App-specific projection context carried through navigation rendering. */
+  readonly context: TProjectionContext
+
+  /** Presentation module available during route projection. */
+  readonly module: TModule
+
+  /** Navigation graph being projected. */
+  readonly navigation: TNavigation
+
+  /** Resolved semantic target for the active route. */
+  readonly navigationTarget: NavigationTarget<TRoute, TPageHost>
+
+  /** Page host selected by the route. Null is rendered through diagnostics. */
+  readonly pageHost: TPageHost | null
+
+  /** Raw route parameters captured by the frontend router. */
+  readonly parameters: RouteParameterValues
+
+  /** Diagnostic renderer used when the page host cannot be projected. */
+  readonly renderUnknownPageHost: UnknownPageHostRenderer<
+    TModule,
+    TNavigation,
+    TRoute,
+    TPageHost,
+    TProjectionContext
+  >
+
+  /** Active route definition from the navigation graph. */
+  readonly route: TRoute
+}
+
+/**
+ * Projects a resolved semantic page host into a concrete React renderer.
+ *
+ * The function does only three things: validate that a page host exists,
+ * validate that a component key exists, and look up the corresponding renderer.
+ * Higher-level code owns route matching and component-key resolution; unknown
+ * cases are delegated to `renderUnknownPageHost` so projection failures remain
+ * visible and recoverable.
+ */
+export function renderPageHost<
+  TComponentKey extends string,
+  TModule,
+  TNavigation extends NavigationDefinitionProjection<TRoute, TPageHost>,
+  TRoute extends NavigationRouteDefinition,
+  TPageHost extends PageHostDefinition,
+  TProjectionContext,
+>({
+  componentKey,
+  componentRegistry,
+  context,
+  module,
+  navigation,
+  navigationTarget,
+  pageHost,
+  parameters,
+  renderUnknownPageHost,
+  route,
+}: RenderPageHostOptions<
+  TComponentKey,
+  TModule,
+  TNavigation,
+  TRoute,
+  TPageHost,
+  TProjectionContext
+>) {
+  if (!pageHost) {
+    return renderUnknownPageHost({
+      context,
+      module,
+      navigation,
+      navigationTarget,
+      pageHost,
+      parameters,
+      reason: 'missing-page-host',
+      route,
+    })
+  }
+
+  if (!componentKey) {
+    return renderUnknownPageHost({
+      context,
+      module,
+      navigation,
+      navigationTarget,
+      pageHost,
+      parameters,
+      reason: 'missing-component-binding',
+      route,
+    })
+  }
+
+  const renderer = componentRegistry[componentKey as TComponentKey]
+  if (!renderer) {
+    return renderUnknownPageHost({
+      componentKey,
+      context,
+      module,
+      navigation,
+      navigationTarget,
+      pageHost,
+      parameters,
+      reason: 'unknown-component-key',
+      route,
+    })
+  }
+
+  return renderer({
+    context,
+    module,
+    navigation,
+    navigationTarget,
+    pageHost,
+    parameters,
+    route,
+  })
+}

package/src/page-host-renderer-registry.tsx

@@ -0,0 +1,353 @@
+import type { ComponentType } from 'react'
+
+import {
+  presentationTargetKinds,
+  type NavigationRouteDefinition,
+  type PageHostDefinition,
+} from '@cohesivesystems/presentation-contracts'
+import {
+  createPresentationEnumDiscriminator,
+  presentationPageHostComponentRoles,
+  resolveDefaultPresentationPageHostComponentRole,
+  resolvePageHostRenderer as resolveCorePageHostRenderer,
+  type NavigationDefinitionProjection,
+  type PageHostRendererRegistry as CorePageHostRendererRegistry,
+  type PageHostRendererResolution as CorePageHostRendererResolution,
+  type PageHostRendererResolutionSource,
+  type PageHostTargetBindingSource,
+  type PresentationPageHostRendererModuleProjection,
+} from '@cohesivesystems/presentation-core'
+import type {
+  PageHostComponentRenderer,
+  PageHostRenderContext,
+} from './page-host-projection'
+import type {
+  ProjectedNavigationTargetRenderContext,
+  ProjectedNavigationTargetRenderer,
+} from './react-router-binding'
+
+export {
+  presentationPageHostComponentRoles,
+  resolveDefaultPresentationPageHostComponentRole,
+}
+
+export type {
+  PageHostRendererResolutionSource,
+  PageHostTargetBindingSource,
+  PresentationPageHostRendererModuleProjection,
+}
+
+/**
+ * Renders a semantic page host after navigation has resolved the target route.
+ * These renderers sit at the projection boundary: they choose React components
+ * for page-host semantics without letting the router own application meaning.
+ */
+export type PageHostRenderer<
+  TModule,
+  TNavigation extends NavigationDefinitionProjection<TRoute, TPageHost>,
+  TRoute extends NavigationRouteDefinition,
+  TPageHost extends PageHostDefinition,
+  TProjectionContext,
+> = PageHostComponentRenderer<
+  TModule,
+  TNavigation,
+  TRoute,
+  TPageHost,
+  TProjectionContext
+>
+
+/**
+ * React component type that consumes the fully resolved page-host context.
+ * Use `createPageHostComponentRenderer` to adapt one of these into a registry
+ * entry.
+ */
+export type PageHostRendererComponent<
+  TModule,
+  TNavigation extends NavigationDefinitionProjection<TRoute, TPageHost>,
+  TRoute extends NavigationRouteDefinition,
+  TPageHost extends PageHostDefinition,
+  TProjectionContext,
+> = ComponentType<
+  PageHostRenderContext<
+    TModule,
+    TNavigation,
+    TRoute,
+    TPageHost,
+    TProjectionContext
+  >
+>
+
+/**
+ * Adapts a React component that consumes the resolved page-host context into a
+ * registry renderer. This keeps the registry declarative while allowing route
+ * hosts to remain ordinary components at the projection boundary.
+ */
+export function createPageHostComponentRenderer<
+  TModule,
+  TNavigation extends NavigationDefinitionProjection<TRoute, TPageHost>,
+  TRoute extends NavigationRouteDefinition,
+  TPageHost extends PageHostDefinition,
+  TProjectionContext,
+>(
+  Component: PageHostRendererComponent<
+    TModule,
+    TNavigation,
+    TRoute,
+    TPageHost,
+    TProjectionContext
+  >,
+): PageHostRenderer<
+  TModule,
+  TNavigation,
+  TRoute,
+  TPageHost,
+  TProjectionContext
+> {
+  return function renderPageHostWithComponent(context) {
+    return <Component {...context} />
+  }
+}
+
+export type PageHostRendererRegistry<
+  TModule,
+  TNavigation extends NavigationDefinitionProjection<TRoute, TPageHost>,
+  TRoute extends NavigationRouteDefinition,
+  TPageHost extends PageHostDefinition,
+  TProjectionContext,
+> = CorePageHostRendererRegistry<
+  PageHostRenderer<
+    TModule,
+    TNavigation,
+    TRoute,
+    TPageHost,
+    TProjectionContext
+  >
+>
+
+/**
+ * Convenience registry type for apps that use the standard generated
+ * navigation, route, and page-host shapes.
+ */
+export type SimplePageHostRendererRegistry<
+  TModule,
+  TProjectionContext,
+> = PageHostRendererRegistry<
+  TModule,
+  NavigationDefinitionProjection,
+  NavigationRouteDefinition,
+  PageHostDefinition,
+  TProjectionContext
+>
+
+export type PageHostRendererResolution<
+  TModule,
+  TNavigation extends NavigationDefinitionProjection<TRoute, TPageHost>,
+  TRoute extends NavigationRouteDefinition,
+  TPageHost extends PageHostDefinition,
+  TProjectionContext,
+> = CorePageHostRendererResolution<
+  PageHostRenderer<
+    TModule,
+    TNavigation,
+    TRoute,
+    TPageHost,
+    TProjectionContext
+  >
+>
+
+/**
+ * Options for adapting a page-host registry into a navigation-target renderer
+ * that can be passed to router projection.
+ */
+export interface CreatePageHostTargetRendererOptions<
+  TComponentKey extends string,
+  TModule extends PresentationPageHostRendererModuleProjection,
+  TNavigation extends NavigationDefinitionProjection<TRoute, TPageHost>,
+  TRoute extends NavigationRouteDefinition,
+  TPageHost extends PageHostDefinition,
+  TProjectionContext,
+> {
+  /** Registry used to resolve semantic page hosts to concrete renderers. */
+  readonly registry: PageHostRendererRegistry<
+    TModule,
+    TNavigation,
+    TRoute,
+    TPageHost,
+    TProjectionContext
+  >
+
+  /** Adapter component set to use when reading target bindings. */
+  readonly componentSet?: string | null
+
+  /**
+   * Optional caller-supplied component-key resolver. When provided, this value
+   * takes precedence over PageHostComponent target bindings.
+   */
+  readonly resolveComponentKey?: (
+    context: ProjectedNavigationTargetRenderContext<
+      TComponentKey,
+      TModule,
+      TNavigation,
+      TRoute,
+      TPageHost,
+      TProjectionContext
+    >,
+  ) => string | null
+
+  /**
+   * Optional caller-supplied component-role resolver. When provided, this value
+   * takes precedence over PageHostComponent target bindings.
+   */
+  readonly resolveComponentRole?: (
+    context: ProjectedNavigationTargetRenderContext<
+      TComponentKey,
+      TModule,
+      TNavigation,
+      TRoute,
+      TPageHost,
+      TProjectionContext
+    >,
+  ) => string | null
+}
+
+export interface ResolvePageHostRendererOptions<
+  TModule extends PresentationPageHostRendererModuleProjection,
+  TNavigation extends NavigationDefinitionProjection<TRoute, TPageHost>,
+  TRoute extends NavigationRouteDefinition,
+  TPageHost extends PageHostDefinition,
+  TProjectionContext,
+> {
+  readonly componentKey?: string | null
+  readonly componentRole?: string | null
+  readonly componentSet?: string | null
+  readonly module: TModule
+  readonly pageHost: TPageHost | null
+  readonly registry: PageHostRendererRegistry<
+    TModule,
+    TNavigation,
+    TRoute,
+    TPageHost,
+    TProjectionContext
+  >
+  readonly route?: TRoute | null
+}
+
+/**
+ * Creates a navigation-target renderer from a page-host registry. Resolution
+ * starts from the semantic page-host shape, resolves an adapter component role,
+ * then invokes the frontend interpreter registered for that role.
+ */
+export function createPageHostTargetRenderer<
+  TComponentKey extends string,
+  TModule extends PresentationPageHostRendererModuleProjection,
+  TNavigation extends NavigationDefinitionProjection<TRoute, TPageHost>,
+  TRoute extends NavigationRouteDefinition,
+  TPageHost extends PageHostDefinition,
+  TProjectionContext,
+>({
+  componentSet,
+  registry,
+  resolveComponentKey,
+  resolveComponentRole,
+}: CreatePageHostTargetRendererOptions<
+  TComponentKey,
+  TModule,
+  TNavigation,
+  TRoute,
+  TPageHost,
+  TProjectionContext
+>): ProjectedNavigationTargetRenderer<
+  TComponentKey,
+  TModule,
+  TNavigation,
+  TRoute,
+  TPageHost,
+  TProjectionContext
+> {
+  return function renderPageHostTarget(context) {
+    const componentKey = resolveComponentKey?.(context) ?? null
+    const componentRole = resolveComponentRole?.(context) ?? null
+    const resolution = resolvePageHostRenderer({
+      componentKey,
+      componentRole,
+      componentSet,
+      module: context.module,
+      pageHost: context.pageHost,
+      registry,
+      route: context.route,
+    })
+
+    if (context.pageHost && resolution.renderer) {
+      return resolution.renderer({
+        context: context.context,
+        module: context.module,
+        navigation: context.navigation,
+        navigationTarget: context.navigationTarget,
+        pageHost: context.pageHost,
+        parameters: context.parameters,
+        route: context.route,
+      })
+    }
+
+    return context.renderBoundPageHost(componentKey)
+  }
+}
+
+/**
+ * Resolves a page-host renderer without rendering it.
+ */
+export function resolvePageHostRenderer<
+  TModule extends PresentationPageHostRendererModuleProjection,
+  TNavigation extends NavigationDefinitionProjection<TRoute, TPageHost>,
+  TRoute extends NavigationRouteDefinition,
+  TPageHost extends PageHostDefinition,
+  TProjectionContext,
+>({
+  componentKey,
+  componentRole,
+  componentSet,
+  module,
+  pageHost,
+  registry,
+  route,
+}: ResolvePageHostRendererOptions<
+  TModule,
+  TNavigation,
+  TRoute,
+  TPageHost,
+  TProjectionContext
+>): PageHostRendererResolution<
+  TModule,
+  TNavigation,
+  TRoute,
+  TPageHost,
+  TProjectionContext
+> {
+  return resolveCorePageHostRenderer<
+    PageHostRenderer<
+      TModule,
+      TNavigation,
+      TRoute,
+      TPageHost,
+      TProjectionContext
+    >,
+    TModule,
+    TRoute,
+    TPageHost
+  >({
+    componentKey,
+    componentRole,
+    componentSet,
+    module,
+    pageHost,
+    registry,
+    route,
+    targetKind: reactPresentationTargetKind,
+  })
+}
+
+const reactPresentationTargetKind = createPresentationEnumDiscriminator(
+  presentationTargetKinds,
+  'react',
+  'React',
+)