@cohesivesystems/presentation-core 0.1.0-alpha.1

package/src/projected-document-workspace-data-source-bindings.ts

@@ -0,0 +1,182 @@
+import {
+  projectDocumentProfileDataSourceBindings,
+  type DocumentWorkspaceProfileProjection,
+} from './document-module'
+import type { PresentationModuleDefinition } from './module'
+import {
+  createApiEndpointTanStackQueryDataSourceBindingProjectionRegistry,
+  type PresentationDataSourceApiEndpointFactoryContext,
+  type PresentationDataSourceEndpointExecutor,
+  type PresentationDataSourceTargetInterpretation,
+} from './data-source-projection'
+import {
+  type PresentationDataSourceAuthorizationRequirement,
+  type PresentationDataSourceBinding,
+} from './presentation-data-source-binding-model'
+import {
+  documentDataSourceRoles,
+  type DocumentDataSourceRole,
+} from '@cohesivesystems/presentation-contracts'
+
+const defaultDocumentWorkspaceDataSourceRoles = [
+  documentDataSourceRoles.resource,
+  documentDataSourceRoles.metadata,
+] as const
+const emptyQueryKeyParts = [] as const
+
+/**
+ * Runtime subset required to decide which profile-scoped data sources are
+ * active for the current document workspace projection.
+ */
+export interface DocumentWorkspaceDataSourceRuntimeState {
+  readonly activeLayoutModeId: string
+  readonly activeProjectionId: string | null
+  readonly activeViewId: string | null
+  readonly projectionViewIds: readonly string[]
+}
+
+/** Context used to create stable cache keys for document workspace data sources. */
+export interface DocumentWorkspaceDataSourceQueryKeyContext {
+  readonly dataSourceId: string
+  readonly queryKeyParts: readonly unknown[]
+  readonly resourceId: string
+  readonly routeParameters: Readonly<Record<string, string | null | undefined>>
+}
+
+/** Creates a cache key for a projected document workspace data source. */
+export type DocumentWorkspaceDataSourceQueryKeyFactory = (
+  context: DocumentWorkspaceDataSourceQueryKeyContext,
+) => readonly unknown[]
+
+/** Options for projecting a document profile's load-time data sources. */
+export interface ProjectDocumentWorkspaceDataSourceBindingsOptions {
+  /** Authorization applied to API-backed document workspace data sources when no target interpretation supplies it. */
+  readonly authorization?: PresentationDataSourceAuthorizationRequirement
+  /** Cache-key factory supplied by the app/runtime cache domain. */
+  readonly createQueryKey?: DocumentWorkspaceDataSourceQueryKeyFactory
+  /** Concrete endpoint executor for API-backed presentation data sources when no target interpretation supplies it. */
+  readonly executeEndpoint?: PresentationDataSourceEndpointExecutor
+  /** Optional app-level enablement predicate layered over route-parameter checks. */
+  readonly isEnabled?: (context: PresentationDataSourceApiEndpointFactoryContext) => boolean
+  /** Presentation module containing canonical data-source definitions. */
+  readonly module: PresentationModuleDefinition | null
+  /** Projected document workspace profile whose data sources should be bound. */
+  readonly projection: Pick<DocumentWorkspaceProfileProjection, 'dataSourceId' | 'profile'>
+  /** Additional cache-key parts, such as auth or tenant scope. */
+  readonly queryKeyParts?: readonly unknown[]
+  /** Concrete document resource id from the current route. */
+  readonly resourceId: string
+  /** Route parameter name used by document resource endpoints. */
+  readonly resourceRouteParameterName?: string
+  /** Data-source roles to bind; defaults to resource and metadata. */
+  readonly roles?: readonly DocumentDataSourceRole[]
+  /** Current document workspace runtime state used for activation policies. */
+  readonly runtime: DocumentWorkspaceDataSourceRuntimeState
+  /** Target-level interpretation for data-source execution and authorization semantics. */
+  readonly targetInterpretation?: PresentationDataSourceTargetInterpretation
+}
+
+/** Result of projecting document workspace data-source bindings. */
+export interface ProjectDocumentWorkspaceDataSourceBindingsResult {
+  readonly bindings: readonly PresentationDataSourceBinding[]
+  readonly resourceQueryKey: readonly unknown[]
+}
+
+/**
+ * Projects a document workspace profile's load-time data sources to concrete
+ * frontend bindings.
+ *
+ * The backend declares which data sources exist and when they are active. This
+ * helper contributes the reusable document-workspace interpretation: route
+ * parameter wiring, active-view activation, API endpoint binding, cache-key
+ * creation, and primary resource query-key exposure for downstream mutations.
+ */
+export function projectDocumentWorkspaceDataSourceBindings({
+  authorization,
+  createQueryKey = createDocumentWorkspaceDataSourceQueryKey,
+  executeEndpoint,
+  isEnabled,
+  module,
+  projection,
+  queryKeyParts = emptyQueryKeyParts,
+  resourceId,
+  resourceRouteParameterName = 'id',
+  roles = defaultDocumentWorkspaceDataSourceRoles,
+  runtime,
+  targetInterpretation,
+}: ProjectDocumentWorkspaceDataSourceBindingsOptions): ProjectDocumentWorkspaceDataSourceBindingsResult {
+  const routeParameters = {
+    [resourceRouteParameterName]: resourceId,
+  } satisfies Readonly<Record<string, string>>
+  const registry = createApiEndpointTanStackQueryDataSourceBindingProjectionRegistry({
+    createQueryKey: ({ dataSource, routeParameters }) =>
+      createQueryKey({
+        dataSourceId: dataSource.Id,
+        queryKeyParts,
+        resourceId,
+        routeParameters,
+      }),
+    defaultAuthorization: authorization && !targetInterpretation
+      ? () => authorization
+      : undefined,
+    executeEndpoint,
+    isEnabled: createDocumentWorkspaceDataSourceEnabledPredicate(resourceId, isEnabled),
+    pendingLabel: ({ dataSource }) =>
+      dataSource.Id === projection.dataSourceId
+        ? 'Loading document...'
+        : `Loading ${dataSource.Name.toLocaleLowerCase()}...`,
+    retry: false,
+    targetInterpretation,
+  })
+
+  return {
+    bindings: projectDocumentProfileDataSourceBindings({
+      activation: {
+        activeLayoutModeId: runtime.activeLayoutModeId,
+        activeProjectionId: runtime.activeProjectionId,
+        activeViewId: resolveActiveDocumentViewId(runtime),
+        routeParameters,
+      },
+      context: {
+        routeParameters,
+        queryKeyParts,
+      },
+      module,
+      profile: projection.profile,
+      registry,
+      roles,
+    }),
+    resourceQueryKey: createQueryKey({
+      dataSourceId: projection.dataSourceId,
+      queryKeyParts,
+      resourceId,
+      routeParameters,
+    }),
+  }
+}
+
+/** Default cache key for document workspace data sources when an app does not supply one. */
+export function createDocumentWorkspaceDataSourceQueryKey({
+  dataSourceId,
+  queryKeyParts,
+  resourceId,
+}: DocumentWorkspaceDataSourceQueryKeyContext) {
+  return ['document-workspace', dataSourceId, resourceId, ...queryKeyParts] as const
+}
+
+function createDocumentWorkspaceDataSourceEnabledPredicate(
+  resourceId: string,
+  isEnabled: ProjectDocumentWorkspaceDataSourceBindingsOptions['isEnabled'],
+) {
+  if (resourceId.length === 0) {
+    return () => false
+  }
+
+  return isEnabled
+}
+
+function resolveActiveDocumentViewId(runtime: DocumentWorkspaceDataSourceRuntimeState) {
+  return runtime.activeViewId && runtime.projectionViewIds.includes(runtime.activeViewId)
+    ? runtime.activeViewId
+    : (runtime.projectionViewIds[0] ?? '')
+}

