@cohesivesystems/presentation-core 0.1.0-alpha.1

package/src/presentation-standards.ts

@@ -0,0 +1,14 @@
+export type PresentationStandardsComposer<TStandards, TContribution> = (
+  ...contributions: readonly TContribution[]
+) => TStandards
+
+/**
+ * Creates a typed standards contribution without coupling the contribution to a
+ * particular app shell. Folder-local feature modules can export these and the
+ * app composition layer decides how to merge them.
+ */
+export function definePresentationStandardsContribution<TContribution>(
+  contribution: TContribution,
+) {
+  return contribution
+}

package/src/presentation-test-selectors.ts

@@ -0,0 +1,312 @@
+import {
+  presentationTestSelectors as generatedPresentationTestSelectors,
+} from '@cohesivesystems/presentation-contracts'
+import type {
+  FlowDefinition,
+  FlowStateDefinition,
+  FlowTransitionDefinition,
+} from '@cohesivesystems/presentation-contracts'
+
+/**
+ * Stable DOM attribute names emitted by Cohesive presentation renderers for
+ * semantic UI automation.
+ */
+export const presentationTestAttributes = {
+  actionId: generatedPresentationTestSelectors.actionIdAttribute,
+  collectionSlotId: generatedPresentationTestSelectors.collectionSlotIdAttribute,
+  fieldId: generatedPresentationTestSelectors.fieldIdAttribute,
+  flowId: generatedPresentationTestSelectors.flowIdAttribute,
+  flowStateId: generatedPresentationTestSelectors.flowStateIdAttribute,
+  formId: generatedPresentationTestSelectors.formIdAttribute,
+  projectionId: generatedPresentationTestSelectors.projectionIdAttribute,
+  routeId: generatedPresentationTestSelectors.routeIdAttribute,
+  rowId: generatedPresentationTestSelectors.rowIdAttribute,
+  viewId: generatedPresentationTestSelectors.viewIdAttribute,
+} as const
+
+/**
+ * Custom browser event names reserved for Cohesive presentation test drivers.
+ */
+export const presentationTestEvents = {
+  setDocumentText: 'cohesive:presentation.test.set-document-text',
+} as const
+
+/**
+ * Semantic presentation identities that can be projected onto a rendered
+ * element as stable automation attributes.
+ */
+export interface PresentationTestAttributeSubject {
+  /** Presentation action identifier represented by the element. */
+  readonly actionId?: string | null
+
+  /** Collection chrome, body, detail, or action slot identifier. */
+  readonly collectionSlotId?: string | null
+
+  /** Presentation field identifier represented by the element. */
+  readonly fieldId?: string | null
+
+  /** Presentation flow identifier represented by the element. */
+  readonly flowId?: string | null
+
+  /** Flow state identifier represented by the element. */
+  readonly flowStateId?: string | null
+
+  /** Presentation form identifier represented by the element. */
+  readonly formId?: string | null
+
+  /** Renderer-specific projection identifier represented by the element. */
+  readonly projectionId?: string | null
+
+  /** Navigation route identifier represented by the element. */
+  readonly routeId?: string | null
+
+  /** Data row identifier represented by the element. */
+  readonly rowId?: string | null
+
+  /** Presentation view identifier represented by the element. */
+  readonly viewId?: string | null
+}
+
+/**
+ * Payload for the test-only document text event.
+ */
+export interface PresentationSetDocumentTextTestEventDetail {
+  /** Replacement document text supplied by the test driver. */
+  readonly value: string
+}
+
+/**
+ * Serializable semantic test plan generated from a presentation flow.
+ */
+export interface PresentationFlowTestPlan {
+  /** Flow identifier that owns the generated plan. */
+  readonly flowId: string
+
+  /** Initial state identifier declared by the flow. */
+  readonly initialStateId: string
+
+  /** Human-readable flow name. */
+  readonly name: string
+
+  /** Flow states with selectors for locating their rendered surfaces. */
+  readonly states: readonly PresentationFlowTestState[]
+
+  /** Flow transitions with optional selectors for invoking actions. */
+  readonly transitions: readonly PresentationFlowTestTransition[]
+}
+
+/**
+ * Testable state node generated from a presentation flow state.
+ */
+export interface PresentationFlowTestState {
+  /** Flow state identifier. */
+  readonly id: string
+
+  /** Presentation flow state kind from the IR. */
+  readonly kind: FlowStateDefinition['Kind']
+
+  /** Human-readable state name. */
+  readonly name: string
+
+  /** CSS selector that locates this state within the rendered flow. */
+  readonly selector: string
+
+  /** View rendered for this state, when the state declares one. */
+  readonly viewId: string | null
+}
+
+/**
+ * Testable transition edge generated from a presentation flow transition.
+ */
+export interface PresentationFlowTestTransition {
+  /** Action invoked by this transition, when the transition is action-bound. */
+  readonly actionId: string | null
+
+  /** Event name that triggers the transition. */
+  readonly event: string
+
+  /** Source flow state identifier. */
+  readonly fromStateId: string
+
+  /** Guard expression or identifier declared by the transition, when present. */
+  readonly guard: string | null
+
+  /** Flow transition identifier. */
+  readonly id: string
+
+  /** CSS selector for the transition action, when the transition is action-bound. */
+  readonly selector: string | null
+
+  /** Destination flow state identifier. */
+  readonly toStateId: string
+}
+
+/**
+ * Creates DOM attributes for a semantic presentation subject.
+ *
+ * Null, undefined, and empty-string values are omitted so callers can spread the
+ * result directly onto React elements.
+ */
+export function createPresentationTestAttributes({
+  actionId,
+  collectionSlotId,
+  fieldId,
+  flowId,
+  flowStateId,
+  formId,
+  projectionId,
+  routeId,
+  rowId,
+  viewId,
+}: PresentationTestAttributeSubject): Record<string, string> {
+  const entries: readonly (readonly [string, string | null | undefined])[] = [
+    [presentationTestAttributes.actionId, actionId],
+    [presentationTestAttributes.collectionSlotId, collectionSlotId],
+    [presentationTestAttributes.fieldId, fieldId],
+    [presentationTestAttributes.flowId, flowId],
+    [presentationTestAttributes.flowStateId, flowStateId],
+    [presentationTestAttributes.formId, formId],
+    [presentationTestAttributes.projectionId, projectionId],
+    [presentationTestAttributes.routeId, routeId],
+    [presentationTestAttributes.rowId, rowId],
+    [presentationTestAttributes.viewId, viewId],
+  ]
+
+  return Object.fromEntries(
+    entries.filter((entry): entry is readonly [string, string] =>
+      typeof entry[1] === 'string' && entry[1].length > 0),
+  )
+}
+
+/**
+ * Creates a CSS attribute selector for a Cohesive semantic test attribute.
+ */
+export function createPresentationAttributeSelector(
+  attribute: string,
+  value: string,
+) {
+  return `[${attribute}="${escapeCssAttributeValue(value)}"]`
+}
+
+/**
+ * Selector factories for semantic presentation test attributes.
+ */
+export const presentationTestSelectors = {
+  /** Locates an element by presentation action identifier. */
+  action: (actionId: string) =>
+    createPresentationAttributeSelector(
+      presentationTestAttributes.actionId,
+      actionId,
+    ),
+
+  /** Locates an element by collection slot identifier. */
+  collectionSlot: (slotId: string) =>
+    createPresentationAttributeSelector(
+      presentationTestAttributes.collectionSlotId,
+      slotId,
+    ),
+
+  /** Locates an element by presentation field identifier. */
+  field: (fieldId: string) =>
+    createPresentationAttributeSelector(
+      presentationTestAttributes.fieldId,
+      fieldId,
+    ),
+
+  /** Locates an element by presentation flow identifier. */
+  flow: (flowId: string) =>
+    createPresentationAttributeSelector(
+      presentationTestAttributes.flowId,
+      flowId,
+    ),
+
+  /** Locates a rendered flow state within a presentation flow. */
+  flowState: (flowId: string, stateId: string) =>
+    `${presentationTestSelectors.flow(flowId)}${createPresentationAttributeSelector(
+      presentationTestAttributes.flowStateId,
+      stateId,
+    )}`,
+
+  /** Locates an element by presentation form identifier. */
+  form: (formId: string) =>
+    createPresentationAttributeSelector(
+      presentationTestAttributes.formId,
+      formId,
+    ),
+
+  /** Locates an element by renderer-specific projection identifier. */
+  projection: (projectionId: string) =>
+    createPresentationAttributeSelector(
+      presentationTestAttributes.projectionId,
+      projectionId,
+    ),
+
+  /** Locates an element by navigation route identifier. */
+  route: (routeId: string) =>
+    createPresentationAttributeSelector(
+      presentationTestAttributes.routeId,
+      routeId,
+    ),
+
+  /** Locates an element by data row identifier. */
+  row: (rowId: string) =>
+    createPresentationAttributeSelector(
+      presentationTestAttributes.rowId,
+      rowId,
+    ),
+
+  /** Locates an element by presentation view identifier. */
+  view: (viewId: string) =>
+    createPresentationAttributeSelector(
+      presentationTestAttributes.viewId,
+      viewId,
+    ),
+} as const
+
+/**
+ * Generates a semantic test plan from a presentation flow definition.
+ */
+export function createPresentationFlowTestPlan(
+  flow: FlowDefinition,
+): PresentationFlowTestPlan {
+  return {
+    flowId: flow.Id,
+    initialStateId: flow.InitialStateId,
+    name: flow.Name,
+    states: flow.States.map((state) => createPresentationFlowTestState(flow, state)),
+    transitions: flow.Transitions.map(createPresentationFlowTestTransition),
+  }
+}
+
+function createPresentationFlowTestState(
+  flow: FlowDefinition,
+  state: FlowStateDefinition,
+): PresentationFlowTestState {
+  return {
+    id: state.Id,
+    kind: state.Kind,
+    name: state.Name,
+    selector: presentationTestSelectors.flowState(flow.Id, state.Id),
+    viewId: state.ViewId ?? null,
+  }
+}
+
+function createPresentationFlowTestTransition(
+  transition: FlowTransitionDefinition,
+): PresentationFlowTestTransition {
+  return {
+    actionId: transition.ActionId ?? null,
+    event: transition.Event,
+    fromStateId: transition.FromStateId,
+    guard: transition.Guard ?? null,
+    id: transition.Id,
+    selector: transition.ActionId
+      ? presentationTestSelectors.action(transition.ActionId)
+      : null,
+    toStateId: transition.ToStateId,
+  }
+}
+
+function escapeCssAttributeValue(value: string) {
+  return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')
+}

