@cohesivesystems/presentation-core 0.1.0-alpha.1

package/src/presentation-action-endpoint-request-projection.ts

@@ -0,0 +1,223 @@
+import type {
+  ActionDefinition,
+  ActionEndpointRequestProjectionDefinition,
+  ActionEndpointRequestValueBindingDefinition,
+  PresentationValueDefinition,
+} from './module'
+import { presentationValueKinds } from '@cohesivesystems/presentation-contracts'
+import {
+  readObjectPath,
+  writeObjectPath,
+} from './object-path'
+import type { EndpointExecutionRequest } from './endpoint-executor'
+
+export type PresentationActionEndpointExecutionRequest<
+  TBody = unknown,
+  TQuery = unknown,
+> = EndpointExecutionRequest<TBody, TQuery>
+
+export interface PresentationActionEndpointRequestProjectionOptions {
+  readonly action: ActionDefinition | null
+  readonly dataSourceId?: string | null
+  readonly endpointId: string
+  readonly sources: Readonly<Record<string, unknown>>
+}
+
+export interface RequiredPresentationActionEndpointRequestProjectionOptions
+  extends PresentationActionEndpointRequestProjectionOptions {
+  readonly actionId: string
+}
+
+/**
+ * Lowers a Presentation IR action endpoint request projection into the concrete
+ * endpoint request envelope used by the app transport.
+ */
+export function projectPresentationActionEndpointRequest({
+  action,
+  dataSourceId,
+  endpointId,
+  sources,
+}: PresentationActionEndpointRequestProjectionOptions): PresentationActionEndpointExecutionRequest | null {
+  const projection = selectActionEndpointRequestProjection({
+    action,
+    dataSourceId,
+    endpointId,
+  })
+  if (!projection) {
+    return null
+  }
+
+  return {
+    body: projectRequestBody(projection.BodyFields, sources),
+    routeParameters: projectRouteParameters(projection.RouteParameters, sources),
+  }
+}
+
+/**
+ * Projects a required action endpoint request, failing early when the action
+ * lacks an endpoint request projection for the selected endpoint/data source.
+ */
+export function projectRequiredPresentationActionEndpointRequest({
+  action,
+  actionId,
+  dataSourceId,
+  endpointId,
+  sources,
+}: RequiredPresentationActionEndpointRequestProjectionOptions): PresentationActionEndpointExecutionRequest {
+  const request = projectPresentationActionEndpointRequest({
+    action,
+    dataSourceId,
+    endpointId,
+    sources,
+  })
+  if (!request) {
+    throw new Error(
+      `No endpoint request projection is registered for action '${actionId}' and endpoint '${endpointId}'.`,
+    )
+  }
+
+  return request
+}
+
+function selectActionEndpointRequestProjection({
+  action,
+  dataSourceId,
+  endpointId,
+}: {
+  readonly action: ActionDefinition | null
+  readonly dataSourceId?: string | null
+  readonly endpointId: string
+}): ActionEndpointRequestProjectionDefinition | null {
+  const endpointRequests = action?.EndpointRequests ?? []
+  const endpointMatches = endpointRequests.filter((candidate) =>
+    candidate.EndpointId === endpointId,
+  )
+  if (!dataSourceId && endpointMatches.length === 1) {
+    return endpointMatches[0]
+  }
+
+  return endpointRequests.find((candidate) =>
+    candidate.EndpointId === endpointId && candidate.DataSourceId === dataSourceId,
+  ) ??
+    endpointRequests.find((candidate) =>
+      candidate.EndpointId === endpointId && !candidate.DataSourceId,
+    ) ??
+    endpointRequests.find((candidate) =>
+      !candidate.EndpointId && candidate.DataSourceId === dataSourceId,
+    ) ??
+    endpointRequests.find((candidate) =>
+      !candidate.EndpointId && !candidate.DataSourceId,
+    ) ??
+    null
+}
+
+function projectRouteParameters(
+  bindings: readonly ActionEndpointRequestValueBindingDefinition[],
+  sources: Readonly<Record<string, unknown>>,
+) {
+  return Object.fromEntries(
+    bindings.flatMap((binding) => {
+      const value =
+        resolvePresentationActionRequestValue(binding.Source, sources) ??
+        resolveFallbackRouteParameterValue(binding.TargetPath, sources)
+      if ((value === null || value === undefined) && binding.OmitWhenNull) {
+        return []
+      }
+
+      return [[binding.TargetPath, value == null ? value : String(value)]]
+    }),
+  )
+}
+
+function resolveFallbackRouteParameterValue(
+  targetPath: string,
+  sources: Readonly<Record<string, unknown>>,
+) {
+  if (targetPath !== 'id') {
+    return undefined
+  }
+
+  return readObjectPath(sources, 'route.id') ?? readObjectPath(sources, 'resource.Id')
+}
+
+function projectRequestBody(
+  bindings: readonly ActionEndpointRequestValueBindingDefinition[],
+  sources: Readonly<Record<string, unknown>>,
+) {
+  if (bindings.length === 0) {
+    return undefined
+  }
+
+  const body: Record<string, unknown> = {}
+  for (const binding of bindings) {
+    const resolvedValue = resolvePresentationActionRequestValue(binding.Source, sources)
+    const value = resolvedValue === undefined
+      ? resolveFallbackRequestBodyValue(binding.TargetPath, sources)
+      : resolvedValue
+    if ((value === null || value === undefined) && binding.OmitWhenNull) {
+      continue
+    }
+
+    if (value === undefined && isDocumentRequestBodyTarget(binding.TargetPath)) {
+      throw new Error(
+        `Unable to project request body field '${binding.TargetPath}' because its source did not resolve.`,
+      )
+    }
+
+    writeObjectPath(body, binding.TargetPath, value)
+  }
+
+  return body
+}
+
+function resolveFallbackRequestBodyValue(
+  targetPath: string,
+  sources: Readonly<Record<string, unknown>>,
+) {
+  if (!isDocumentRequestBodyTarget(targetPath)) {
+    return undefined
+  }
+
+  const documentValue = readObjectPath(sources, 'document.value')
+  if (documentValue !== undefined) {
+    return documentValue
+  }
+
+  return readObjectPath(sources, 'document.Document')
+}
+
+function isDocumentRequestBodyTarget(targetPath: string) {
+  return targetPath.toLowerCase() === 'document'
+}
+
+function resolvePresentationActionRequestValue(
+  value: PresentationValueDefinition,
+  sources: Readonly<Record<string, unknown>>,
+) {
+  if (isPresentationValueKind(value.Kind, presentationValueKinds.literal, 'literal')) {
+    return value.Literal
+  }
+
+  if (isPresentationValueKind(value.Kind, presentationValueKinds.field, 'field')) {
+    return value.Field ? readObjectPath(sources, value.Field) : undefined
+  }
+
+  if (isPresentationValueKind(value.Kind, presentationValueKinds.state, 'state')) {
+    return value.StateId ? sources[value.StateId] : undefined
+  }
+
+  if (isPresentationValueKind(value.Kind, presentationValueKinds.expression, 'expression')) {
+    throw new Error('Action endpoint request expression values are not supported yet.')
+  }
+
+  return undefined
+}
+
+function isPresentationValueKind(
+  value: unknown,
+  numericKind: number,
+  stringKind: string,
+) {
+  return value === numericKind ||
+    (typeof value === 'string' && value.toLowerCase() === stringKind.toLowerCase())
+}