package/src/projected-document-workspace-notice-diagnostics.ts

@@ -0,0 +1,41 @@
+import type { DocumentProfileProjection } from './document-module'
+import type {
+  PresentationModuleDefinition,
+  ProcessTaskSelectorDefinition,
+} from './module'
+import {
+  projectDocumentActionStatusNoticeDiagnostics,
+} from './projected-document-action-status-notice-diagnostics'
+import {
+  projectProcessTaskNoticeDiagnostics,
+} from './projected-process-task-notice-diagnostics'
+import type {
+  ProcessTaskSelector,
+} from './process-task-model'
+
+export interface ProjectDocumentWorkspaceNoticeDiagnosticsOptions<TContext> {
+  readonly context: TContext
+  readonly module: Pick<PresentationModuleDefinition, 'Actions' | 'Fields'> | null
+  readonly profile: Pick<
+    DocumentProfileProjection,
+    'ActionStatusNotices' | 'ProcessTaskNotices' | 'ProcessTaskSelectors'
+  > | null
+  readonly projectSelector: (
+    selector: ProcessTaskSelectorDefinition | null | undefined,
+    context: TContext,
+  ) => ProcessTaskSelector | null
+  readonly region?: string
+}
+
+export function projectDocumentWorkspaceNoticeDiagnostics<TContext>(
+  options: ProjectDocumentWorkspaceNoticeDiagnosticsOptions<TContext>,
+) {
+  return [
+    ...projectDocumentActionStatusNoticeDiagnostics({
+      module: options.module,
+      profile: options.profile,
+      region: options.region,
+    }),
+    ...projectProcessTaskNoticeDiagnostics(options),
+  ]
+}

