@cohesivesystems/presentation-core 0.1.0-alpha.1

package/src/presentation-action-runtime-binding.ts

@@ -0,0 +1,177 @@
+import type {
+  ActionDefinition,
+  PresentationModuleDefinition,
+} from './module'
+import {
+  actionKindLabels,
+  actionSemanticsKindLabels,
+  actionScopeKindLabels,
+  documentWorkspaceActionKindLabels,
+  localDocumentEditorActionKindLabels,
+  preparationKindLabels,
+  presentationBindingKindLabels,
+  type ActionKind,
+  type ActionScopeKind,
+  type ActionSemanticsKind,
+  type DocumentWorkspaceActionKind,
+  type LocalDocumentEditorActionKind,
+  type PreparationKind,
+  type PresentationBindingKind,
+} from '@cohesivesystems/presentation-contracts'
+
+export interface PresentationActionRuntime<TExecuteContext = unknown, TLabel = string> {
+  readonly canExecute?: (context: TExecuteContext) => boolean
+  readonly disabledReason?: TLabel
+  readonly execute?: (context: TExecuteContext) => Promise<void> | void
+  readonly isDisabled?: boolean
+  readonly isHidden?: boolean
+  readonly isPending?: boolean
+  readonly label?: TLabel
+  readonly pendingLabel?: TLabel
+}
+
+export interface PresentationActionRuntimeBindingContext {
+  readonly action: ActionDefinition
+  readonly actionId: string
+  readonly module: PresentationModuleDefinition
+}
+
+export interface PresentationActionRuntimeBinding<TExecuteContext = unknown, TLabel = string> {
+  readonly id: string
+  readonly matches: (context: PresentationActionRuntimeBindingContext) => boolean
+  readonly project: (context: PresentationActionRuntimeBindingContext) => PresentationActionRuntime<TExecuteContext, TLabel> | null | undefined
+}
+
+export interface PresentationActionRuntimeBindingSpec<TExecuteContext = unknown, TLabel = string> {
+  /** Optional exact action id match for narrowly scoped or legacy bindings. */
+  readonly actionId?: string | readonly string[]
+
+  /** Optional infrastructure binding match, such as endpoint, flow event, or local state. */
+  readonly bindingKind?: PresentationBindingKind | readonly PresentationBindingKind[]
+
+  /** Optional sub-kind match for DocumentWorkspace action semantics. */
+  readonly documentWorkspaceKind?:
+    | DocumentWorkspaceActionKind
+    | readonly DocumentWorkspaceActionKind[]
+
+  readonly id: string
+
+  /** Optional semantic action kind match. Prefer semantics-specific fields when possible. */
+  readonly kind?: ActionKind | readonly ActionKind[]
+
+  /** Optional sub-kind match for LocalDocumentEditor action semantics. */
+  readonly localDocumentEditorKind?:
+    | LocalDocumentEditorActionKind
+    | readonly LocalDocumentEditorActionKind[]
+
+  readonly predicate?: (context: PresentationActionRuntimeBindingContext) => boolean
+
+  readonly preparationKind?: PreparationKind | readonly PreparationKind[]
+
+  /** Optional first-class action semantics match. */
+  readonly semanticsKind?: ActionSemanticsKind | readonly ActionSemanticsKind[]
+
+  readonly project: (context: PresentationActionRuntimeBindingContext) => PresentationActionRuntime<TExecuteContext, TLabel> | null | undefined
+
+  readonly scope?: ActionScopeKind | readonly ActionScopeKind[]
+}
+
+/**
+ * Creates an adapter-neutral runtime binding for a semantic presentation
+ * action. The binding decides whether an ActionDefinition matches, then
+ * projects frontend-local runtime state for that action.
+ */
+export function createPresentationActionRuntimeBinding<
+  TExecuteContext = unknown,
+  TLabel = string,
+>({
+  actionId,
+  bindingKind,
+  documentWorkspaceKind,
+  id,
+  kind,
+  localDocumentEditorKind,
+  predicate,
+  preparationKind,
+  project,
+  semanticsKind,
+  scope,
+}: PresentationActionRuntimeBindingSpec<
+  TExecuteContext,
+  TLabel
+>): PresentationActionRuntimeBinding<TExecuteContext, TLabel> {
+  return {
+    id,
+    matches: (context) =>
+      matchesStringOption(context.action.Id, actionId) &&
+      matchesEnumOption(context.action.Kind, kind, actionKindLabels) &&
+      matchesEnumOption(context.action.Scope, scope, actionScopeKindLabels) &&
+      matchesEnumOption(context.action.Binding.Kind, bindingKind, presentationBindingKindLabels) &&
+      matchesEnumOption(context.action.Preparation?.Kind, preparationKind, preparationKindLabels) &&
+      matchesEnumOption(context.action.Semantics?.Kind, semanticsKind, actionSemanticsKindLabels) &&
+      matchesEnumOption(
+        context.action.Semantics?.DocumentWorkspace?.Kind,
+        documentWorkspaceKind,
+        documentWorkspaceActionKindLabels,
+      ) &&
+      matchesEnumOption(
+        context.action.Semantics?.LocalDocumentEditor?.Kind,
+        localDocumentEditorKind,
+        localDocumentEditorActionKindLabels,
+      ) &&
+      (predicate?.(context) ?? true),
+    project,
+  }
+}
+
+function matchesStringOption(
+  value: string | null | undefined,
+  expected: string | readonly string[] | null | undefined,
+) {
+  if (!expected) {
+    return true
+  }
+
+  return toArray(expected).includes(value ?? '')
+}
+
+function matchesEnumOption<TValue extends string | number>(
+  value: string | number | null | undefined,
+  expected: TValue | readonly TValue[] | null | undefined,
+  labels: Readonly<Record<number, string>>,
+) {
+  if (expected === null || expected === undefined) {
+    return true
+  }
+
+  return toArray(expected).some((candidate) =>
+    matchesGeneratedEnumValue(value, candidate, labels),
+  )
+}
+
+function matchesGeneratedEnumValue<TValue extends string | number>(
+  value: string | number | null | undefined,
+  expected: TValue,
+  labels: Readonly<Record<number, string>>,
+) {
+  if (value === expected) {
+    return true
+  }
+
+  const expectedLabel = typeof expected === 'number'
+    ? labels[expected] ?? String(expected)
+    : String(expected)
+  const actualLabel = typeof value === 'number'
+    ? labels[value] ?? String(value)
+    : String(value ?? '')
+
+  return normalizeEnumLabel(actualLabel) === normalizeEnumLabel(expectedLabel)
+}
+
+function normalizeEnumLabel(value: string) {
+  return value.replace(/[^a-zA-Z0-9]+/g, '').toLocaleLowerCase()
+}
+
+function toArray<TValue>(value: TValue | readonly TValue[]) {
+  return Array.isArray(value) ? value : [value]
+}