package/src/presentation-value-formatting.ts

@@ -0,0 +1,65 @@
+export function resolvePresentationEnumLabel(
+  value: unknown,
+  labels: Readonly<Record<number | string, string>> | undefined,
+  {
+    fallback = 'Unknown',
+  }: {
+    readonly fallback?: string
+  } = {},
+) {
+  if (value === null || value === undefined || value === '') {
+    return fallback
+  }
+
+  const key = String(value)
+  return labels?.[key] ?? String(value)
+}
+
+export function formatPresentationVersion(
+  value: unknown,
+  {
+    fallback = 'n/a',
+    prefix = 'v',
+  }: {
+    readonly fallback?: string
+    readonly prefix?: string
+  } = {},
+) {
+  return value === null || value === undefined || value === ''
+    ? fallback
+    : `${prefix}${value}`
+}
+
+export function formatPresentationDateTime(
+  value: unknown,
+  {
+    fallback = 'n/a',
+  }: {
+    readonly fallback?: string
+  } = {},
+) {
+  if (typeof value !== 'string') {
+    return fallback
+  }
+
+  const parsed = new Date(value)
+  if (Number.isNaN(parsed.getTime())) {
+    return value
+  }
+
+  return parsed.toLocaleString(undefined, {
+    day: 'numeric',
+    hour: 'numeric',
+    minute: '2-digit',
+    month: 'short',
+  })
+}
+
+export function formatPresentationOptionalValue(
+  value: unknown,
+  fallback = 'n/a',
+) {
+  return value === null || value === undefined || value === ''
+    ? fallback
+    : String(value)
+}

