@cohesivesystems/presentation-core 0.1.0-alpha.1

package/src/projected-document-action-runtime-profile.ts

@@ -0,0 +1,133 @@
+import type {
+  DocumentProfileProjection,
+} from './document-module'
+import type {
+  ActionPlacementDefinition,
+} from './module'
+
+export type ProjectedDocumentActionRuntimeProfile =
+  NonNullable<DocumentProfileProjection['ActionRuntimeProfiles']>[number]
+
+/**
+ * Frontend runtime selection contract derived from a document action runtime
+ * profile declared by the presentation module.
+ *
+ * The spec keeps semantic identifiers and state conventions in core while
+ * allowing application adapters to supply concrete preview/start request and
+ * response types.
+ *
+ * @typeParam TPreviewRequest - Request shape sent to the action preview endpoint.
+ * @typeParam TPreviewResponse - Response shape returned from the action preview endpoint.
+ * @typeParam TStartInput - Input shape used to start the action after preview.
+ * @typeParam TStartResult - Result shape returned when the action is started.
+ * @typeParam TMetadata - Metadata shape associated with the action runtime.
+ */
+export interface ProjectedDocumentActionRuntimeProfileSpec<
+  TPreviewRequest extends object = Record<string, unknown>,
+  TPreviewResponse = unknown,
+  TStartInput = TPreviewRequest,
+  TStartResult = unknown,
+  TMetadata = unknown,
+> {
+  /** Action id that this runtime profile handles. */
+  readonly actionId?: string
+
+  /** Prefix used when registering diagnostics for this runtime profile. */
+  readonly diagnosticsKeyPrefix?: string
+
+  /** Presentation flow id used for preview/review UI, when one is modeled. */
+  readonly flowId?: string | null
+
+  /** Runtime profile id selected from the document profile projection. */
+  readonly profileId?: string
+
+  /**
+   * Optional suffix used to partition process input state for this action.
+   */
+  readonly processInputStateKeySuffix?: string | null
+
+  /** Source identifier for tracing where this runtime profile was projected. */
+  readonly source?: string
+
+  /**
+   * Compile-time-only type anchors for application adapters. These values are
+   * not populated by projection; they preserve strongly typed request,
+   * response, result, and metadata shapes through generic inference.
+   */
+  readonly typeHints?: {
+    /** Metadata shape associated with the runtime profile. */
+    readonly metadata?: TMetadata
+
+    /** Preview request shape sent before starting the action. */
+    readonly previewRequest?: TPreviewRequest
+
+    /** Preview response shape rendered by the review flow. */
+    readonly previewResponse?: TPreviewResponse
+
+    /** Start input shape submitted when the action is accepted. */
+    readonly startInput?: TStartInput
+
+    /** Start result shape returned after the action is accepted. */
+    readonly startResult?: TStartResult
+  }
+}
+
+export interface SelectDocumentActionRuntimeProfileOptions {
+  readonly actionPlacements?: readonly ActionPlacementDefinition[]
+}
+
+/**
+ * Selects the document action runtime profile that best matches placed actions
+ * for a document workspace profile.
+ */
+export function selectDocumentActionRuntimeProfile(
+  documentProfile: Pick<DocumentProfileProjection, 'ActionRuntimeProfiles' | 'Actions'> | null,
+  options: SelectDocumentActionRuntimeProfileOptions = {},
+): ProjectedDocumentActionRuntimeProfile | null {
+  const profiles = documentProfile?.ActionRuntimeProfiles ?? []
+  if (profiles.length <= 1) {
+    return profiles[0] ?? null
+  }
+
+  const actionPlacements = options.actionPlacements ?? documentProfile?.Actions ?? []
+  const placedActionIds = new Set(actionPlacements.map((placement) => placement.ActionId))
+
+  return (
+    profiles.find((profile) => placedActionIds.has(profile.ActionId)) ??
+    profiles[0] ??
+    null
+  )
+}
+
+/**
+ * Projects a backend-declared document action runtime profile into the frontend
+ * action-runtime spec consumed by document workspace adapters.
+ */
+export function projectDocumentActionRuntimeProfileSpec<
+  TPreviewRequest extends object = Record<string, unknown>,
+  TPreviewResponse = unknown,
+  TStartInput = TPreviewRequest,
+  TStartResult = unknown,
+  TMetadata = unknown,
+>(
+  documentProfile: Pick<DocumentProfileProjection, 'ActionRuntimeProfiles' | 'Actions'> | null,
+  options: SelectDocumentActionRuntimeProfileOptions = {},
+): ProjectedDocumentActionRuntimeProfileSpec<
+  TPreviewRequest,
+  TPreviewResponse,
+  TStartInput,
+  TStartResult,
+  TMetadata
+> | null {
+  const profile = selectDocumentActionRuntimeProfile(documentProfile, options)
+  return profile
+    ? {
+        actionId: profile.ActionId,
+        diagnosticsKeyPrefix: profile.DiagnosticsKeyPrefix,
+        flowId: profile.FlowId,
+        profileId: profile.Id,
+        processInputStateKeySuffix: profile.ProcessInputStateKeySuffix,
+        source: profile.Source,
+      }
+    : null
+}