package/src/presentation-action-runtime-diagnostics.ts

@@ -0,0 +1,120 @@
+import type {
+  ActionDefinition,
+  ActionPlacementDefinition,
+  PresentationModuleDefinition,
+} from './module'
+import {
+  findPresentationAction,
+} from './module'
+import type {
+  PresentationActionRuntimeRegistry,
+} from './presentation-action-runtime-projection'
+import type {
+  PresentationProjectionDiagnostic,
+} from './presentation-projection-diagnostics'
+
+export interface ProjectPresentationActionRuntimeBindingDiagnosticsOptions<
+  TExecuteContext,
+  TLabel,
+> {
+  readonly actionPlacements: readonly ActionPlacementDefinition[]
+  readonly module: Pick<PresentationModuleDefinition, 'Actions'> | null
+  readonly runtimes: PresentationActionRuntimeRegistry<TExecuteContext, TLabel>
+  readonly source: string
+}
+
+/**
+ * Reports placed actions that reached the frontend but did not receive an
+ * executable runtime interpretation.
+ *
+ * This keeps IR expansion honest: adding a backend action should either bind a
+ * frontend runtime or show up as a projection TODO.
+ */
+export function projectPresentationActionRuntimeBindingDiagnostics<
+  TExecuteContext,
+  TLabel,
+>({
+  actionPlacements,
+  module,
+  runtimes,
+  source,
+}: ProjectPresentationActionRuntimeBindingDiagnosticsOptions<
+  TExecuteContext,
+  TLabel
+>): readonly PresentationProjectionDiagnostic[] {
+  return actionPlacements.flatMap((placement) => {
+    const action = findPresentationAction<ActionDefinition>(module, placement.ActionId)
+    if (!action) {
+      return [
+        {
+          details: {
+            actionId: placement.ActionId,
+            placementIntent: placement.Intent,
+            placementRegion: placement.Region,
+          },
+          id: `action-runtime.${placement.ActionId}.missing-action`,
+          message:
+            `Placed action '${placement.ActionId}' is referenced by the presentation IR ` +
+            'but is not present in the action catalog.',
+          severity: 'error',
+          source,
+          subject: {
+            id: placement.ActionId,
+            kind: 'action',
+          },
+        } satisfies PresentationProjectionDiagnostic,
+      ]
+    }
+
+    const runtime = runtimes[action.Id]
+    if (runtime?.execute) {
+      return []
+    }
+
+    return [
+      createActionRuntimeDiagnostic({
+        action,
+        message:
+          `Action '${action.Name}' is placed in '${placement.Region}' but has no ` +
+          'frontend runtime binding.',
+        placement,
+        reason: 'missing-execute-binding',
+        source,
+      }),
+    ]
+  })
+}
+
+function createActionRuntimeDiagnostic({
+  action,
+  message,
+  placement,
+  reason,
+  source,
+}: {
+  readonly action: ActionDefinition
+  readonly message: string
+  readonly placement: ActionPlacementDefinition
+  readonly reason: string
+  readonly source: string
+}): PresentationProjectionDiagnostic {
+  return {
+    details: {
+      actionId: action.Id,
+      bindingKind: action.Binding.Kind,
+      kind: action.Kind,
+      placementIntent: placement.Intent,
+      placementRegion: placement.Region,
+      scope: action.Scope,
+    },
+    id: `action-runtime.${action.Id}.${reason}`,
+    message,
+    severity: 'warning',
+    source,
+    subject: {
+      id: action.Id,
+      kind: 'action',
+      name: action.Name,
+    },
+  }
+}