package/src/projected-input-form-runtime.ts

@@ -0,0 +1,86 @@
+import type {
+  ActionDefinition,
+  ActionPlacementDefinition,
+  DataSourceQueryDefinition,
+  InputFormDefinition,
+  QueryFormDefinition,
+} from './module'
+
+/**
+ * Caller-owned state and commands used by a projected input form.
+ *
+ * The form renderer owns generic control projection. The host owns how a placed
+ * action interprets the current draft value for a query, transition, process,
+ * endpoint request, enrichment request, or local state update.
+ *
+ * @typeParam TValue - Shape of the caller-owned form state object.
+ */
+export interface ProjectedInputFormRuntime<TValue extends object = object> {
+  /** Invokes a form action against the current draft value. */
+  readonly invokeAction: (context: ProjectedInputFormActionContext<TValue>) => void
+
+  /** Updates the caller-owned form value, preserving React set-state semantics. */
+  readonly setValue: (
+    update: TValue | ((current: TValue) => TValue),
+    context?: ProjectedInputFormValueChangeContext<TValue>,
+  ) => void
+
+  /** Current caller-owned form value. */
+  readonly value: TValue
+}
+
+/**
+ * Target interpretation attached to the projected input form.
+ */
+export interface ProjectedInputFormTargetContext {
+  /** Optional relation-query field metadata used when a query form specializes this input form. */
+  readonly queryDefinition?: DataSourceQueryDefinition | null
+
+  /** Optional query-form specialization over this input form. */
+  readonly queryForm?: QueryFormDefinition | null
+
+  /** Shared or target state id affected by the input form. */
+  readonly stateId: string
+}
+
+/**
+ * Semantic and runtime state passed to input-form action handlers.
+ *
+ * @typeParam TValue - Shape of the caller-owned form state object.
+ */
+export interface ProjectedInputFormActionContext<TValue extends object = object> {
+  /** Presentation action resolved from the action placement, when available. */
+  readonly action: ActionDefinition | null
+
+  /** Available choice values for each input-form field id at the time of action. */
+  readonly choiceValuesByFieldId: Readonly<Record<string, readonly string[]>>
+
+  /** Input form that declares groups, fields, and action placements. */
+  readonly inputForm: InputFormDefinition
+
+  /** Action placement selected by the user. */
+  readonly placement: ActionPlacementDefinition
+
+  /** Target interpretation attached to this form instance. */
+  readonly target: ProjectedInputFormTargetContext
+
+  /** Current caller-owned form value. */
+  readonly value: TValue
+}
+
+/**
+ * Semantic context supplied when a field changes the caller-owned form value.
+ */
+export interface ProjectedInputFormValueChangeContext<TValue extends object = object> {
+  /** Available choice values for each input-form field id at the time of change. */
+  readonly choiceValuesByFieldId: Readonly<Record<string, readonly string[]>>
+
+  /** Input form that declares groups, fields, and action placements. */
+  readonly inputForm: InputFormDefinition
+
+  /** Target interpretation attached to this form instance. */
+  readonly target: ProjectedInputFormTargetContext
+
+  /** Current caller-owned form value before the field update is applied. */
+  readonly value: TValue
+}

