@cohesivesystems/presentation-core 0.1.0-alpha.1

package/src/document-summary-model.ts

@@ -0,0 +1 @@
+export const documentSummaryStructuralMessageFieldPath = 'StructuralMessage'

package/src/document-workspace-chrome-projection.ts

@@ -0,0 +1,62 @@
+import {
+  findPresentationView,
+  type PresentationModuleDefinition,
+  type ViewDefinition,
+} from './module'
+import {
+  viewChromeSlotKinds,
+  viewRegionKinds,
+} from '@cohesivesystems/presentation-contracts'
+
+/**
+ * Resolves document workspace metadata fields from page/header chrome.
+ *
+ * The document editor surface renders these same badge-strip field ids. Keeping
+ * this helper in the projection layer lets adapters build field renderers and
+ * diagnostics from the same IR locations instead of repeating view ids.
+ */
+export function resolveDocumentWorkspaceMetadataFieldIds(
+  module: Pick<PresentationModuleDefinition, 'Views'> | null,
+  pageView: ViewDefinition | null,
+) {
+  const headerView = findHostedView(module, pageView, viewRegionKinds.header, 'Header')
+  const badgeSlot = headerView?.Chrome?.Slots?.find((slot) =>
+    matchesEnum(slot.Kind, viewChromeSlotKinds.badgeStrip, 'BadgeStrip'))
+
+  return badgeSlot?.FieldIds ?? []
+}
+
+/**
+ * Resolves the page-region id used for document workspace header chrome.
+ *
+ * Profile-level notices target region ids, while page layout regions carry
+ * enum kinds. This helper keeps that cross-reference in the projection layer
+ * instead of repeating product constants in workspace hosts.
+ */
+export function resolveDocumentWorkspaceHeaderRegionId(pageView: ViewDefinition | null) {
+  return pageView?.Regions?.find((region) =>
+    matchesEnum(region.Kind, viewRegionKinds.header, 'Header'))?.Id ?? null
+}
+
+function findHostedView(
+  module: Pick<PresentationModuleDefinition, 'Views'> | null,
+  view: ViewDefinition | null,
+  regionKind: string | number,
+  regionKindLabel: string,
+) {
+  const region = view?.Regions?.find((candidate) =>
+    matchesEnum(candidate.Kind, regionKind, regionKindLabel))
+  const viewId = region?.ViewIds?.[0]
+
+  return viewId ? findPresentationView(module, viewId) : null
+}
+
+function matchesEnum(
+  value: string | number | null | undefined,
+  numericValue: string | number,
+  label: string,
+) {
+  return value === numericValue ||
+    String(value) === String(numericValue) ||
+    String(value) === label
+}

package/src/document-workspace-surface-slots.ts

