@cohesivesystems/presentation-core 0.1.0-alpha.1

package/src/presentation-data-source-binding-model.ts

@@ -0,0 +1,140 @@
+/**
+ * Frontend realization strategies for semantic presentation data sources.
+ * These are projection/runtime binding kinds, not backend IR data-source kinds.
+ */
+export const presentationDataSourceBindingKinds = {
+  /**
+   * Realizes a data source through TanStack Query so React owns fetch lifecycle,
+   * caching, pending/error state, and refetch behavior.
+   */
+  tanstackQuery: 'tanstack-query',
+  /**
+   * Realizes a data source from already-available local/runtime data without
+   * invoking a query adapter.
+   */
+  localValue: 'local-value',
+} as const
+
+/**
+ * Declares whether a presentation data source can resolve in the current
+ * authorization context.
+ */
+export type PresentationDataSourceAuthorizationRequirement =
+  | { readonly kind: 'none' }
+  | {
+      readonly blockedLabel?: string
+      readonly isAuthorized: boolean
+      readonly kind: 'required'
+    }
+
+/**
+ * Small constructors for keeping data source authorization declarations explicit
+ * at the binding site.
+ */
+export const presentationDataSourceAuthorization = {
+  none: (): PresentationDataSourceAuthorizationRequirement => ({ kind: 'none' }),
+  required: ({
+    blockedLabel,
+    isAuthorized,
+  }: {
+    readonly blockedLabel?: string
+    readonly isAuthorized: boolean
+  }): PresentationDataSourceAuthorizationRequirement => ({
+    blockedLabel,
+    isAuthorized,
+    kind: 'required',
+  }),
+}
+
+/**
+ * Declarative binding from a semantic presentation data source id to a concrete
+ * frontend source. Query bindings currently use TanStack Query.
+ */
+export type PresentationDataSourceBinding =
+  | PresentationLocalValueDataSourceBinding
+  | PresentationTanStackQueryDataSourceBinding
+
+export interface PresentationDataSourceBindingBase {
+  readonly authorization: PresentationDataSourceAuthorizationRequirement
+  readonly blockedLabel?: string
+  readonly dataSourceId: string
+  readonly emptyMessage?: string
+  readonly pendingLabel?: string
+}
+
+export interface PresentationLocalValueDataSourceBinding
+  extends PresentationDataSourceBindingBase {
+  readonly data: unknown
+  readonly error?: unknown
+  readonly isFetching?: boolean
+  readonly isPending?: boolean
+  readonly kind: typeof presentationDataSourceBindingKinds.localValue
+  readonly refetch?: () => Promise<unknown> | unknown
+}
+
+export interface PresentationTanStackQueryDataSourceBinding
+  extends PresentationDataSourceBindingBase {
+  readonly enabled?: boolean
+  readonly fallbackData?: unknown
+  readonly kind: typeof presentationDataSourceBindingKinds.tanstackQuery
+  readonly queryFn: () => Promise<unknown>
+  readonly queryKey: readonly unknown[]
+  readonly refetchInterval?: number | false
+  readonly retry?: boolean | number
+  readonly staleTime?: number
+}
+
+export type PresentationLocalValueDataSourceBindingInput = Omit<
+  PresentationLocalValueDataSourceBinding,
+  'kind'
+>
+
+export type PresentationTanStackQueryDataSourceBindingInput = Omit<
+  PresentationTanStackQueryDataSourceBinding,
+  'kind'
+>
+
+export const presentationDataSourceBindings = {
+  localValue: (
+    binding: PresentationLocalValueDataSourceBindingInput,
+  ): PresentationLocalValueDataSourceBinding => ({
+    ...binding,
+    kind: presentationDataSourceBindingKinds.localValue,
+  }),
+  tanstackQuery: (
+    binding: PresentationTanStackQueryDataSourceBindingInput,
+  ): PresentationTanStackQueryDataSourceBinding => ({
+    ...binding,
+    kind: presentationDataSourceBindingKinds.tanstackQuery,
+  }),
+}
+
+export interface DataSourceAuthorizationState {
+  readonly blockedLabel?: string
+  readonly isBlocked: boolean
+}
+
+export function resolveDataSourceAuthorization(
+  binding: PresentationDataSourceBindingBase,
+): DataSourceAuthorizationState {
+  if (binding.authorization.kind === 'required' && !binding.authorization.isAuthorized) {
+    return {
+      blockedLabel: binding.authorization.blockedLabel ?? binding.blockedLabel,
+      isBlocked: true,
+    }
+  }
+
+  return {
+    blockedLabel:
+      binding.authorization.kind === 'required'
+        ? binding.authorization.blockedLabel ?? binding.blockedLabel
+        : binding.blockedLabel,
+    isBlocked: false,
+  }
+}
+
+export function isTanStackQueryBinding(
+  binding: PresentationDataSourceBinding,
+): binding is PresentationTanStackQueryDataSourceBinding {
+  return binding.kind === presentationDataSourceBindingKinds.tanstackQuery
+}

