@cohesivesystems/presentation-core 0.1.0-alpha.1

package/src/target-bindings.ts

@@ -0,0 +1,123 @@
+import type {
+  PresentationBindingDefinition,
+} from './module'
+
+export interface PresentationEnumDiscriminator {
+  readonly label?: string
+  readonly value: string | number
+}
+
+export interface FindPresentationComponentBindingOptions {
+  readonly bindingKind: PresentationEnumDiscriminator
+  readonly componentSet?: string | null
+  readonly id: string
+  readonly routeId?: string | null
+  readonly targetKind?: PresentationEnumDiscriminator | null
+}
+
+export interface ResolvedPresentationComponentBinding<
+  TBinding extends PresentationBindingDefinition = PresentationBindingDefinition,
+> {
+  readonly binding: TBinding | null
+  readonly componentKey: string | null
+  readonly componentRole: string | null
+}
+
+interface PresentationTargetBindingProjection {
+  readonly Bindings: readonly PresentationBindingDefinition[]
+  readonly ComponentSet?: string | null
+  readonly Target: string | number
+}
+
+export function findPresentationComponentBinding<
+  TBinding extends PresentationBindingDefinition,
+>(
+  module: { readonly Targets: readonly PresentationTargetBindingProjection[] },
+  {
+    bindingKind,
+    componentSet,
+    id,
+    routeId,
+    targetKind,
+  }: FindPresentationComponentBindingOptions,
+): TBinding | null {
+  const targetMatches = module.Targets.filter((target) => {
+    if (targetKind && !matchesPresentationEnum(target.Target, targetKind)) {
+      return false
+    }
+
+    return !componentSet || target.ComponentSet === componentSet
+  })
+  const targets = targetMatches.length > 0 ? targetMatches : module.Targets
+  const bindings = targets
+    .flatMap((target) => target.Bindings)
+    .filter(
+      (binding) =>
+        matchesPresentationEnum(binding.Kind, bindingKind) && binding.Id === id,
+    )
+
+  return (
+    (bindings.find((binding) => routeId && binding.RouteId === routeId) as
+      | TBinding
+      | undefined) ??
+    (bindings.find((binding) => !binding.RouteId) as TBinding | undefined) ??
+    (bindings[0] as TBinding | undefined) ??
+    null
+  )
+}
+
+export function resolvePresentationComponentBinding<
+  TBinding extends PresentationBindingDefinition = PresentationBindingDefinition,
+>(
+  module: { readonly Targets: readonly PresentationTargetBindingProjection[] },
+  options: FindPresentationComponentBindingOptions,
+): ResolvedPresentationComponentBinding<TBinding> {
+  const binding = findPresentationComponentBinding<TBinding>(module, options)
+
+  return {
+    binding,
+    componentKey: binding?.ComponentKey ?? null,
+    componentRole: binding?.ComponentRole ?? null,
+  }
+}
+
+export function matchesPresentationEnum(
+  value: string | number,
+  discriminator: PresentationEnumDiscriminator,
+) {
+  return value === discriminator.value || value === discriminator.label
+}
+
+export function createPresentationEnumDiscriminator<
+  TValues extends Readonly<Record<string, string | number>>,
+>(
+  values: TValues,
+  key: keyof TValues,
+  label?: string,
+): PresentationEnumDiscriminator {
+  return { label, value: values[key] }
+}
+
+export function createPresentationComponentBinding<
+  TComponentKey extends string,
+>({
+  componentKey,
+  componentRole,
+  id,
+  kind,
+  routeId,
+}: {
+  readonly componentKey?: TComponentKey
+  readonly componentRole?: string
+  readonly id: string
+  readonly kind: PresentationBindingDefinition['Kind']
+  readonly routeId?: string
+}): PresentationBindingDefinition {
+  return {
+    ComponentKey: componentKey ?? null,
+    ComponentRole: componentRole,
+    Id: id,
+    Kind: kind,
+    RouteId: routeId,
+  }
+}

package/src/view-chrome-content-diagnostics.ts