package/src/presentation-value-resolution.ts

@@ -0,0 +1,100 @@
+import type { PresentationValueDefinition } from './module'
+
+const presentationValueKind = {
+  literal: new Set<string | number>(['Literal', 0]),
+  field: new Set<string | number>(['Field', 1]),
+} as const
+
+export function resolvePresentationValue(
+  value: PresentationValueDefinition | null | undefined,
+  data: unknown,
+) {
+  if (!value) {
+    return undefined
+  }
+
+  if (presentationValueKind.literal.has(value.Kind)) {
+    return value.Literal
+  }
+
+  if (presentationValueKind.field.has(value.Kind)) {
+    return readPresentationFieldValue(data, value.Field)
+  }
+
+  return undefined
+}
+
+export function resolvePresentationTemplate(
+  template: string | null | undefined,
+  data: unknown,
+) {
+  if (!template) {
+    return null
+  }
+
+  return template.replace(/\{([^}]+)\}/g, (match, fieldPath: string) => {
+    const value = readPresentationFieldValue(data, fieldPath)
+    return value === null || value === undefined ? match : formatPresentationValue(value) ?? ''
+  })
+}
+
+export function readPresentationFieldValue(
+  data: unknown,
+  fieldPath: string | null | undefined,
+) {
+  if (!fieldPath) {
+    return undefined
+  }
+
+  const path = fieldPath.split('.').filter(Boolean)
+  const exactValue = readPath(data, path)
+  if (exactValue !== undefined || path.length <= 1) {
+    return exactValue
+  }
+
+  return readPath(data, path.slice(1))
+}
+
+export function isEmptyPresentationValue(value: unknown) {
+  return value === null || value === undefined || value === ''
+}
+
+export function formatPresentationValue(value: unknown) {
+  if (value === null || value === undefined) {
+    return null
+  }
+
+  if (typeof value === 'string') {
+    return value
+  }
+
+  if (typeof value === 'number' || typeof value === 'bigint' || typeof value === 'boolean') {
+    return value.toString()
+  }
+
+  return JSON.stringify(value)
+}
+
+function readPath(source: unknown, path: readonly string[]) {
+  let current = source
+  for (const segment of path) {
+    if (!current || typeof current !== 'object') {
+      return undefined
+    }
+
+    current = readObjectProperty(current as Record<string, unknown>, segment)
+  }
+
+  return current
+}
+
+function readObjectProperty(source: Record<string, unknown>, segment: string) {
+  if (Object.prototype.hasOwnProperty.call(source, segment)) {
+    return source[segment]
+  }
+
+  const match = Object.keys(source).find(
+    (key) => key.toLocaleLowerCase() === segment.toLocaleLowerCase(),
+  )
+  return match ? source[match] : undefined
+}