package/src/presentation-data-source-runtime.ts

@@ -0,0 +1,190 @@
+import type {
+  DataSourceDefinition,
+  ViewDefinition,
+} from './module'
+import {
+  readObjectPath,
+} from './object-path'
+import {
+  createQueryActivityState,
+  type ProjectedActivityState,
+} from './projected-activity-state-model'
+import {
+  getPresentationViewProjectedDataSourceIds,
+} from './presentation-semantics'
+import {
+  resolveCollectionChromePrimaryDataSourceId,
+} from './collection-chrome-runtime'
+
+export {
+  readObjectPath,
+  readObjectProperty,
+} from './object-path'
+
+export interface PresentationDataSourceState<TData = unknown> {
+  readonly blockedLabel?: string
+  readonly data?: TData
+  readonly definition?: DataSourceDefinition | null
+  readonly emptyMessage?: string
+  readonly error?: unknown
+  readonly isBlocked?: boolean
+  readonly isFetching?: boolean
+  readonly isPending?: boolean
+  readonly pendingLabel?: string
+  readonly refetch?: () => Promise<unknown> | unknown
+}
+
+export type PresentationDataSourceStateMap = Readonly<Record<string, PresentationDataSourceState>>
+
+/**
+ * Resolves presentation data sources from their semantic identifiers without
+ * flattening the state map into an ad hoc component data context.
+ */
+export interface PresentationDataSourceResolver {
+  /**
+   * Bound runtime state keyed by semantic presentation data source id.
+   */
+  readonly dataSources: PresentationDataSourceStateMap
+
+  /**
+   * Reads the raw data payload for a data source.
+   */
+  readonly read: <TData = unknown>(dataSourceId: string) => TData | undefined
+
+  /**
+   * Reads a nested value from a data source payload using a dot-separated field path.
+   */
+  readonly readPath: (dataSourceId: string, fieldPath?: string | null) => unknown
+
+  /**
+   * Resolves the full runtime state for a data source, including activity and refetch metadata.
+   */
+  readonly resolve: <TData = unknown>(dataSourceId: string) => PresentationDataSourceState<TData> | undefined
+
+  /**
+   * Resolves all data source states declared by a view subject and explicit data source ids.
+   */
+  readonly resolveViewDataSources: (view: Pick<ViewDefinition, 'Collection' | 'DataSourceIds' | 'Subject'>) => readonly PresentationDataSourceState[]
+
+  /**
+   * Resolves the primary data source state for a view, preferring the view subject source.
+   */
+  readonly resolveViewPrimary: <TData = unknown>(view: Pick<ViewDefinition, 'Collection' | 'DataSourceIds' | 'Subject'>) => PresentationDataSourceState<TData> | undefined
+}
+
+/**
+ * Creates a stable semantic resolver over a bound presentation data source map.
+ */
+export function createPresentationDataSourceResolver(dataSources: PresentationDataSourceStateMap): PresentationDataSourceResolver {
+  return {
+    dataSources,
+    read<TData = unknown>(dataSourceId: string) {
+      return dataSources[dataSourceId]?.data as TData | undefined
+    },
+    readPath(dataSourceId: string, fieldPath?: string | null) {
+      return readObjectPath(dataSources[dataSourceId]?.data, fieldPath ?? '')
+    },
+    resolve<TData = unknown>(dataSourceId: string) {
+      return dataSources[dataSourceId] as PresentationDataSourceState<TData> | undefined
+    },
+    resolveViewDataSources(view: Pick<ViewDefinition, 'Collection' | 'DataSourceIds' | 'Subject'>) {
+      return resolvePresentationViewDataSourceIds(view)
+        .map((dataSourceId) => dataSources[dataSourceId])
+        .filter((state): state is PresentationDataSourceState => Boolean(state))
+    },
+    resolveViewPrimary<TData = unknown>(
+      view: Pick<ViewDefinition, 'Collection' | 'DataSourceIds' | 'Subject'>,
+    ) {
+      const dataSourceId = resolvePresentationViewPrimaryDataSourceId(view)
+      return dataSourceId
+        ? (dataSources[dataSourceId] as PresentationDataSourceState<TData> | undefined)
+        : undefined
+    },
+  }
+}
+
+export function createPresentationViewActivityState({
+  blockedLabel = 'Attach an authenticated context to load this view.',
+  dataSourceResolver,
+  pendingLabel = 'Loading view data...',
+  view,
+}: {
+  readonly blockedLabel?: string
+  readonly dataSourceResolver: PresentationDataSourceResolver
+  readonly pendingLabel?: string
+  readonly view: ViewDefinition
+}): ProjectedActivityState {
+  const states = dataSourceResolver.resolveViewDataSources(view)
+  const blockedState = states.find((state) => state.isBlocked)
+  const pendingState = states.find((state) => state.isPending)
+  const errorState = states.find((state) => state.error)
+
+  return createQueryActivityState({
+    blockedLabel: blockedState?.blockedLabel ?? blockedLabel,
+    error: errorState?.error,
+    isBlocked: Boolean(blockedState),
+    isPending: Boolean(pendingState),
+    pendingLabel: pendingState?.pendingLabel ?? pendingLabel,
+  })
+}
+
+export function isPresentationViewFetching(
+  view: ViewDefinition,
+  dataSourceResolver: PresentationDataSourceResolver,
+) {
+  return resolvePresentationViewDataSourceIds(view).some(
+    (dataSourceId) => dataSourceResolver.resolve(dataSourceId)?.isFetching,
+  )
+}
+
+export function readPresentationDataSourceItems<TItem extends object = object>(
+  state: PresentationDataSourceState | null | undefined,
+): readonly TItem[] {
+  const data = state?.data
+  if (Array.isArray(data)) {
+    return data as readonly TItem[]
+  }
+
+  if (data && typeof data === 'object') {
+    const items = (data as { readonly Items?: unknown }).Items
+    if (Array.isArray(items)) {
+      return items as readonly TItem[]
+    }
+  }
+
+  return []
+}
+
+export async function refreshPresentationDataSources(
+  dataSourceResolver: PresentationDataSourceResolver,
+  dataSourceIds: readonly string[],
+) {
+  const uniqueDataSourceIds = Array.from(new Set(dataSourceIds))
+  await Promise.all(
+    uniqueDataSourceIds.map((dataSourceId) =>
+      Promise.resolve(dataSourceResolver.resolve(dataSourceId)?.refetch?.()),
+    ),
+  )
+  return undefined
+}
+
+export function resolvePresentationViewDataSourceIds(
+  view: Pick<ViewDefinition, 'Collection' | 'DataSourceIds' | 'Subject'>,
+) {
+  return getPresentationViewProjectedDataSourceIds(view)
+}
+
+export function resolvePresentationViewPrimaryDataSourceId(
+  view: Pick<ViewDefinition, 'Collection' | 'DataSourceIds' | 'Subject'>,
+) {
+  return view.Subject.DataSourceId ??
+    resolvePresentationViewCollectionPrimarySlotDataSourceId(view) ??
+    view.DataSourceIds[0] ??
+    null
+}
+
+function resolvePresentationViewCollectionPrimarySlotDataSourceId(
+  view: Pick<ViewDefinition, 'Collection'>,
+) {
+  return resolveCollectionChromePrimaryDataSourceId(view.Collection)
+}