@@ -0,0 +1,139 @@
+import {
+  findPresentationView,
+} from './module'
+import type {
+  PresentationModuleDefinition,
+  ViewDefinition,
+} from './module'
+import type {
+  PresentationProjectionDiagnostic,
+} from './presentation-projection-diagnostics'
+
+export interface ProjectViewChromeContentDiagnosticsOptions {
+  readonly module: Pick<PresentationModuleDefinition, 'Views'> | null
+  readonly view: ViewDefinition | null
+}
+
+export function projectViewChromeContentDiagnostics({
+  module,
+  view,
+}: ProjectViewChromeContentDiagnosticsOptions): readonly PresentationProjectionDiagnostic[] {
+  return collectViewTree(module, view).flatMap(projectSingleViewChromeContentDiagnostics)
+}
+
+function projectSingleViewChromeContentDiagnostics(
+  view: ViewDefinition,
+): readonly PresentationProjectionDiagnostic[] {
+  const chrome = view.Chrome
+  if (!chrome) {
+    return []
+  }
+
+  const hasLegacyTitle = Boolean(chrome.Title)
+  const hasLegacySubtitle = Boolean(chrome.Subtitle)
+  const content = chrome.Content
+  if (!content && (hasLegacyTitle || hasLegacySubtitle)) {
+    return [
+      createViewChromeContentDiagnostic({
+        fields: [
+          hasLegacyTitle ? 'Title' : null,
+          hasLegacySubtitle ? 'Subtitle' : null,
+        ].filter((field): field is string => Boolean(field)),
+        message:
+          `View '${view.Name}' chrome still declares legacy title/subtitle fields ` +
+          'without Content; the frontend will use legacy chrome content fallback semantics.',
+        reason: 'legacy-content-fallback',
+        view,
+      }),
+    ]
+  }
+
+  const diagnostics: PresentationProjectionDiagnostic[] = []
+  if (content && hasLegacyTitle && !content.Title) {
+    diagnostics.push(
+      createViewChromeContentDiagnostic({
+        fields: ['Title'],
+        message:
+          `View '${view.Name}' chrome Content does not declare a title, but legacy Title is present; ` +
+          'the frontend will use legacy title fallback semantics.',
+        reason: 'legacy-title-fallback',
+        view,
+      }),
+    )
+  }
+
+  const hasContentDescription = Boolean(
+    content?.Description ??
+    content?.DescriptionTemplate ??
+    content?.Subtitle,
+  )
+  if (content && hasLegacySubtitle && !hasContentDescription) {
+    diagnostics.push(
+      createViewChromeContentDiagnostic({
+        fields: ['Subtitle'],
+        message:
+          `View '${view.Name}' chrome Content does not declare description or subtitle content, ` +
+          'but legacy Subtitle is present; the frontend will use legacy subtitle fallback semantics.',
+        reason: 'legacy-subtitle-fallback',
+        view,
+      }),
+    )
+  }
+
+  return diagnostics
+}
+
+function collectViewTree(
+  module: Pick<PresentationModuleDefinition, 'Views'> | null,
+  view: ViewDefinition | null,
+  seen = new Set<string>(),
+): readonly ViewDefinition[] {
+  if (!view || seen.has(view.Id)) {
+    return []
+  }
+
+  seen.add(view.Id)
+  return [
+    view,
+    ...view.Regions.flatMap((region) =>
+      region.ViewIds.flatMap((viewId) =>
+        collectViewTree(module, findPresentationView(module, viewId), seen),
+      ),
+    ),
+  ]
+}
+
+function createViewChromeContentDiagnostic({
+  fields,
+  message,
+  reason,
+  view,
+}: {
+  readonly fields: readonly string[]
+  readonly message: string
+  readonly reason: string
+  readonly view: ViewDefinition
+}): PresentationProjectionDiagnostic {
+  return {
+    category: 'incomplete-projection',
+    details: {
+      fields,
+      viewId: view.Id,
+    },
+    id: `view-chrome.${view.Id}.content.${reason}`,
+    interpretation: {
+      status: 'locally-interpreted',
+      target: 'react',
+    },
+    message,
+    severity: 'warning',
+    source: 'view-chrome-content-projection',
+    subject: {
+      id: view.Id,
+      kind: 'view-chrome',
+      name: view.Name,
+    },
+    suggestedNextStep:
+      'Declare View.Chrome.Content with PresentationContentDefinition and remove legacy title/subtitle fallback fields.',
+  }
+}