@@ -0,0 +1,458 @@
+import {
+  findPresentationView,
+  type DocumentWorkspaceSurfaceSlotDefinition,
+  type DocumentWorkspaceSurfaceSlotRole,
+  type PresentationBindingDefinition,
+  type PresentationModuleDefinition,
+  type ViewDefinition,
+  type ViewRegionDefinition,
+  type WorkspaceDefinition,
+} from './module'
+import {
+  createPresentationProjectionDiagnostic,
+  type PresentationProjectionDiagnostic,
+} from './presentation-projection-diagnostics'
+import {
+  documentWorkspaceSurfaceSlotRoleLabels,
+  documentWorkspaceSurfaceSlotRoles,
+  viewRegionKindLabels,
+  viewRegionKinds,
+} from '@cohesivesystems/presentation-contracts'
+
+export interface DocumentWorkspaceSurfaceSlotDescriptor {
+  readonly expectsHostedView: boolean
+  readonly id: string
+  readonly regionKind?: string | number | null
+  readonly regionKindLabel?: string
+  readonly role: string | number
+  readonly roleLabel?: string
+  readonly renderer?: PresentationBindingDefinition | null
+}
+
+export interface ResolvedDocumentWorkspaceSurfaceSlot {
+  readonly descriptor: DocumentWorkspaceSurfaceSlotDescriptor
+  readonly expectsHostedView: boolean
+  readonly id: string
+  readonly region: ViewRegionDefinition | null
+  readonly role: string | number
+  readonly roleLabel?: string
+  readonly renderer?: PresentationBindingDefinition | null
+  readonly view: ViewDefinition | null
+}
+
+export interface ResolvedDocumentWorkspaceSurfaceSlots {
+  readonly all: readonly ResolvedDocumentWorkspaceSurfaceSlot[]
+  readonly auxiliary: ResolvedDocumentWorkspaceSurfaceSlot
+  readonly header: ResolvedDocumentWorkspaceSurfaceSlot
+  readonly primarySurface: ResolvedDocumentWorkspaceSurfaceSlot
+}
+
+export const documentWorkspaceSurfaceSlotRoleKeys = {
+  header: 'header',
+  primarySurface: 'primarySurface',
+  auxiliary: 'auxiliary',
+  custom: 'custom',
+} as const
+
+export const documentWorkspaceSurfaceSlotIds = {
+  auxiliary: 'auxiliary',
+  header: 'header',
+  workspace: 'workspace',
+} as const
+
+export const documentWorkspaceSurfaceSlotDescriptors = {
+  header: {
+    expectsHostedView: true,
+    id: documentWorkspaceSurfaceSlotIds.header,
+    regionKind: viewRegionKinds.header,
+    regionKindLabel: viewRegionKindLabels[viewRegionKinds.header],
+    role: documentWorkspaceSurfaceSlotRoles.header,
+    roleLabel: documentWorkspaceSurfaceSlotRoleLabels[
+      documentWorkspaceSurfaceSlotRoles.header
+    ],
+    renderer: null,
+  },
+  workspace: {
+    expectsHostedView: true,
+    id: documentWorkspaceSurfaceSlotIds.workspace,
+    regionKind: viewRegionKinds.surface,
+    regionKindLabel: viewRegionKindLabels[viewRegionKinds.surface],
+    role: documentWorkspaceSurfaceSlotRoles.primarySurface,
+    roleLabel: documentWorkspaceSurfaceSlotRoleLabels[
+      documentWorkspaceSurfaceSlotRoles.primarySurface
+    ],
+    renderer: null,
+  },
+  auxiliary: {
+    expectsHostedView: false,
+    id: documentWorkspaceSurfaceSlotIds.auxiliary,
+    role: documentWorkspaceSurfaceSlotRoles.auxiliary,
+    roleLabel: documentWorkspaceSurfaceSlotRoleLabels[
+      documentWorkspaceSurfaceSlotRoles.auxiliary
+    ],
+    renderer: null,
+  },
+} as const satisfies Record<string, DocumentWorkspaceSurfaceSlotDescriptor>
+
+export function resolveDocumentWorkspaceSurfaceSlots(
+  module: Pick<PresentationModuleDefinition, 'Views'> | null,
+  pageView: ViewDefinition | null,
+  workspace?: Pick<WorkspaceDefinition, 'SurfaceSlots'> | null,
+): ResolvedDocumentWorkspaceSurfaceSlots {
+  const descriptors = resolveDocumentWorkspaceSurfaceSlotDescriptors(workspace)
+  const resolvedSlots = descriptors.map((descriptor) =>
+    resolveDocumentWorkspaceSurfaceSlot(
+      module,
+      pageView,
+      descriptor,
+    ))
+  const header = resolveDocumentWorkspaceSurfaceSlotByRole(
+    resolvedSlots,
+    module,
+    pageView,
+    documentWorkspaceSurfaceSlotDescriptors.header,
+  )
+  const primarySurface = resolveDocumentWorkspaceSurfaceSlotByRole(
+    resolvedSlots,
+    module,
+    pageView,
+    documentWorkspaceSurfaceSlotDescriptors.workspace,
+  )
+  const auxiliary = resolveDocumentWorkspaceSurfaceSlotByRole(
+    resolvedSlots,
+    module,
+    pageView,
+    documentWorkspaceSurfaceSlotDescriptors.auxiliary,
+  )
+
+  return {
+    all: resolvedSlots,
+    auxiliary,
+    header,
+    primarySurface,
+  }
+}
+
+export function projectDocumentWorkspaceSurfaceSlotDiagnostics({
+  declaredSlots,
+  pageView,
+  renderedSlots,
+  sourceId,
+}: {
+  readonly declaredSlots: readonly ResolvedDocumentWorkspaceSurfaceSlot[]
+  readonly pageView: ViewDefinition | null
+  readonly renderedSlots: readonly ResolvedDocumentWorkspaceSurfaceSlot[]
+  readonly sourceId: string
+}): readonly PresentationProjectionDiagnostic[] {
+  const diagnostics: PresentationProjectionDiagnostic[] = []
+  const declaredSlotIds = new Set(declaredSlots.map((slot) => slot.id))
+  const renderedSlotIds = new Set(renderedSlots.map((slot) => slot.id))
+
+  diagnostics.push(...projectDuplicateDocumentWorkspaceSurfaceSlotRoleDiagnostics({
+    declaredSlots,
+    sourceId,
+  }))
+
+  for (const slotId of declaredSlotIds) {
+    if (!renderedSlotIds.has(slotId)) {
+      diagnostics.push(createPresentationProjectionDiagnostic({
+        category: 'incomplete-projection',
+        id: `document-workspace-surface-slot:${slotId}:not-rendered`,
+        interpretation: {
+          status: 'unbound',
+          target: 'react',
+        },
+        message:
+          `Document workspace surface slot '${slotId}' is declared but is not rendered by the ` +
+          'document editor surface interpreter.',
+        severity: 'warning',
+        source: sourceId,
+        subject: {
+          id: slotId,
+          kind: 'document-workspace-surface-slot',
+        },
+        suggestedNextStep:
+          'Bind a surface-slot renderer for this slot role or remove it from the workspace SurfaceSlots IR.',
+      }))
+    }
+  }
+
+  for (const slot of distinctDocumentWorkspaceSurfaceSlots([
+    ...declaredSlots,
+    ...renderedSlots,
+  ])) {
+    if (slot.expectsHostedView && !slot.view) {
+      diagnostics.push(createPresentationProjectionDiagnostic({
+        category: 'missing-definition',
+        details: {
+          pageViewId: pageView?.Id ?? null,
+          regionId: slot.region?.Id ?? null,
+          role: resolveDocumentWorkspaceSurfaceSlotRoleKey(slot.role, slot.roleLabel),
+        },
+        id: `document-workspace-surface-slot:${slot.id}:missing-hosted-view`,
+        interpretation: {
+          status: 'unbound',
+          target: 'react',
+        },
+        message:
+          `Document workspace surface slot '${slot.id}' requires a hosted view but has no ` +
+          'hosted view on the page view.',
+        severity: 'warning',
+        source: sourceId,
+        subject: {
+          id: slot.id,
+          kind: 'document-workspace-surface-slot',
+        },
+        suggestedNextStep:
+          'Declare a page region with the expected ViewRegionKind and a hosted view id for this slot.',
+      }))
+    }
+  }
+
+  for (const slot of renderedSlots) {
+    if (!declaredSlotIds.has(slot.id)) {
+      diagnostics.push(createPresentationProjectionDiagnostic({
+        category: 'local-interpretation',
+        id: `document-workspace-surface-slot:${slot.id}:fallback`,
+        interpretation: {
+          status: 'locally-interpreted',
+          target: 'react',
+        },
+        message:
+          `Document workspace surface slot '${slot.id}' is rendered through the default ` +
+          'surface-slot fallback because it is not declared on the workspace SurfaceSlots IR.',
+        severity: 'info',
+        source: sourceId,
+        subject: {
+          id: slot.id,
+          kind: 'document-workspace-surface-slot',
+        },
+        suggestedNextStep:
+          'Add this slot to the workspace SurfaceSlots declaration if it is a first-class slot.',
+      }))
+    }
+  }
+
+  return diagnostics
+}
+
+export function resolveDocumentWorkspaceSurfaceSlotRoleKey(
+  role: string | number,
+  roleLabel?: string,
+) {
+  for (const [roleKey, roleValue] of Object.entries(documentWorkspaceSurfaceSlotRoles)) {
+    if (
+      isEnumDiscriminator(
+        role,
+        roleValue,
+        documentWorkspaceSurfaceSlotRoleLabels[
+          roleValue as keyof typeof documentWorkspaceSurfaceSlotRoleLabels
+        ],
+      )
+    ) {
+      return roleKey
+    }
+  }
+
+  return normalizeEnumDiscriminator(roleLabel ?? role)
+}
+
+export function isStandardDocumentWorkspaceSurfaceSlotRoleKey(roleKey: string) {
+  return (
+    roleKey === documentWorkspaceSurfaceSlotRoleKeys.header ||
+    roleKey === documentWorkspaceSurfaceSlotRoleKeys.primarySurface ||
+    roleKey === documentWorkspaceSurfaceSlotRoleKeys.auxiliary
+  )
+}
+
+function resolveDocumentWorkspaceSurfaceSlotDescriptors(
+  workspace?: Pick<WorkspaceDefinition, 'SurfaceSlots'> | null,
+): readonly DocumentWorkspaceSurfaceSlotDescriptor[] {
+  const slots = workspace?.SurfaceSlots ?? []
+  if (slots.length === 0) {
+    return Object.values(documentWorkspaceSurfaceSlotDescriptors)
+  }
+
+  return slots.map(createDocumentWorkspaceSurfaceSlotDescriptor)
+}
+
+function createDocumentWorkspaceSurfaceSlotDescriptor(
+  slot: DocumentWorkspaceSurfaceSlotDefinition,
+): DocumentWorkspaceSurfaceSlotDescriptor {
+  const regionKind = slot.RegionKind ?? undefined
+  return {
+    expectsHostedView: slot.RequiresHostedView,
+    id: slot.Id,
+    regionKind,
+    regionKindLabel: resolveViewRegionKindLabel(regionKind),
+    role: slot.Role,
+    roleLabel: resolveDocumentWorkspaceSurfaceSlotRoleLabel(slot.Role),
+    renderer: slot.Renderer ?? null,
+  }
+}
+
+function resolveDocumentWorkspaceSurfaceSlotByRole(
+  resolvedSlots: readonly ResolvedDocumentWorkspaceSurfaceSlot[],
+  module: Pick<PresentationModuleDefinition, 'Views'> | null,
+  pageView: ViewDefinition | null,
+  fallbackDescriptor: DocumentWorkspaceSurfaceSlotDescriptor,
+): ResolvedDocumentWorkspaceSurfaceSlot {
+  return (
+    resolvedSlots.find((slot) =>
+      isEnumDiscriminator(
+        slot.role,
+        fallbackDescriptor.role,
+        fallbackDescriptor.roleLabel ?? String(fallbackDescriptor.role),
+      )) ??
+    resolveDocumentWorkspaceSurfaceSlot(module, pageView, fallbackDescriptor)
+  )
+}
+
+function resolveDocumentWorkspaceSurfaceSlot(
+  module: Pick<PresentationModuleDefinition, 'Views'> | null,
+  pageView: ViewDefinition | null,
+  descriptor: DocumentWorkspaceSurfaceSlotDescriptor,
+): ResolvedDocumentWorkspaceSurfaceSlot {
+  const regionKind = descriptor.regionKind
+  const regionKindLabel = descriptor.regionKindLabel
+  const region =
+    regionKind === undefined || regionKind === null || regionKindLabel === undefined
+      ? null
+      : pageView?.Regions?.find((candidate) =>
+          isEnumDiscriminator(
+            candidate.Kind,
+            regionKind,
+            regionKindLabel,
+          )) ?? null
+  const viewId = region?.ViewIds?.[0]
+
+  return {
+    descriptor,
+    expectsHostedView: descriptor.expectsHostedView,
+    id: descriptor.id,
+    region,
+    role: descriptor.role,
+    roleLabel: descriptor.roleLabel,
+    renderer: descriptor.renderer ?? null,
+    view: viewId ? findPresentationView(module, viewId) : null,
+  }
+}
+
+function isEnumDiscriminator(
+  value: string | number,
+  expected: string | number,
+  expectedLabel: string,
+) {
+  const valueLabel = resolveViewRegionKindLabel(value)
+
+  return (
+    value === expected ||
+    String(value) === String(expected) ||
+    (valueLabel !== undefined &&
+      normalizeEnumDiscriminator(valueLabel) === normalizeEnumDiscriminator(expectedLabel)) ||
+    normalizeEnumDiscriminator(value) === normalizeEnumDiscriminator(expectedLabel)
+  )
+}
+
+function normalizeEnumDiscriminator(value: string | number) {
+  return String(value).replace(/[-_\s]/g, '').toLocaleLowerCase()
+}
+
+function resolveViewRegionKindLabel(regionKind: string | number | null | undefined) {
+  if (regionKind === null || regionKind === undefined) {
+    return undefined
+  }
+
+  if (
+    typeof regionKind === 'number' &&
+    Object.prototype.hasOwnProperty.call(viewRegionKindLabels, regionKind)
+  ) {
+    return viewRegionKindLabels[regionKind as keyof typeof viewRegionKindLabels]
+  }
+
+  return String(regionKind)
+}
+
+function resolveDocumentWorkspaceSurfaceSlotRoleLabel(
+  role: DocumentWorkspaceSurfaceSlotRole | string | number | null | undefined,
+) {
+  if (role === null || role === undefined) {
+    return undefined
+  }
+
+  if (
+    typeof role === 'number' &&
+    Object.prototype.hasOwnProperty.call(documentWorkspaceSurfaceSlotRoleLabels, role)
+  ) {
+    return documentWorkspaceSurfaceSlotRoleLabels[
+      role as keyof typeof documentWorkspaceSurfaceSlotRoleLabels
+    ]
+  }
+
+  return String(role)
+}
+
+function projectDuplicateDocumentWorkspaceSurfaceSlotRoleDiagnostics({
+  declaredSlots,
+  sourceId,
+}: {
+  readonly declaredSlots: readonly ResolvedDocumentWorkspaceSurfaceSlot[]
+  readonly sourceId: string
+}): readonly PresentationProjectionDiagnostic[] {
+  const slotsByRoleKey = new Map<string, ResolvedDocumentWorkspaceSurfaceSlot[]>()
+
+  for (const slot of declaredSlots) {
+    const roleKey = resolveDocumentWorkspaceSurfaceSlotRoleKey(slot.role, slot.roleLabel)
+    if (!isStandardDocumentWorkspaceSurfaceSlotRoleKey(roleKey)) {
+      continue
+    }
+
+    const slots = slotsByRoleKey.get(roleKey) ?? []
+    slots.push(slot)
+    slotsByRoleKey.set(roleKey, slots)
+  }
+
+  const diagnostics: PresentationProjectionDiagnostic[] = []
+  for (const [roleKey, slots] of slotsByRoleKey) {
+    if (slots.length <= 1) {
+      continue
+    }
+
+    diagnostics.push(createPresentationProjectionDiagnostic({
+      category: 'incomplete-projection',
+      details: {
+        role: roleKey,
+        slotIds: slots.map((slot) => slot.id),
+      },
+      id: `document-workspace-surface-slot-role:${roleKey}:duplicate`,
+      interpretation: {
+        status: 'unbound',
+        target: 'react',
+      },
+      message:
+        `Document workspace surface role '${roleKey}' is declared by multiple slots: ` +
+        slots.map((slot) => `'${slot.id}'`).join(', '),
+      severity: 'warning',
+      source: sourceId,
+      subject: {
+        id: roleKey,
+        kind: 'document-workspace-surface-slot-role',
+      },
+      suggestedNextStep:
+        'Keep one standard slot per role, or introduce a custom role with an explicit renderer.',
+    }))
+  }
+
+  return diagnostics
+}
+
+function distinctDocumentWorkspaceSurfaceSlots(
+  slots: readonly ResolvedDocumentWorkspaceSurfaceSlot[],
+) {
+  const distinctSlots = new Map<string, ResolvedDocumentWorkspaceSurfaceSlot>()
+  for (const slot of slots) {
+    distinctSlots.set(slot.id, slot)
+  }
+
+  return [...distinctSlots.values()]
+}