package/src/projected-document-action-status-notice-diagnostics.ts

@@ -0,0 +1,116 @@
+import type { DocumentProfileProjection } from './document-module'
+import {
+  findPresentationAction,
+} from './module'
+import type {
+  DocumentActionStatusNoticeDefinition,
+  PresentationModuleDefinition,
+} from './module'
+import {
+  projectPresentationContentDiagnostics,
+} from './presentation-content-diagnostics'
+import type {
+  PresentationProjectionDiagnostic,
+} from './presentation-projection-diagnostics'
+
+export interface ProjectDocumentActionStatusNoticeDiagnosticsOptions {
+  readonly module: Pick<PresentationModuleDefinition, 'Actions'> | null
+  readonly profile: Pick<DocumentProfileProjection, 'ActionStatusNotices'> | null
+  readonly region?: string
+}
+
+export function projectDocumentActionStatusNoticeDiagnostics({
+  module,
+  profile,
+  region,
+}: ProjectDocumentActionStatusNoticeDiagnosticsOptions): readonly PresentationProjectionDiagnostic[] {
+  return getRegionActionStatusNotices(profile, region).flatMap((notice) => [
+    ...projectDocumentActionStatusNoticeContentDiagnostics(notice),
+    ...projectDocumentActionStatusNoticeActionDiagnostics(module, notice),
+  ])
+}
+
+function projectDocumentActionStatusNoticeContentDiagnostics(
+  notice: DocumentActionStatusNoticeDefinition,
+): readonly PresentationProjectionDiagnostic[] {
+  return projectPresentationContentDiagnostics({
+    content: notice.Content,
+    contentFallbackDescription: 'local action status error message fallback semantics',
+    descriptionFallbackDescription: 'local action status error message fallback semantics',
+    details: createDocumentActionStatusNoticeDiagnosticDetails(notice),
+    diagnosticIdPrefix: `action-status-notice.${notice.Id}.content`,
+    requireDescription: true,
+    source: 'document-workspace-notice-projection',
+    subject: createDocumentActionStatusNoticeDiagnosticSubject(notice),
+    surfaceLabel: `Action status notice '${notice.Name}'`,
+  })
+}
+
+function projectDocumentActionStatusNoticeActionDiagnostics(
+  module: Pick<PresentationModuleDefinition, 'Actions'> | null,
+  notice: DocumentActionStatusNoticeDefinition,
+): readonly PresentationProjectionDiagnostic[] {
+  if (findPresentationAction(module, notice.ActionId)) {
+    return []
+  }
+
+  return [
+    createDocumentActionStatusNoticeDiagnostic({
+      message:
+        `Action status notice '${notice.Name}' references action ` +
+        `'${notice.ActionId}', but the presentation module does not define it.`,
+      notice,
+      reason: 'missing-action',
+      severity: 'warning',
+    }),
+  ]
+}
+
+function getRegionActionStatusNotices(
+  profile: Pick<DocumentProfileProjection, 'ActionStatusNotices'> | null,
+  region?: string,
+) {
+  return profile?.ActionStatusNotices?.filter((notice) => !region || notice.Region === region) ?? []
+}
+
+function createDocumentActionStatusNoticeDiagnostic({
+  message,
+  notice,
+  reason,
+  severity,
+}: {
+  readonly message: string
+  readonly notice: DocumentActionStatusNoticeDefinition
+  readonly reason: string
+  readonly severity: PresentationProjectionDiagnostic['severity']
+}): PresentationProjectionDiagnostic {
+  return {
+    details: createDocumentActionStatusNoticeDiagnosticDetails(notice),
+    id: `action-status-notice.${notice.Id}.${reason}`,
+    message,
+    severity,
+    source: 'document-workspace-notice-projection',
+    subject: createDocumentActionStatusNoticeDiagnosticSubject(notice),
+  }
+}
+
+function createDocumentActionStatusNoticeDiagnosticDetails(
+  notice: DocumentActionStatusNoticeDefinition,
+) {
+  return {
+    actionId: notice.ActionId,
+    kind: notice.Kind,
+    noticeId: notice.Id,
+    region: notice.Region,
+  }
+}
+
+function createDocumentActionStatusNoticeDiagnosticSubject(
+  notice: DocumentActionStatusNoticeDefinition,
+) {
+  return {
+    id: notice.Id,
+    kind: 'document-action-status-notice',
+    name: notice.Name,
+  }
+}