package/src/projected-process-task-notice-diagnostics.ts

@@ -0,0 +1,283 @@
+import type { DocumentProfileProjection } from './document-module'
+import {
+  findPresentationAction,
+  findPresentationField,
+} from './module'
+import type {
+  DocumentProcessTaskNoticeDefinition,
+  FieldPresentationDefinition,
+  PresentationModuleDefinition,
+  ProcessTaskSelectorDefinition,
+} from './module'
+import type {
+  PresentationProjectionDiagnostic,
+} from './presentation-projection-diagnostics'
+import {
+  projectPresentationContentDiagnostics,
+} from './presentation-content-diagnostics'
+import type {
+  ProcessTaskSelector,
+} from './process-task-model'
+
+export interface ProjectProcessTaskNoticeDiagnosticsOptions<TContext> {
+  readonly context: TContext
+  readonly module: Pick<PresentationModuleDefinition, 'Actions' | 'Fields'> | null
+  readonly profile: Pick<
+    DocumentProfileProjection,
+    'ProcessTaskNotices' | 'ProcessTaskSelectors'
+  > | null
+  readonly projectSelector: (
+    selector: ProcessTaskSelectorDefinition | null | undefined,
+    context: TContext,
+  ) => ProcessTaskSelector | null
+  readonly region?: string
+}
+
+export function projectProcessTaskNoticeDiagnostics<TContext>({
+  context,
+  module,
+  profile,
+  projectSelector,
+  region,
+}: ProjectProcessTaskNoticeDiagnosticsOptions<TContext>): readonly PresentationProjectionDiagnostic[] {
+  return getRegionProcessTaskNotices(profile, region).flatMap((notice) => {
+    const diagnostics: PresentationProjectionDiagnostic[] = [
+      ...projectProcessTaskNoticeContentDiagnostics(notice),
+      ...projectProcessTaskNoticeStatusFieldDiagnostics(module, notice),
+      ...projectProcessTaskNoticeActionDiagnostics(module, notice),
+    ]
+    const selectorDefinition = findProcessTaskSelectorDefinition(
+      profile,
+      notice.ProcessTaskSelectorId,
+    )
+    if (!selectorDefinition) {
+      diagnostics.push(
+        createProcessTaskNoticeDiagnostic({
+          message:
+            `Process task notice '${notice.Name}' references selector ` +
+            `'${notice.ProcessTaskSelectorId}', but the document profile does not define it.`,
+          notice,
+          reason: 'missing-selector',
+          severity: 'error',
+        }),
+      )
+      return diagnostics
+    }
+
+    const selector = projectSelector(selectorDefinition, context)
+    if (!selector) {
+      diagnostics.push(
+        createProcessTaskNoticeDiagnostic({
+          message:
+            `Process task notice '${notice.Name}' uses selector ` +
+            `'${selectorDefinition.Name}', but this frontend context cannot project it.`,
+          notice,
+          reason: 'unprojectable-selector',
+          severity: 'warning',
+        }),
+      )
+      return diagnostics
+    }
+
+    return diagnostics
+  })
+}
+
+function projectProcessTaskNoticeContentDiagnostics(
+  notice: DocumentProcessTaskNoticeDefinition,
+): readonly PresentationProjectionDiagnostic[] {
+  return projectPresentationContentDiagnostics({
+    content: notice.Content,
+    contentFallbackDescription: 'local process title and status text fallback semantics',
+    descriptionFallbackDescription: 'local process status text fallback semantics',
+    details: createProcessTaskNoticeDiagnosticDetails(notice),
+    diagnosticIdPrefix: `process-task-notice.${notice.Id}.content`,
+    requireDescription: true,
+    requireTitle: true,
+    source: 'document-workspace-notice-projection',
+    subject: createProcessTaskNoticeDiagnosticSubject(notice),
+    surfaceLabel: `Process task notice '${notice.Name}'`,
+    titleFallbackDescription: 'the local process task title',
+  })
+}
+
+function projectProcessTaskNoticeActionDiagnostics(
+  module: Pick<PresentationModuleDefinition, 'Actions'> | null,
+  notice: DocumentProcessTaskNoticeDefinition,
+): readonly PresentationProjectionDiagnostic[] {
+  if (notice.Actions.length === 0) {
+    return [
+      createProcessTaskNoticeDiagnostic({
+        message:
+          `Process task notice '${notice.Name}' does not declare actions; ` +
+          'the frontend will use local process detail navigation fallback semantics.',
+        notice,
+        reason: 'missing-actions',
+        severity: 'warning',
+      }),
+    ]
+  }
+
+  return notice.Actions.flatMap((action) => {
+    const diagnostics: PresentationProjectionDiagnostic[] = []
+
+    if (!findPresentationAction(module, action.Placement.ActionId)) {
+      diagnostics.push(
+        createProcessTaskNoticeDiagnostic({
+          message:
+            `Process task notice '${notice.Name}' references action ` +
+            `'${action.Placement.ActionId}', but the presentation module does not define it.`,
+          notice,
+          reason: `missing-action.${action.Placement.ActionId}`,
+          severity: 'warning',
+        }),
+      )
+    }
+
+    if (!action.Placement.Icon) {
+      diagnostics.push(
+        createProcessTaskNoticeDiagnostic({
+          message:
+            `Process task notice '${notice.Name}' action '${action.Placement.ActionId}' ` +
+            'does not declare an icon.',
+          notice,
+          reason: `missing-action-icon.${action.Placement.ActionId}`,
+          severity: 'warning',
+        }),
+      )
+    }
+
+    if (action.TargetPreference.length === 0) {
+      diagnostics.push(
+        createProcessTaskNoticeDiagnostic({
+          message:
+            `Process task notice '${notice.Name}' action '${action.Placement.ActionId}' ` +
+            'does not declare process-task link target preferences.',
+          notice,
+          reason: `missing-action-targets.${action.Placement.ActionId}`,
+          severity: 'warning',
+        }),
+      )
+    }
+
+    return diagnostics
+  })
+}
+
+function projectProcessTaskNoticeStatusFieldDiagnostics(
+  module: Pick<PresentationModuleDefinition, 'Fields'> | null,
+  notice: DocumentProcessTaskNoticeDefinition,
+): readonly PresentationProjectionDiagnostic[] {
+  if (!notice.StatusFieldId) {
+    return [
+      createProcessTaskNoticeDiagnostic({
+        message:
+          `Process task notice '${notice.Name}' does not declare a status field; ` +
+          'the frontend will use local process status icon and tone fallback semantics.',
+        notice,
+        reason: 'missing-status-field',
+        severity: 'warning',
+      }),
+    ]
+  }
+
+  const field = findPresentationField<FieldPresentationDefinition>(module, notice.StatusFieldId)
+  if (!field) {
+    return [
+      createProcessTaskNoticeDiagnostic({
+        message:
+          `Process task notice '${notice.Name}' references status field ` +
+          `'${notice.StatusFieldId}', but the presentation module does not define it.`,
+        notice,
+        reason: 'missing-status-field-definition',
+        severity: 'warning',
+      }),
+    ]
+  }
+
+  const diagnostics: PresentationProjectionDiagnostic[] = []
+
+  if ((field.Display?.ValueIcons?.length ?? 0) === 0) {
+    diagnostics.push(
+      createProcessTaskNoticeDiagnostic({
+        message:
+          `Process task notice '${notice.Name}' uses status field '${notice.StatusFieldId}', ` +
+          'but that field does not declare value icons; the frontend will use local fallback semantics.',
+        notice,
+        reason: 'status-field-without-value-icons',
+        severity: 'warning',
+      }),
+    )
+  }
+
+  if ((field.Display?.ValueTones?.length ?? 0) === 0) {
+    diagnostics.push(
+      createProcessTaskNoticeDiagnostic({
+        message:
+          `Process task notice '${notice.Name}' uses status field '${notice.StatusFieldId}', ` +
+          'but that field does not declare value tones; the frontend will use local fallback semantics.',
+        notice,
+        reason: 'status-field-without-value-tones',
+        severity: 'warning',
+      }),
+    )
+  }
+
+  return diagnostics
+}
+
+function getRegionProcessTaskNotices(
+  profile: Pick<DocumentProfileProjection, 'ProcessTaskNotices'> | null,
+  region?: string,
+) {
+  return profile?.ProcessTaskNotices?.filter((notice) => !region || notice.Region === region) ?? []
+}
+
+function findProcessTaskSelectorDefinition(
+  profile: Pick<DocumentProfileProjection, 'ProcessTaskSelectors'> | null,
+  selectorId: string,
+) {
+  return profile?.ProcessTaskSelectors?.find((selector) => selector.Id === selectorId) ?? null
+}
+
+function createProcessTaskNoticeDiagnostic({
+  message,
+  notice,
+  reason,
+  severity,
+}: {
+  readonly message: string
+  readonly notice: DocumentProcessTaskNoticeDefinition
+  readonly reason: string
+  readonly severity: PresentationProjectionDiagnostic['severity']
+}): PresentationProjectionDiagnostic {
+  return {
+    details: createProcessTaskNoticeDiagnosticDetails(notice),
+    id: `process-task-notice.${notice.Id}.${reason}`,
+    message,
+    severity,
+    source: 'document-workspace-notice-projection',
+    subject: createProcessTaskNoticeDiagnosticSubject(notice),
+  }
+}
+
+function createProcessTaskNoticeDiagnosticDetails(
+  notice: DocumentProcessTaskNoticeDefinition,
+) {
+  return {
+    noticeId: notice.Id,
+    processTaskSelectorId: notice.ProcessTaskSelectorId,
+    region: notice.Region,
+    statusFieldId: notice.StatusFieldId,
+  }
+}
+
+function createProcessTaskNoticeDiagnosticSubject(
+  notice: DocumentProcessTaskNoticeDefinition,
+) {
+  return {
+    id: notice.Id,
+    kind: 'document-process-task-notice',
+    name: notice.Name,
+  }
+}