package/src/view-chrome-icons.ts

@@ -0,0 +1,81 @@
+import type {
+  ViewChromeSlotDefinition,
+} from './module'
+import type {
+  PresentationIconDiagnosticSubject,
+} from './presentation-icon-diagnostics'
+import {
+  isViewChromeSlotKind,
+} from './view-chrome-slot-renderer-registry'
+import {
+  viewChromeSlotKinds,
+} from '@cohesivesystems/presentation-contracts'
+
+export const viewChromeIconIds = {
+  layoutSingle: 'view-chrome.layout.single',
+  layoutSplit: 'view-chrome.layout.split',
+  viewDefault: 'view-chrome.view.default',
+  viewJson: 'view-chrome.view.json',
+  viewStructure: 'view-chrome.view.structure',
+  viewTypes: 'view-chrome.view.types',
+} as const
+
+export function resolveViewChromeIconSubjects(
+  slots: readonly ViewChromeSlotDefinition[],
+): readonly PresentationIconDiagnosticSubject[] {
+  return slots.flatMap((slot) => {
+    if (isViewChromeSlotKind(slot, viewChromeSlotKinds.layoutSwitch)) {
+      return [
+        createViewChromeIconSubject(slot, viewChromeIconIds.layoutSingle, 'Single layout'),
+        createViewChromeIconSubject(slot, viewChromeIconIds.layoutSplit, 'Split layout'),
+      ]
+    }
+
+    if (isViewChromeSlotKind(slot, viewChromeSlotKinds.viewSwitch)) {
+      return slot.ViewIds.map((viewId) =>
+        createViewChromeIconSubject(
+          slot,
+          resolveViewChromeViewIconId(viewId),
+          `View switch: ${viewId}`,
+          { viewId },
+        ))
+    }
+
+    return []
+  })
+}
+
+function createViewChromeIconSubject(
+  slot: ViewChromeSlotDefinition,
+  icon: string,
+  label: string,
+  details: Readonly<Record<string, unknown>> = {},
+): PresentationIconDiagnosticSubject {
+  return {
+    details: {
+      slotId: slot.Id,
+      ...details,
+    },
+    icon,
+    id: `${slot.Id}:${icon}`,
+    kind: 'view-chrome-icon',
+    label,
+  }
+}
+
+function resolveViewChromeViewIconId(viewId: string) {
+  const normalized = viewId.toLocaleLowerCase()
+  if (normalized.includes('json')) {
+    return viewChromeIconIds.viewJson
+  }
+
+  if (normalized.includes('type')) {
+    return viewChromeIconIds.viewTypes
+  }
+
+  if (normalized.includes('structure')) {
+    return viewChromeIconIds.viewStructure
+  }
+
+  return viewChromeIconIds.viewDefault
+}

package/src/view-chrome-slot-renderer-registry.ts