package/src/presentation-action-endpoint.ts

@@ -0,0 +1,130 @@
+import {
+  findPresentationAction,
+  type PresentationBindingDefinition,
+  type PresentationModuleDefinition,
+} from './module'
+import {
+  createPresentationEnumDiscriminator,
+  matchesPresentationEnum,
+  type PresentationEnumDiscriminator,
+} from './target-bindings'
+import {
+  presentationBindingKinds,
+  presentationTargetKinds,
+} from '@cohesivesystems/presentation-contracts'
+
+interface PresentationTargetBindingProjection {
+  readonly Bindings: readonly PresentationBindingDefinition[]
+  readonly ComponentSet?: string | null
+  readonly Target: string | number
+}
+
+export interface ResolvePresentationActionEndpointBindingOptions {
+  readonly actionId: string
+  readonly componentSet?: string | null
+  readonly dataSourceId?: string | null
+  readonly module: Pick<PresentationModuleDefinition, 'Actions'> & {
+    readonly Targets?: readonly PresentationTargetBindingProjection[]
+  } | null
+  readonly targetKind?: PresentationEnumDiscriminator | null
+}
+
+/**
+ * Resolves the concrete endpoint that realizes a semantic action for the
+ * current projection target. Target bindings can specialize an action by data
+ * source while the action definition remains semantic and reusable.
+ */
+export function resolvePresentationActionEndpointBinding({
+  actionId,
+  componentSet,
+  dataSourceId,
+  module,
+  targetKind = createPresentationEnumDiscriminator(presentationTargetKinds, 'react', 'React'),
+}: ResolvePresentationActionEndpointBindingOptions): PresentationBindingDefinition | null {
+  if (!module) {
+    return null
+  }
+  return (
+    resolveActionEndpointTargetBinding({
+      actionId,
+      componentSet,
+      dataSourceId,
+      module,
+      targetKind,
+    }) ??
+    resolveActionDefinitionEndpointBinding(module, actionId) ??
+    null
+  )
+}
+
+function resolveActionEndpointTargetBinding({
+  actionId,
+  componentSet,
+  dataSourceId,
+  module,
+  targetKind,
+}: ResolvePresentationActionEndpointBindingOptions): PresentationBindingDefinition | null {
+  const targets = resolveCandidateTargets(module?.Targets ?? [], {
+    componentSet,
+    targetKind,
+  })
+  const bindings = targets
+    .flatMap((target) => target.Bindings)
+    .filter(
+      (binding) =>
+        matchesPresentationEnum(binding.Kind, actionEndpointBindingKind) &&
+        binding.Id === actionId,
+    )
+
+  return (
+    bindings.find((binding) => dataSourceId && binding.DataSourceId === dataSourceId) ??
+    bindings.find((binding) => !binding.DataSourceId) ??
+    bindings[0] ??
+    null
+  )
+}
+
+function resolveActionDefinitionEndpointBinding(
+  module: Pick<PresentationModuleDefinition, 'Actions'>,
+  actionId: string,
+): PresentationBindingDefinition | null {
+  const binding = findPresentationAction(module, actionId)?.Binding ?? null
+  return binding && isEndpointBinding(binding) ? binding : null
+}
+
+function resolveCandidateTargets(
+  targets: readonly PresentationTargetBindingProjection[],
+  {
+    componentSet,
+    targetKind,
+  }: Pick<ResolvePresentationActionEndpointBindingOptions, 'componentSet' | 'targetKind'>,
+) {
+  const filteredTargets = targets.filter((target) => {
+    if (targetKind && !matchesPresentationEnum(target.Target, targetKind)) {
+      return false
+    }
+
+    return !componentSet || target.ComponentSet === componentSet
+  })
+
+  return filteredTargets.length > 0 ? filteredTargets : targets
+}
+
+function isEndpointBinding(binding: PresentationBindingDefinition) {
+  return (
+    matchesPresentationEnum(binding.Kind, actionEndpointBindingKind) ||
+    matchesPresentationEnum(binding.Kind, apiEndpointBindingKind)
+  )
+}
+
+const actionEndpointBindingKind = createPresentationEnumDiscriminator(
+  presentationBindingKinds,
+  'actionEndpoint',
+  'ActionEndpoint',
+)
+
+const apiEndpointBindingKind = createPresentationEnumDiscriminator(
+  presentationBindingKinds,
+  'apiEndpoint',
+  'ApiEndpoint',
+)