package/src/projected-query-form-runtime.ts

@@ -0,0 +1,62 @@
+import type {
+  InputFormDefinition,
+  QueryFormDefinition,
+} from './module'
+
+/**
+ * Caller-owned state and commands used by a projected relation-query form.
+ *
+ * Query forms specialize generic input-form projection while preserving a
+ * compact apply/reset contract for hosts that own query state.
+ *
+ * @typeParam TValue - Shape of the caller-owned query state object.
+ */
+export interface ProjectedQueryFormRuntime<TValue extends object = object> {
+  /** Applies the current form value to the host query or data-source layer. */
+  readonly apply: (context: ProjectedQueryFormActionContext<TValue>) => void
+
+  /** Resets the caller-owned form value according to host policy. */
+  readonly reset: (context: ProjectedQueryFormActionContext<TValue>) => void
+
+  /** Updates the caller-owned form value, preserving React set-state semantics. */
+  readonly setValue: (
+    update: TValue | ((current: TValue) => TValue),
+    context?: ProjectedQueryFormValueChangeContext<TValue>,
+  ) => void
+
+  /** Current caller-owned form value. */
+  readonly value: TValue
+}
+
+/**
+ * Semantic and runtime state passed to apply/reset handlers for a projected
+ * query form.
+ *
+ * @typeParam TValue - Shape of the caller-owned query state object.
+ */
+export interface ProjectedQueryFormActionContext<TValue extends object = object> {
+  /** Available choice values for each input-form field id at the time of action. */
+  readonly choiceValuesByFieldId: Readonly<Record<string, readonly string[]>>
+
+  /** Input form that declares groups, fields, and action placements. */
+  readonly inputForm: InputFormDefinition
+
+  /** Query-form binding that connects the input form to a state target. */
+  readonly queryForm: QueryFormDefinition
+
+  /** Shared or target state id affected by the query form. */
+  readonly stateId: string
+
+  /** Current caller-owned form value. */
+  readonly value: TValue
+}
+
+/**
+ * Semantic context supplied when a query-form field changes the draft value.
+ *
+ * Hosts use this to interpret the query form's execution policy, for example
+ * applying live query forms as field values change while leaving manual query
+ * forms in draft state until an action is invoked.
+ */
+export type ProjectedQueryFormValueChangeContext<TValue extends object = object> =
+  ProjectedQueryFormActionContext<TValue>