package/src/presentation-action-runtime-labels.ts

@@ -0,0 +1,57 @@
+import type {
+  ActionDefinition,
+} from './module'
+import {
+  formatPresentationValue,
+  resolvePresentationValue,
+} from './presentation-value-resolution'
+
+export interface ResolveActionPendingLabelOptions<TLabel> {
+  readonly action: Pick<ActionDefinition, 'RuntimePresentation'> | null | undefined
+  readonly data?: unknown
+  readonly fallback?: TLabel
+}
+
+/**
+ * Resolves a pending action label from presentation IR runtime metadata.
+ *
+ * Label variants are checked before the default pending label, which lets a
+ * process-preview action describe response-dependent labels such as overwrite
+ * vs create without product-specific frontend branches.
+ */
+export function resolveActionPendingLabel<TLabel = string>({
+  action,
+  data,
+  fallback,
+}: ResolveActionPendingLabelOptions<TLabel>): TLabel | undefined {
+  const runtimePresentation = action?.RuntimePresentation
+  const variant = runtimePresentation?.PendingLabelVariants.find((candidate) =>
+    actionRuntimeLabelVariantMatches({
+      data,
+      expectedValue: candidate.ExpectedValue,
+      value: resolvePresentationValue(candidate.Condition, data),
+    }),
+  )
+  const label = variant?.Label ?? runtimePresentation?.PendingLabel
+
+  return label === null || label === undefined || label === ''
+    ? fallback
+    : label as TLabel
+}
+
+function actionRuntimeLabelVariantMatches({
+  data,
+  expectedValue,
+  value,
+}: {
+  readonly data: unknown
+  readonly expectedValue: string
+  readonly value: unknown
+}) {
+  if (data === null || data === undefined) {
+    return false
+  }
+
+  const formatted = formatPresentationValue(value)
+  return formatted?.toLocaleLowerCase() === expectedValue.toLocaleLowerCase()
+}

package/src/presentation-action-runtime-projection.ts

@@ -0,0 +1,67 @@
+import type {
+  PresentationModuleDefinition,
+} from './module'
+import type {
+  PresentationActionRuntime,
+  PresentationActionRuntimeBinding,
+  PresentationActionRuntimeBindingContext,
+} from './presentation-action-runtime-binding'
+
+export type PresentationActionRuntimeRegistry<TExecuteContext, TLabel> = Readonly<
+  Record<string, PresentationActionRuntime<TExecuteContext, TLabel> | null | undefined>
+>
+
+export interface ProjectPresentationActionRuntimeRegistryOptions<
+  TExecuteContext,
+  TLabel,
+> {
+  readonly actionIds?: readonly string[]
+  readonly module: PresentationModuleDefinition | null
+  readonly projections: readonly PresentationActionRuntimeBinding<TExecuteContext, TLabel>[]
+}
+
+/**
+ * Interprets backend-declared actions through ordered frontend runtime
+ * projections.
+ *
+ * The IR owns action identity and semantics; the frontend contributes concrete
+ * local effects by registering projection bindings that match those semantics.
+ */
+export function projectPresentationActionRuntimeRegistry<TExecuteContext, TLabel>({
+  actionIds,
+  module,
+  projections,
+}: ProjectPresentationActionRuntimeRegistryOptions<
+  TExecuteContext,
+  TLabel
+>): PresentationActionRuntimeRegistry<TExecuteContext, TLabel> {
+  if (!module) {
+    return {}
+  }
+
+  const actionsById = new Map(module.Actions.map((action) => [action.Id, action]))
+  const candidateActionIds = actionIds ?? module.Actions.map((action) => action.Id)
+  const registry: Record<
+    string,
+    PresentationActionRuntime<TExecuteContext, TLabel> | null | undefined
+  > = {}
+
+  for (const actionId of new Set(candidateActionIds)) {
+    const action = actionsById.get(actionId)
+    if (!action) {
+      continue
+    }
+
+    const context = { action, actionId, module } satisfies PresentationActionRuntimeBindingContext
+    for (const projection of projections) {
+      if (!projection.matches(context)) {
+        continue
+      }
+
+      registry[actionId] = projection.project(context)
+      break
+    }
+  }
+
+  return registry
+}