package/src/projected-document-badge-formatting.ts

@@ -0,0 +1,7 @@
+export function formatBadgeValue(value: unknown) {
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+    return value.toString()
+  }
+
+  return null
+}

package/src/projected-document-editor-model.ts

@@ -0,0 +1,7 @@
+import type {
+  FieldPresentationDefinition,
+} from './module'
+
+export type DocumentEditorLayout = 'single' | 'split'
+
+export type ProjectedDocumentFieldDefinitionLike = FieldPresentationDefinition

package/src/projected-document-field-navigation.ts

@@ -0,0 +1,300 @@
+import type {
+  FieldPresentationDefinition,
+  PresentationModuleDefinition,
+} from './module'
+import type {
+  NavigationRouteParameters,
+  PresentationNavigationHrefFactory,
+} from './navigation'
+import {
+  readObjectPath,
+} from './object-path'
+import {
+  createPresentationEnumDiscriminator,
+  matchesPresentationEnum,
+} from './target-bindings'
+import {
+  presentationBindingKinds,
+} from '@cohesivesystems/presentation-contracts'
+
+/**
+ * Inputs used to project a document field value into a navigation binding.
+ */
+export interface ProjectDocumentFieldNavigationBindingOptions {
+  /** Optional route-to-href factory supplied by the host navigation runtime. */
+  readonly createHref?: PresentationNavigationHrefFactory
+
+  /** Presentation field whose target binding may declare a navigation route. */
+  readonly field: FieldPresentationDefinition
+
+  /** Presentation module target bindings used to find the field route binding. */
+  readonly module: Pick<PresentationModuleDefinition, 'Targets'> | null
+
+  /** Resource that contains route parameter source fields. */
+  readonly resource: unknown
+
+  /** Field value rendered as the navigation label and default route parameter. */
+  readonly value: unknown
+}
+
+/**
+ * Concrete navigation binding projected from a document field.
+ */
+export interface ProjectedDocumentFieldNavigationBinding {
+  /** Host-generated href, or `null` when no href factory was supplied. */
+  readonly href: string | null
+
+  /** Scalar label rendered for the navigable field value. */
+  readonly label: string
+
+  /** Required route parameter names that could not be resolved. */
+  readonly missingParameterNames: readonly string[]
+
+  /** Route parameter values projected from the field value and resource. */
+  readonly parameters: NavigationRouteParameters
+
+  /** Human-facing prefix rendered before the navigation label. */
+  readonly prefix: string
+
+  /** Semantic navigation route id selected by the field target binding. */
+  readonly routeId: string
+}
+
+/**
+ * Route projection for a document field before href generation is applied.
+ */
+export interface ProjectedDocumentFieldNavigationProjection {
+  /** Scalar label rendered for the navigable field value. */
+  readonly label: string
+
+  /** Required route parameter names that could not be resolved. */
+  readonly missingParameterNames: readonly string[]
+
+  /** Route parameter values projected from the field value and resource. */
+  readonly parameters: NavigationRouteParameters
+
+  /** Human-facing prefix rendered before the navigation label. */
+  readonly prefix: string
+
+  /** Semantic navigation route id selected by the field target binding. */
+  readonly routeId: string
+}
+
+interface DocumentFieldNavigationBindingOptions {
+  readonly labelPrefix?: string | null
+  readonly parameters?: readonly DocumentFieldNavigationParameterBinding[]
+}
+
+interface DocumentFieldNavigationParameterBinding {
+  readonly fieldPath?: string | null
+  readonly name: string
+  readonly source?: 'resource' | 'value' | string | null
+}
+
+/**
+ * Projects a document field into a complete navigation binding.
+ *
+ * Returns `null` when the field has no navigation route binding or the field
+ * value cannot be rendered as a scalar navigation label.
+ */
+export function projectDocumentFieldNavigationBinding({
+  createHref,
+  field,
+  module,
+  resource,
+  value,
+}: ProjectDocumentFieldNavigationBindingOptions): ProjectedDocumentFieldNavigationBinding | null {
+  const projection = projectDocumentFieldNavigation({
+    field,
+    module,
+    resource,
+    value,
+  })
+  if (!projection) {
+    return null
+  }
+
+  return {
+    ...projection,
+    href: createHref?.(projection.routeId, projection.parameters) ?? null,
+  }
+}
+
+/**
+ * Projects a document field into route id, label, prefix, and route parameters.
+ *
+ * The projection uses target binding options to map route parameters from the
+ * current field value or backing resource. If no parameter mapping is declared,
+ * it defaults to an `id` parameter sourced from the field value.
+ */
+export function projectDocumentFieldNavigation({
+  field,
+  module,
+  resource,
+  value,
+}: Omit<ProjectDocumentFieldNavigationBindingOptions, 'createHref'>): ProjectedDocumentFieldNavigationProjection | null {
+  const binding = findDocumentFieldNavigationRouteBinding(module, field)
+  if (!binding?.RouteId) {
+    return null
+  }
+
+  const label = readNavigationScalar(value)
+  if (!label) {
+    return null
+  }
+
+  const options = readDocumentFieldNavigationBindingOptions(binding.Options)
+  const parameterProjection = projectNavigationRouteParameters({
+    options,
+    resource,
+    value,
+  })
+
+  return {
+    label,
+    missingParameterNames: parameterProjection.missingParameterNames,
+    parameters: parameterProjection.parameters,
+    prefix: options.labelPrefix ?? field.Label,
+    routeId: binding.RouteId,
+  }
+}
+
+/**
+ * Finds the navigation-route target binding declared for a presentation field.
+ *
+ * Route-bearing bindings are preferred when multiple target bindings share the
+ * same field id; otherwise the first matching binding is returned.
+ */
+export function findDocumentFieldNavigationRouteBinding(
+  module: Pick<PresentationModuleDefinition, 'Targets'> | null,
+  field: FieldPresentationDefinition,
+) {
+  const bindings = module?.Targets
+    .flatMap((target) => target.Bindings)
+    .filter((binding) =>
+      matchesPresentationEnum(binding.Kind, navigationRouteBindingKind) &&
+      binding.Id === field.Id) ?? []
+
+  return bindings.find((binding) => binding.RouteId) ?? bindings[0] ?? null
+}
+
+function projectNavigationRouteParameters({
+  options,
+  resource,
+  value,
+}: {
+  readonly options: DocumentFieldNavigationBindingOptions
+  readonly resource: unknown
+  readonly value: unknown
+}): {
+  readonly missingParameterNames: readonly string[]
+  readonly parameters: NavigationRouteParameters
+} {
+  const parameterBindings = options.parameters?.length
+    ? options.parameters
+    : [{ name: 'id', source: 'value' }]
+  const parameters: NavigationRouteParameters = {}
+  const missingParameterNames: string[] = []
+
+  for (const parameter of parameterBindings) {
+    const parameterValue = projectNavigationRouteParameterValue({
+      parameter,
+      resource,
+      value,
+    })
+    if (parameterValue === null || parameterValue === undefined) {
+      missingParameterNames.push(parameter.name)
+      continue
+    }
+
+    parameters[parameter.name] = parameterValue
+  }
+
+  return {
+    missingParameterNames,
+    parameters,
+  }
+}
+
+function projectNavigationRouteParameterValue({
+  parameter,
+  resource,
+  value,
+}: {
+  readonly parameter: DocumentFieldNavigationParameterBinding
+  readonly resource: unknown
+  readonly value: unknown
+}) {
+  const source = parameter.source ?? 'value'
+  const resolvedValue =
+    source === 'resource' && parameter.fieldPath
+      ? readObjectPath(resource, parameter.fieldPath)
+      : value
+
+  return readNavigationScalar(resolvedValue)
+}
+
+function readDocumentFieldNavigationBindingOptions(
+  value: unknown,
+): DocumentFieldNavigationBindingOptions {
+  if (!value || typeof value !== 'object') {
+    return {}
+  }
+
+  const source = value as Record<string, unknown>
+  const labelPrefix = readOptionalString(source.labelPrefix ?? source.LabelPrefix)
+  const rawParameters = source.parameters ?? source.Parameters
+  const parameters = Array.isArray(rawParameters)
+    ? rawParameters
+      .map(readDocumentFieldNavigationParameterBinding)
+      .filter((parameter): parameter is DocumentFieldNavigationParameterBinding =>
+        Boolean(parameter))
+    : undefined
+
+  return {
+    labelPrefix,
+    parameters,
+  }
+}
+
+function readDocumentFieldNavigationParameterBinding(
+  value: unknown,
+): DocumentFieldNavigationParameterBinding | null {
+  if (!value || typeof value !== 'object') {
+    return null
+  }
+
+  const source = value as Record<string, unknown>
+  const name = readOptionalString(source.name ?? source.Name)
+  if (!name) {
+    return null
+  }
+
+  return {
+    fieldPath: readOptionalString(source.fieldPath ?? source.FieldPath),
+    name,
+    source: readOptionalString(source.source ?? source.Source),
+  }
+}
+
+function readNavigationScalar(value: unknown) {
+  if (typeof value === 'string' && value.length > 0) {
+    return value
+  }
+
+  if (typeof value === 'number' || typeof value === 'bigint' || typeof value === 'boolean') {
+    return value.toString()
+  }
+
+  return null
+}
+
+function readOptionalString(value: unknown) {
+  return typeof value === 'string' && value.length > 0 ? value : null
+}
+
+const navigationRouteBindingKind = createPresentationEnumDiscriminator(
+  presentationBindingKinds,
+  'navigationRoute',
+  'NavigationRoute',
+)

package/src/projected-document-field-semantics.ts

@@ -0,0 +1,27 @@
+import type {
+  FieldPresentationDefinition,
+} from './module'
+import {
+  fieldDisplayKinds,
+} from '@cohesivesystems/presentation-contracts'
+
+export function isProjectedDocumentBadgeField(field: FieldPresentationDefinition) {
+  return matchesFieldDisplayKind(field, fieldDisplayKinds.badge, 'Badge') ||
+    matchesFieldDisplayKind(field, fieldDisplayKinds.status, 'Status')
+}
+
+export function isProjectedDocumentEntityReferenceField(field: FieldPresentationDefinition) {
+  return matchesFieldDisplayKind(field, fieldDisplayKinds.entityReference, 'EntityReference') ||
+    (field.Capabilities.includes('navigate') &&
+      matchesFieldDisplayKind(field, fieldDisplayKinds.link, 'Link'))
+}
+
+export function matchesFieldDisplayKind(
+  field: FieldPresentationDefinition,
+  numericValue: string | number,
+  label: string,
+) {
+  return field.DisplayKind === numericValue ||
+    String(field.DisplayKind) === String(numericValue) ||
+    String(field.DisplayKind) === label
+}