@@ -0,0 +1,128 @@
+import type {
+  ViewChromeSlotDefinition,
+  ViewChromeSlotKind,
+  ViewChromeSlotPlacement,
+} from './module'
+import {
+  viewChromeSlotKindLabels,
+  viewChromeSlotPlacementLabels,
+} from '@cohesivesystems/presentation-contracts'
+
+export const viewChromeSlotAnyPlacement = '*'
+
+export type ViewChromeSlotRenderer<TContext, TResult = unknown> = (
+  context: TContext,
+) => TResult
+
+export type ViewChromeSlotRendererRegistry<TContext, TResult = unknown> = Readonly<
+  Record<string, ViewChromeSlotRenderer<TContext, TResult>>
+>
+
+export interface ViewChromeSlotRendererBinding<TContext, TResult = unknown> {
+  readonly kind: ViewChromeSlotKind | string | number
+  readonly placement?: ViewChromeSlotPlacement | string | number | null
+  readonly render: ViewChromeSlotRenderer<TContext, TResult>
+}
+
+export function createViewChromeSlotRendererRegistry<TContext, TResult = unknown>(
+  bindings: readonly ViewChromeSlotRendererBinding<TContext, TResult>[],
+): ViewChromeSlotRendererRegistry<TContext, TResult> {
+  return Object.fromEntries(
+    bindings.map((binding) => [
+      createViewChromeSlotRendererKey(binding.kind, binding.placement),
+      binding.render,
+    ]),
+  )
+}
+
+export function createViewChromeSlotRendererKey(
+  kind: ViewChromeSlotKind | string | number,
+  placement?: ViewChromeSlotPlacement | string | number | null,
+) {
+  return `${normalizeViewChromeSlotKind(kind)}:${placement == null
+    ? viewChromeSlotAnyPlacement
+    : normalizeViewChromeSlotPlacement(placement)}`
+}
+
+export function getViewChromeSlotRendererRegistryKeys<TContext, TResult = unknown>(
+  registry: ViewChromeSlotRendererRegistry<TContext, TResult> | null | undefined,
+) {
+  return Object.keys(registry ?? {})
+}
+
+export function getViewChromeSlotRendererCandidateKeys(
+  slot: ViewChromeSlotDefinition,
+) {
+  return [
+    createViewChromeSlotRendererKey(slot.Kind, slot.Placement),
+    createViewChromeSlotRendererKey(slot.Kind),
+  ]
+}
+
+export function hasViewChromeSlotRendererBinding(
+  keys: readonly string[],
+  slot: ViewChromeSlotDefinition,
+) {
+  return getViewChromeSlotRendererCandidateKeys(slot).some((key) =>
+    keys.includes(key))
+}
+
+export function resolveViewChromeSlotRenderer<TContext, TResult = unknown>(
+  registry: ViewChromeSlotRendererRegistry<TContext, TResult> | null | undefined,
+  slot: ViewChromeSlotDefinition,
+) {
+  const renderers = registry ?? {}
+  for (const key of getViewChromeSlotRendererCandidateKeys(slot)) {
+    const renderer = renderers[key]
+    if (renderer) {
+      return renderer
+    }
+  }
+
+  return null
+}
+
+export function isViewChromeSlotPlacement(
+  slot: ViewChromeSlotDefinition,
+  placement: ViewChromeSlotPlacement | string | number,
+) {
+  return isViewChromeSlotPlacementValue(slot.Placement, placement)
+}
+
+export function isViewChromeSlotKind(
+  slot: ViewChromeSlotDefinition,
+  kind: ViewChromeSlotKind | string | number,
+) {
+  return normalizeViewChromeSlotKind(slot.Kind) ===
+    normalizeViewChromeSlotKind(kind)
+}
+
+export function isViewChromeSlotPlacementValue(
+  value: ViewChromeSlotPlacement | string | number | null | undefined,
+  placement: ViewChromeSlotPlacement | string | number,
+) {
+  if (value == null) {
+    return false
+  }
+
+  return normalizeViewChromeSlotPlacement(value) ===
+    normalizeViewChromeSlotPlacement(placement)
+}
+
+function normalizeViewChromeSlotKind(value: unknown) {
+  return normalizeGeneratedEnumToken(value, viewChromeSlotKindLabels)
+}
+
+function normalizeViewChromeSlotPlacement(value: unknown) {
+  return normalizeGeneratedEnumToken(value, viewChromeSlotPlacementLabels)
+}
+
+function normalizeGeneratedEnumToken(
+  value: unknown,
+  labels: Readonly<Record<number, string>>,
+) {
+  const label = typeof value === 'number'
+    ? labels[value] ?? String(value)
+    : String(value)
+  return label.replace(/[^a-z0-9]/gi, '').toLocaleLowerCase()
+}