package/src/endpoint-executor.ts

@@ -0,0 +1,122 @@
+/**
+ * Transport-neutral request envelope passed to an endpoint executor after a
+ * presentation runtime has projected semantic inputs into concrete API inputs.
+ *
+ * @typeParam TBody - Request body payload shape.
+ * @typeParam TQuery - Query payload shape.
+ */
+export interface EndpointExecutionRequest<TBody = unknown, TQuery = unknown> {
+  /** Request body payload for mutation/action endpoints. */
+  readonly body?: TBody
+
+  /** Query payload for query/read endpoints. */
+  readonly query?: TQuery | null
+
+  /** Route parameters substituted into endpoint paths by the host adapter. */
+  readonly routeParameters?: Readonly<Record<string, string | null | undefined>>
+}
+
+/**
+ * Executes a concrete endpoint request.
+ *
+ * Endpoint executors are supplied by applications or adapters because only the
+ * host knows how endpoint ids map to generated clients, fetch calls, auth, and
+ * transport concerns.
+ *
+ * @typeParam TResult - Result shape returned by the endpoint executor.
+ * @typeParam TBody - Request body payload shape.
+ * @typeParam TQuery - Query payload shape.
+ */
+export type EndpointExecutor<
+  TResult = unknown,
+  TBody = unknown,
+  TQuery = unknown,
+> = (request: EndpointExecutionRequest<TBody, TQuery>) => Promise<TResult>
+
+/**
+ * Registry keyed by semantic endpoint id.
+ */
+export type EndpointExecutorRegistry = Readonly<Record<string, EndpointExecutor>>
+
+/**
+ * Dispatches an endpoint id through a host-provided endpoint executor registry.
+ *
+ * @typeParam TResult - Result shape returned by the selected executor.
+ * @typeParam TBody - Request body payload shape.
+ * @typeParam TQuery - Query payload shape.
+ */
+export type EndpointRegistryExecutor = <
+  TResult = unknown,
+  TBody = unknown,
+  TQuery = unknown,
+>(
+  endpointId: string,
+  request?: EndpointExecutionRequest<TBody, TQuery>,
+) => Promise<TResult>
+
+/**
+ * Options for creating an endpoint registry dispatcher.
+ */
+export interface CreateEndpointExecutorOptions {
+  /** Human-readable endpoint family label used in diagnostic errors. */
+  readonly label?: string
+}
+
+/**
+ * Creates a generic dispatcher from semantic endpoint ids to concrete endpoint
+ * executors.
+ */
+export function createEndpointExecutor(
+  registry: EndpointExecutorRegistry,
+  { label = 'API' }: CreateEndpointExecutorOptions = {},
+): EndpointRegistryExecutor {
+  return async function executeEndpoint<
+    TResult = unknown,
+    TBody = unknown,
+    TQuery = unknown,
+  >(
+    endpointId: string,
+    request: EndpointExecutionRequest<TBody, TQuery> = {},
+  ): Promise<TResult> {
+    const executor = registry[endpointId]
+    if (!executor) {
+      throw new Error(`No ${label} endpoint executor is registered for endpoint '${endpointId}'.`)
+    }
+
+    return await executor(request) as TResult
+  }
+}
+
+/**
+ * Reads a required route parameter from a projected endpoint request.
+ */
+export function readRequiredEndpointRouteParameter(
+  endpointId: string,
+  request: EndpointExecutionRequest,
+  parameterName: string,
+): string {
+  const value = request.routeParameters?.[parameterName]
+  if (value === null || value === undefined || value === '') {
+    throw new Error(
+      `Endpoint '${endpointId}' requires route parameter '${parameterName}'.`,
+    )
+  }
+
+  return value
+}
+
+/**
+ * Reads a required request body from a projected endpoint request.
+ *
+ * @typeParam TBody - Expected request body payload shape.
+ */
+export function readRequiredEndpointBody<TBody>(
+  endpointId: string,
+  request: EndpointExecutionRequest,
+): TBody {
+  if (request.body === undefined) {
+    throw new Error(`Endpoint '${endpointId}' requires a request body.`)
+  }
+
+  return request.body as TBody
+}