package/src/presentation-design-intent-diagnostics.ts

@@ -0,0 +1,104 @@
+import {
+  createPresentationProjectionDiagnostic,
+  type PresentationProjectionDiagnostic,
+} from './presentation-projection-diagnostics'
+import type {
+  DesignIntent,
+} from '@cohesivesystems/presentation-contracts'
+
+export const presentationDesignIntentFieldNames = [
+  'Role',
+  'Variant',
+  'Tone',
+  'Density',
+  'Size',
+  'Layout',
+] as const
+
+export type PresentationDesignIntentFieldName =
+  (typeof presentationDesignIntentFieldNames)[number]
+
+export interface ProjectPresentationDesignIntentDiagnosticsOptions {
+  readonly design: DesignIntent | null | undefined
+  readonly ignoredFields: readonly PresentationDesignIntentFieldName[]
+  readonly interpretedFields: readonly PresentationDesignIntentFieldName[]
+  readonly message: string
+  readonly semanticInputs?: readonly string[]
+  readonly source: string
+  readonly subject: {
+    readonly id: string
+    readonly kind: string
+    readonly name?: string | null
+  }
+  readonly suggestedNextStep?: string
+  readonly target: string
+}
+
+/**
+ * Reports which design-intent fields a frontend interpreter currently consumes
+ * and which declared fields remain TODOs for the active target.
+ */
+export function projectPresentationDesignIntentDiagnostics({
+  design,
+  ignoredFields,
+  interpretedFields,
+  message,
+  semanticInputs = [],
+  source,
+  subject,
+  suggestedNextStep =
+    'Extend the design interpreter for these fields or remove the unused design intent.',
+  target,
+}: ProjectPresentationDesignIntentDiagnosticsOptions): readonly PresentationProjectionDiagnostic[] {
+  if (!design) {
+    return []
+  }
+
+  const declaredFields = presentationDesignIntentFieldNames.filter((field) =>
+    isPresentationDesignIntentFieldDeclared(design, field))
+  const declaredIgnoredFields = ignoredFields.filter((field) =>
+    declaredFields.includes(field))
+  if (declaredIgnoredFields.length === 0) {
+    return []
+  }
+
+  const declaredInterpretedFields = interpretedFields.filter((field) =>
+    declaredFields.includes(field))
+
+  return [
+    createPresentationProjectionDiagnostic({
+      category: 'incomplete-projection',
+      details: {
+        ignoredFields: declaredIgnoredFields.map((field) => `Design.${field}`),
+        ignoredValues: Object.fromEntries(
+          declaredIgnoredFields.map((field) => [
+            field,
+            design[field],
+          ]),
+        ),
+        interpretedFields: [
+          ...semanticInputs,
+          ...declaredInterpretedFields.map((field) => `Design.${field}`),
+        ],
+      },
+      id: `presentation-design.${subject.id}.design-intent.partial`,
+      interpretation: {
+        status: 'projected',
+        target,
+      },
+      message,
+      severity: 'info',
+      source,
+      subject,
+      suggestedNextStep,
+    }),
+  ]
+}
+
+function isPresentationDesignIntentFieldDeclared(
+  design: DesignIntent,
+  field: PresentationDesignIntentFieldName,
+) {
+  const value = design[field]
+  return value !== null && value !== undefined && value !== ''
+}