package/src/presentation-badge-resolution.ts

@@ -0,0 +1,138 @@
+import {
+  findPresentationField,
+} from './module'
+import type {
+  FieldPresentationDefinition,
+  PresentationBadgeDefinition,
+  PresentationModuleDefinition,
+} from './module'
+import {
+  resolvePresentationContent,
+} from './presentation-content-resolution'
+import {
+  formatPresentationValue,
+  isEmptyPresentationValue,
+  readPresentationFieldValue,
+  resolvePresentationTemplate,
+  resolvePresentationValue,
+} from './presentation-value-resolution'
+
+export interface ResolvedPresentationBadge {
+  readonly id?: string
+  readonly label: string
+  readonly tone?: string | null
+}
+
+export function resolvePresentationBadges(
+  badges: readonly PresentationBadgeDefinition[] | null | undefined,
+  data: unknown,
+  module: Pick<PresentationModuleDefinition, 'Fields'> | null,
+): readonly ResolvedPresentationBadge[] {
+  return badges?.flatMap((badge) =>
+    resolvePresentationBadge(badge, data, module),
+  ) ?? []
+}
+
+function resolvePresentationBadge(
+  badge: PresentationBadgeDefinition,
+  data: unknown,
+  module: Pick<PresentationModuleDefinition, 'Fields'> | null,
+): readonly ResolvedPresentationBadge[] {
+  const field = badge.FieldId
+    ? findPresentationField<FieldPresentationDefinition>(module, badge.FieldId)
+    : null
+  if (badge.FieldId && !field && !badge.Value && !badge.ValueTemplate && !badge.Content) {
+    return []
+  }
+
+  const value = badge.Value
+    ? resolvePresentationValue(badge.Value, data)
+    : readPresentationFieldValue(data, field?.Field)
+  const hasValue = Boolean(badge.Value || field?.Field)
+  if (
+    hasValue &&
+    (
+      (badge.OmitWhenEmpty && isEmptyPresentationValue(value)) ||
+      (badge.OmitWhenZero && isZeroPresentationValue(value))
+    )
+  ) {
+    return []
+  }
+
+  const formattedValue =
+    formatPresentationBadgeFieldValue(value, field) ??
+    formatPresentationValue(value)
+  const label =
+    resolvePresentationBadgeContentLabel(badge, data, field) ??
+    resolvePresentationTemplate(badge.ValueTemplate, data) ??
+    formatFieldBackedBadgeLabel(formattedValue, badge, field) ??
+    badge.Name
+  if (badge.OmitWhenEmpty && isEmptyPresentationValue(label)) {
+    return []
+  }
+
+  return [{
+    id: badge.Id,
+    label,
+    tone: badge.Tone,
+  }]
+}
+
+function formatFieldBackedBadgeLabel(
+  formattedValue: string | null,
+  badge: PresentationBadgeDefinition,
+  field: FieldPresentationDefinition | null,
+) {
+  if (!formattedValue) {
+    return null
+  }
+
+  if (badge.Value || badge.ValueTemplate || !badge.FieldId) {
+    return formattedValue
+  }
+
+  const label = field?.Label ?? badge.Name
+  return label ? `${label}: ${formattedValue}` : formattedValue
+}
+
+function resolvePresentationBadgeContentLabel(
+  badge: PresentationBadgeDefinition,
+  data: unknown,
+  field: FieldPresentationDefinition | null,
+) {
+  const content = badge.Content
+  if (!content) {
+    return null
+  }
+
+  const descriptionValue = resolvePresentationValue(content.Description, data)
+  if (descriptionValue !== undefined && descriptionValue !== null) {
+    return (
+      formatPresentationBadgeFieldValue(descriptionValue, field) ??
+      formatPresentationValue(descriptionValue)
+    )
+  }
+
+  const resolvedContent = resolvePresentationContent(content, data)
+  return resolvedContent.description ?? resolvedContent.title ?? resolvedContent.subtitle
+}
+
+function isZeroPresentationValue(value: unknown) {
+  return value === 0 || value === '0'
+}
+
+function formatPresentationBadgeFieldValue(
+  value: unknown,
+  field: FieldPresentationDefinition | null,
+) {
+  const labels = field?.Display?.ValueLabels
+  if (!labels || value === null || value === undefined) {
+    return null
+  }
+
+  const key = String(value)
+  return labels.find((label) =>
+    label.Value === key ||
+    label.Value.toLocaleLowerCase() === key.toLocaleLowerCase(),
+  )?.Label ?? null
+}