package/src/presentation-view-tree.ts

@@ -0,0 +1,33 @@
+import {
+  findPresentationView,
+  type PresentationModuleDefinition,
+  type ViewDefinition,
+  type ViewRegionDefinition,
+} from './module'
+
+export function findPresentationViewRegion(
+  view: Pick<ViewDefinition, 'Regions'> | null,
+  regionId: string,
+) {
+  return view?.Regions?.find((region) => region.Id === regionId) ?? null
+}
+
+export function readFirstRegionViewId(
+  view: Pick<ViewDefinition, 'Regions'> | null,
+  regionId: string,
+) {
+  return findPresentationViewRegion(view, regionId)?.ViewIds?.[0] ?? null
+}
+
+export function findFirstRegionView<TView extends ViewDefinition>(
+  module: Pick<PresentationModuleDefinition, 'Views'> | null,
+  view: Pick<ViewDefinition, 'Regions'> | null,
+  regionId: string,
+) {
+  const viewId = readFirstRegionViewId(view, regionId)
+  return viewId ? findPresentationView<TView>(module, viewId) : null
+}
+
+export function getRegionViewIds(region: ViewRegionDefinition) {
+  return region.ViewIds ?? []
+}

package/src/process-task-model.ts

@@ -0,0 +1,158 @@
+export type ProcessTaskType = string
+export type ProcessLifecycleStatus = 'pending' | 'running' | 'waiting' | 'success' | 'error' | 'paused'
+export type ProcessTaskMetadataSelector = Partial<{
+  readonly [K in keyof ProcessTaskMetadata]: ProcessTaskMetadata[K]
+}>
+
+export interface ProcessTaskMetadata {
+  readonly correlationId?: string | null
+  readonly ediSpecId?: string | null
+  readonly mode?: string | null
+  readonly modelId?: string | null
+  readonly policyId?: string | null
+  readonly projectionIds?: readonly string[] | null
+  readonly shapeGraphId?: string | null
+}
+
+export interface ProcessTask {
+  readonly id: string
+  readonly type: ProcessTaskType
+  readonly typeTone?: string | null
+  readonly title: string
+  readonly status: string
+  readonly statusLabel: string
+  readonly lifecycleStatus: ProcessLifecycleStatus
+  readonly startedAtUtc?: string | null
+  readonly updatedAtUtc?: string | null
+  readonly completedAtUtc?: string | null
+  readonly failureMessage?: string | null
+  readonly detailsHref?: string | null
+  readonly sourceHref?: string | null
+  readonly targetHref?: string | null
+  readonly metadata: ProcessTaskMetadata
+}
+
+export interface ProcessTaskSelector {
+  readonly activeOnly?: boolean
+  readonly metadata?: ProcessTaskMetadataSelector
+  readonly processType?: ProcessTaskType | null
+}
+
+export interface ProcessTaskStartToast {
+  readonly description?: string
+  readonly href?: string | null
+  readonly hrefLabel?: string | null
+  readonly title?: string
+  readonly tone?: ProcessTaskToast['tone']
+}
+
+export interface ProcessTaskStartRegistration {
+  readonly completedAtUtc?: string | null
+  readonly detailsHref?: string | null
+  readonly failureMessage?: string | null
+  readonly invalidateQueryKeys?: readonly (readonly unknown[])[]
+  readonly metadata?: ProcessTaskMetadata
+  readonly processId: string
+  readonly processName?: string | null
+  readonly processType: ProcessTaskType
+  readonly processTypeLabel?: string | null
+  readonly processTypeTone?: string | null
+  readonly sourceHref?: string | null
+  readonly startedAtUtc?: string | null
+  readonly startedToast?: ProcessTaskStartToast | null
+  readonly status?: string | null
+  readonly statusLabel?: string | null
+  readonly statusTone?: string | null
+  readonly targetHref?: string | null
+  readonly terminalInvalidateQueryKeys?: readonly (readonly unknown[])[]
+  readonly updatedAtUtc?: string | null
+}
+
+export interface ProcessTaskToast {
+  readonly id: string
+  readonly taskId: string
+  readonly title: string
+  readonly description: string
+  readonly tone: 'info' | 'success' | 'error'
+  readonly href?: string | null
+  readonly hrefLabel?: string | null
+  readonly createdAt: number
+}
+
+export function isProcessTaskTerminal(task: ProcessTask) {
+  return isTerminalProcessStatus(task.status, task.completedAtUtc)
+}
+
+export function findProcessTask(
+  tasks: readonly ProcessTask[],
+  selector: ProcessTaskSelector,
+) {
+  return findProcessTasks(tasks, selector)[0] ?? null
+}
+
+export function findProcessTasks(
+  tasks: readonly ProcessTask[],
+  selector: ProcessTaskSelector,
+) {
+  return tasks.filter((task) => matchesProcessTaskSelector(task, selector))
+}
+
+export function matchesProcessTaskSelector(
+  task: ProcessTask,
+  selector: ProcessTaskSelector,
+) {
+  if (selector.activeOnly && isProcessTaskTerminal(task)) {
+    return false
+  }
+
+  if (selector.processType && task.type !== selector.processType) {
+    return false
+  }
+
+  return matchesProcessTaskMetadataSelector(task.metadata, selector.metadata)
+}
+
+export function isTerminalProcessStatus(status: string, completedAtUtc?: string | null) {
+  if (['Completed', 'Failed', 'Cancelled', 'Canceled', 'Terminated'].includes(status)) {
+    return true
+  }
+
+  if (['Pending', 'Running', 'Waiting', 'Suspended'].includes(status)) {
+    return false
+  }
+
+  return Boolean(completedAtUtc)
+}
+
+function matchesProcessTaskMetadataSelector(
+  metadata: ProcessTaskMetadata,
+  selector: ProcessTaskMetadataSelector | null | undefined,
+) {
+  if (!selector) {
+    return true
+  }
+
+  for (const [key, expected] of Object.entries(selector)) {
+    if (expected === undefined) {
+      continue
+    }
+
+    const actual = metadata[key as keyof ProcessTaskMetadata]
+    if (Array.isArray(expected)) {
+      if (!Array.isArray(actual) || !arraysEqual(actual, expected)) {
+        return false
+      }
+      continue
+    }
+
+    if (actual !== expected) {
+      return false
+    }
+  }
+
+  return true
+}
+
+function arraysEqual(left: readonly unknown[], right: readonly unknown[]) {
+  return left.length === right.length && left.every((value, index) => value === right[index])
+}