package/src/presentation-action-icons.ts

@@ -0,0 +1,3 @@
+export const presentationActionIconIds = {
+  pending: 'action.pending',
+} as const

package/src/presentation-action-result-state.ts

@@ -0,0 +1,189 @@
+import {
+  actionResultStateWriteModes,
+  type ActionResultPolicy,
+  type ActionResultStateWriteDefinition,
+  type ActionResultStateWriteMode,
+} from '@cohesivesystems/presentation-contracts'
+
+import {
+  readObjectPath,
+} from './object-path'
+
+/**
+ * Route-scoped presentation state keyed by semantic data-source id.
+ *
+ * Values in this map are action outputs, or values derived from action outputs,
+ * that should be projected as local data-source values until the route scope is
+ * reset.
+ */
+export type PresentationActionResultStateValues = Readonly<Record<string, unknown>>
+
+/**
+ * Inputs for applying explicit action-result state writes.
+ */
+export interface ApplyPresentationActionResultStateWritesOptions {
+  /** Action endpoint response used as the source value for each write. */
+  readonly result: unknown
+
+  /** Current route-scoped action-result state. */
+  readonly state: PresentationActionResultStateValues
+
+  /** State-write declarations to apply. */
+  readonly writes?: readonly ActionResultStateWriteDefinition[] | null
+}
+
+/**
+ * Inputs for applying the state-write policy declared by an action result.
+ */
+export interface ApplyPresentationActionResultPolicyStateWritesOptions {
+  /** Action result policy that declares state writes, when one is present. */
+  readonly policy?: ActionResultPolicy | null
+
+  /** Action endpoint response used as the source value for each policy write. */
+  readonly result: unknown
+
+  /** Current route-scoped action-result state. */
+  readonly state: PresentationActionResultStateValues
+}
+
+/**
+ * Applies the state writes declared by an action result policy.
+ *
+ * The returned state preserves object identity when the policy has no writes,
+ * which lets React callers avoid unnecessary rebinding work.
+ */
+export function applyPresentationActionResultPolicyStateWrites({
+  policy,
+  result,
+  state,
+}: ApplyPresentationActionResultPolicyStateWritesOptions) {
+  return applyPresentationActionResultStateWrites({
+    result,
+    state,
+    writes: policy?.StateWrites,
+  })
+}
+
+/**
+ * Applies backend-declared action response writes to route-local presentation
+ * data-source state.
+ *
+ * Each write targets a semantic data-source id and reads either the full action
+ * response or a dot-separated response path. The function returns a new state
+ * object only when at least one valid write is applied.
+ */
+export function applyPresentationActionResultStateWrites({
+  result,
+  state,
+  writes,
+}: ApplyPresentationActionResultStateWritesOptions): PresentationActionResultStateValues {
+  if (!writes?.length) {
+    return state
+  }
+
+  let next: Record<string, unknown> | null = null
+  for (const write of writes) {
+    if (!write.TargetDataSourceId) {
+      continue
+    }
+
+    next ??= { ...state }
+    applyPresentationActionResultStateWrite(next, write, result)
+  }
+
+  return next ?? state
+}
+
+/**
+ * Applies a single write declaration to a mutable state accumulator.
+ */
+function applyPresentationActionResultStateWrite(
+  state: Record<string, unknown>,
+  write: ActionResultStateWriteDefinition,
+  result: unknown,
+) {
+  const mode = normalizeActionResultStateWriteMode(write.Mode)
+  if (mode === 'clear') {
+    delete state[write.TargetDataSourceId]
+    return
+  }
+
+  const value = write.SourcePath ? readObjectPath(result, write.SourcePath) : result
+  switch (mode) {
+    case 'append':
+      state[write.TargetDataSourceId] = appendPresentationStateValue(
+        state[write.TargetDataSourceId],
+        value,
+      )
+      return
+    case 'merge':
+      state[write.TargetDataSourceId] = mergePresentationStateValue(
+        state[write.TargetDataSourceId],
+        value,
+      )
+      return
+    case 'replace':
+    default:
+      state[write.TargetDataSourceId] = value
+      return
+  }
+}
+
+/**
+ * Appends one scalar or array-valued write source to the current target value.
+ */
+function appendPresentationStateValue(current: unknown, value: unknown) {
+  const currentItems = Array.isArray(current) ? current : current === undefined ? [] : [current]
+  const nextItems = Array.isArray(value) ? value : [value]
+  return [...currentItems, ...nextItems]
+}
+
+/**
+ * Merges object writes shallowly and falls back to replacement for non-objects.
+ */
+function mergePresentationStateValue(current: unknown, value: unknown) {
+  if (isRecord(current) && isRecord(value)) {
+    return {
+      ...current,
+      ...value,
+    }
+  }
+
+  return value
+}
+
+/**
+ * Narrows values that can participate in shallow merge writes.
+ */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}
+
+/**
+ * Normalizes generated numeric enum values and JSON string enum values into the
+ * runtime write-mode labels used by the state applicator.
+ */
+function normalizeActionResultStateWriteMode(
+  mode: ActionResultStateWriteMode | string,
+): 'replace' | 'merge' | 'append' | 'clear' {
+  if (mode === actionResultStateWriteModes.merge || matchesModeLabel(mode, 'merge')) {
+    return 'merge'
+  }
+
+  if (mode === actionResultStateWriteModes.append || matchesModeLabel(mode, 'append')) {
+    return 'append'
+  }
+
+  if (mode === actionResultStateWriteModes.clear || matchesModeLabel(mode, 'clear')) {
+    return 'clear'
+  }
+
+  return 'replace'
+}
+
+/**
+ * Compares a generated JSON enum label case-insensitively.
+ */
+function matchesModeLabel(value: unknown, label: string) {
+  return typeof value === 'string' && value.toLocaleLowerCase() === label
+}