@cohesivesystems/presentation-react 0.1.0-alpha.1

package/src/presentation-module-context.ts

@@ -0,0 +1,10 @@
+import { createContext, useContext } from 'react'
+
+import type { PresentationModuleDefinition } from '@cohesivesystems/presentation-core'
+
+export const PresentationModuleContext =
+  createContext<PresentationModuleDefinition | null>(null)
+
+export function usePresentationModule() {
+  return useContext(PresentationModuleContext)
+}

package/src/presentation-module-provider.tsx

@@ -0,0 +1,19 @@
+import { type PropsWithChildren } from 'react'
+
+import type { PresentationModuleDefinition } from '@cohesivesystems/presentation-core'
+import { PresentationModuleContext } from './presentation-module-context'
+
+export interface PresentationModuleProviderProps extends PropsWithChildren {
+  readonly module: PresentationModuleDefinition | null
+}
+
+export function PresentationModuleProvider({
+  children,
+  module,
+}: PresentationModuleProviderProps) {
+  return (
+    <PresentationModuleContext.Provider value={module}>
+      {children}
+    </PresentationModuleContext.Provider>
+  )
+}

package/src/presentation-projection-diagnostics-context.ts

@@ -0,0 +1,17 @@
+import { createContext } from 'react'
+
+import type {
+  PresentationProjectionDiagnostic,
+} from '@cohesivesystems/presentation-core'
+
+export interface PresentationProjectionDiagnosticsRegistry {
+  readonly clearDiagnostics: (sourceId: string) => void
+  readonly diagnostics: readonly PresentationProjectionDiagnostic[]
+  readonly setDiagnostics: (
+    sourceId: string,
+    diagnostics: readonly PresentationProjectionDiagnostic[],
+  ) => void
+}
+
+export const PresentationProjectionDiagnosticsContext =
+  createContext<PresentationProjectionDiagnosticsRegistry | null>(null)

package/src/presentation-projection-diagnostics-hooks.ts

@@ -0,0 +1,29 @@
+import { useContext, useEffect } from 'react'
+
+import {
+  PresentationProjectionDiagnosticsContext,
+} from './presentation-projection-diagnostics-context'
+import type {
+  PresentationProjectionDiagnostic,
+} from '@cohesivesystems/presentation-core'
+
+export function usePresentationProjectionDiagnostics() {
+  return useContext(PresentationProjectionDiagnosticsContext)?.diagnostics ?? []
+}
+
+export function useRegisterPresentationProjectionDiagnostics(
+  sourceId: string,
+  diagnostics: readonly PresentationProjectionDiagnostic[],
+) {
+  const registry = useContext(PresentationProjectionDiagnosticsContext)
+  const clearDiagnostics = registry?.clearDiagnostics
+  const setDiagnostics = registry?.setDiagnostics
+
+  useEffect(() => {
+    setDiagnostics?.(sourceId, diagnostics)
+  }, [diagnostics, setDiagnostics, sourceId])
+
+  useEffect(() => {
+    return () => clearDiagnostics?.(sourceId)
+  }, [clearDiagnostics, sourceId])
+}

package/src/presentation-projection-diagnostics-runtime.tsx

@@ -0,0 +1,95 @@
+import {
+  useCallback,
+  useMemo,
+  useState,
+  type ReactNode,
+} from 'react'
+
+import {
+  PresentationProjectionDiagnosticsContext,
+} from './presentation-projection-diagnostics-context'
+import {
+  mergePresentationProjectionDiagnostics,
+  type PresentationProjectionDiagnostic,
+} from '@cohesivesystems/presentation-core'
+
+interface PresentationProjectionDiagnosticsProviderProps {
+  readonly children: ReactNode
+}
+
+/**
+ * Collects projection diagnostics from local interpreters so developer tooling
+ * can render one consolidated view instead of scattering warnings through app
+ * chrome.
+ */
+export function PresentationProjectionDiagnosticsProvider({
+  children,
+}: PresentationProjectionDiagnosticsProviderProps) {
+  const [diagnosticsBySource, setDiagnosticsBySource] = useState<
+    Readonly<Record<string, readonly PresentationProjectionDiagnostic[]>>
+  >({})
+  const setDiagnostics = useCallback((
+    sourceId: string,
+    diagnostics: readonly PresentationProjectionDiagnostic[],
+  ) => {
+    setDiagnosticsBySource((current) => {
+      if (areDiagnosticsEqual(current[sourceId] ?? [], diagnostics)) {
+        return current
+      }
+
+      return {
+        ...current,
+        [sourceId]: [...diagnostics],
+      }
+    })
+  }, [])
+  const clearDiagnostics = useCallback((sourceId: string) => {
+    setDiagnosticsBySource((current) => {
+      if (!current[sourceId]) {
+        return current
+      }
+
+      const next = { ...current }
+      delete next[sourceId]
+      return next
+    })
+  }, [])
+  const diagnostics = useMemo(
+    () => mergePresentationProjectionDiagnostics(...Object.values(diagnosticsBySource)),
+    [diagnosticsBySource],
+  )
+  const contextValue = useMemo(
+    () => ({
+      clearDiagnostics,
+      diagnostics,
+      setDiagnostics,
+    }),
+    [clearDiagnostics, diagnostics, setDiagnostics],
+  )
+
+  return (
+    <PresentationProjectionDiagnosticsContext.Provider value={contextValue}>
+      {children}
+    </PresentationProjectionDiagnosticsContext.Provider>
+  )
+}
+
+function areDiagnosticsEqual(
+  left: readonly PresentationProjectionDiagnostic[],
+  right: readonly PresentationProjectionDiagnostic[],
+) {
+  if (left.length !== right.length) {
+    return false
+  }
+
+  return left.every((diagnostic, index) => {
+    const candidate = right[index]
+    return Boolean(
+      candidate &&
+        diagnostic.id === candidate.id &&
+        diagnostic.message === candidate.message &&
+        diagnostic.severity === candidate.severity &&
+        diagnostic.source === candidate.source,
+    )
+  })
+}

package/src/presentation-projection-trace.ts

@@ -0,0 +1,117 @@
+import type {
+  PresentationBindingDefinition,
+  ViewDefinition,
+} from '@cohesivesystems/presentation-core'
+import type {
+  NavigationDefinitionProjection,
+} from '@cohesivesystems/presentation-core'
+import {
+  createPresentationProjectionTrace as createCorePresentationProjectionTrace,
+} from '@cohesivesystems/presentation-core'
+import {
+  resolvePageHostRenderer,
+  type PresentationPageHostRendererModuleProjection,
+  type SimplePageHostRendererRegistry,
+} from './page-host-renderer-registry'
+import {
+  resolvePresentationViewRenderer,
+  type PresentationRendererRegistry,
+} from './presentation-renderer-registry'
+
+export type {
+  PresentationProjectionTrace,
+  PresentationProjectionTracePageHost,
+  PresentationProjectionTracePageHostRenderer,
+  PresentationProjectionTraceRegion,
+  PresentationProjectionTraceRoute,
+  PresentationProjectionTraceSurface,
+  PresentationProjectionTraceView,
+} from '@cohesivesystems/presentation-core'
+
+export interface PresentationProjectionTraceModule
+  extends PresentationPageHostRendererModuleProjection {
+  readonly Targets: readonly {
+    readonly Bindings: readonly PresentationBindingDefinition[]
+    readonly ComponentSet?: string | null
+    readonly Target: string | number
+  }[]
+  readonly Views: readonly ViewDefinition[]
+}
+
+export interface CreatePresentationProjectionTraceOptions<
+  TModule extends PresentationProjectionTraceModule,
+  TContext,
+> {
+  readonly componentSet?: string
+  readonly module: TModule | null
+  readonly navigation: NavigationDefinitionProjection | null
+  readonly pageHostRendererRegistry?: SimplePageHostRendererRegistry<
+    TModule,
+    TContext
+  >
+  readonly pathname: string
+  readonly rendererRegistry?: PresentationRendererRegistry<TContext>
+}
+
+/**
+ * Builds a read-only projection trace while adapting React renderer
+ * registries into framework-neutral trace resolver results.
+ */
+export function createPresentationProjectionTrace<
+  TModule extends PresentationProjectionTraceModule,
+  TContext = unknown,
+>({
+  componentSet,
+  module,
+  navigation,
+  pageHostRendererRegistry,
+  pathname,
+  rendererRegistry,
+}: CreatePresentationProjectionTraceOptions<TModule, TContext>) {
+  return createCorePresentationProjectionTrace({
+    componentSet,
+    module,
+    navigation,
+    pathname,
+    resolvePageHostRenderer: pageHostRendererRegistry
+      ? ({ module, pageHost, route }) => {
+          const resolution = resolvePageHostRenderer({
+            componentKey: null,
+            componentSet,
+            module,
+            pageHost,
+            registry: pageHostRendererRegistry,
+            route,
+          })
+
+          return {
+            componentKey: resolution.componentKey,
+            componentRole: resolution.componentRole,
+            rendererKey: resolution.rendererKey,
+            resolutionSource: resolution.resolutionSource,
+            semanticRole: resolution.semanticRole,
+            targetBindingSource: resolution.targetBindingSource,
+          }
+        }
+      : undefined,
+    resolveViewRenderer: rendererRegistry
+      ? ({ module, routeId, view }) => {
+          const resolution = resolvePresentationViewRenderer({
+            componentSet,
+            module,
+            registry: rendererRegistry,
+            routeId,
+            view,
+          })
+
+          return {
+            componentKey: resolution.componentKey,
+            componentRole: resolution.componentRole,
+            rendererResolved: Boolean(resolution.renderer),
+            resolutionSource: resolution.resolutionSource,
+            semanticRole: resolution.semanticRole,
+          }
+        }
+      : undefined,
+  })
+}

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

@@ -0,0 +1,148 @@
+import type { Dispatch, SetStateAction } from 'react'
+
+import type {
+  ProjectedQueryFormActionContext,
+  ProjectedQueryFormRuntime,
+  ProjectedQueryFormValueChangeContext,
+  QueryFormDefinition,
+} from '@cohesivesystems/presentation-core'
+import { queryFormExecutionModes } from '@cohesivesystems/presentation-contracts'
+
+const debouncedDraftExecutionTimers = new Map<string, ReturnType<typeof setTimeout>>()
+
+export type {
+  PresentationQueryFormState,
+  PresentationQueryFormStateMap,
+  ProjectedQueryFormActionContext,
+  ProjectedQueryFormRuntime,
+  ProjectedQueryFormValueChangeContext,
+} from '@cohesivesystems/presentation-core'
+
+export {
+  findPresentationQueryFormStateForDataSource,
+  readPresentationQueryFormAppliedValue,
+  readPresentationQueryFormDraftValue,
+} from '@cohesivesystems/presentation-core'
+
+export interface PresentationQueryFormValueContext<TValue extends object> {
+  readonly choiceValuesByFieldId: Readonly<Record<string, readonly string[]>>
+  readonly queryForm: QueryFormDefinition
+  readonly value: TValue
+}
+
+export interface CreatePresentationQueryFormRuntimeOptions<TValue extends object> {
+  readonly applyValue: (context: PresentationQueryFormValueContext<TValue>) => void
+  readonly createDefaultValue: (context: PresentationQueryFormValueContext<TValue>) => TValue
+  readonly normalizeValue?: (context: PresentationQueryFormValueContext<TValue>) => TValue
+  readonly queryForm: QueryFormDefinition | null
+  readonly setDraftValue: Dispatch<SetStateAction<TValue>>
+  readonly value: TValue
+}
+
+/**
+ * Adapts caller-owned state into the projected query-form runtime contract.
+ *
+ * The presentation IR defines when a query form has an applied result state,
+ * URL state, and execution policy. This helper keeps the generic form actions
+ * semantic: apply normalizes the draft and commits it to the result state,
+ * reset computes the form default from the available choices and commits that
+ * same value. Concrete hosts provide the interpretation for the commit itself,
+ * such as URL updates, pagination reset, or data-source invalidation.
+ */
+export function createPresentationQueryFormRuntime<TValue extends object>({
+  applyValue,
+  createDefaultValue,
+  normalizeValue,
+  queryForm,
+  setDraftValue,
+  value,
+}: CreatePresentationQueryFormRuntimeOptions<TValue>): ProjectedQueryFormRuntime<TValue> | null {
+  if (!queryForm) {
+    return null
+  }
+
+  const normalize = (context: PresentationQueryFormValueContext<TValue>) =>
+    normalizeValue ? normalizeValue(context) : context.value
+  const commit = (context: PresentationQueryFormValueContext<TValue>) => {
+    const nextValue = normalize(context)
+    setDraftValue(nextValue)
+    applyValue({ ...context, value: nextValue })
+  }
+
+  return {
+    apply: (context) =>
+      commit(createQueryFormValueContext(queryForm, context, context.value)),
+    reset: (context) => {
+      const resetContext = createQueryFormValueContext(queryForm, context, context.value)
+      const nextValue = createDefaultValue(resetContext)
+      commit({ ...resetContext, value: nextValue })
+    },
+    setValue: (update, context) => {
+      const nextValue = resolveSetStateValue(update, value)
+      setDraftValue(nextValue)
+
+      if (context) {
+        executeQueryFormDraftChange(
+          queryForm,
+          commit,
+          createQueryFormValueContext(queryForm, context, nextValue),
+        )
+      }
+    },
+    value,
+  }
+}
+
+export function shouldExecuteQueryFormOnDraftChange(queryForm: QueryFormDefinition | null) {
+  return queryForm?.Target.State.Execution.Mode === queryFormExecutionModes.live ||
+    queryForm?.Target.State.Execution.Mode === queryFormExecutionModes.debouncedLive
+}
+
+function createQueryFormValueContext<TValue extends object>(
+  queryForm: QueryFormDefinition,
+  context: ProjectedQueryFormActionContext<TValue> | ProjectedQueryFormValueChangeContext<TValue>,
+  value: TValue,
+): PresentationQueryFormValueContext<TValue> {
+  return {
+    choiceValuesByFieldId: context.choiceValuesByFieldId,
+    queryForm,
+    value,
+  }
+}
+
+function executeQueryFormDraftChange<TValue extends object>(
+  queryForm: QueryFormDefinition,
+  commit: (context: PresentationQueryFormValueContext<TValue>) => void,
+  context: PresentationQueryFormValueContext<TValue>,
+) {
+  const execution = queryForm.Target.State.Execution
+  if (execution.Mode === queryFormExecutionModes.live) {
+    commit(context)
+    return
+  }
+
+  if (execution.Mode === queryFormExecutionModes.debouncedLive) {
+    const key = queryForm.Target.State.StateId || queryForm.Id
+    const previousTimer = debouncedDraftExecutionTimers.get(key)
+    if (previousTimer) {
+      clearTimeout(previousTimer)
+    }
+
+    debouncedDraftExecutionTimers.set(
+      key,
+      setTimeout(() => {
+        debouncedDraftExecutionTimers.delete(key)
+        commit(context)
+      }, execution.DebounceMilliseconds ?? 250),
+    )
+  }
+}
+
+function resolveSetStateValue<TValue extends object>(
+  update: TValue | ((current: TValue) => TValue),
+  current: TValue,
+) {
+  return typeof update === 'function'
+    ? (update as (current: TValue) => TValue)(current)
+    : update
+}

package/src/presentation-query-form-state-adapter-registry.ts

@@ -0,0 +1,25 @@
+import type { PresentationModuleDefinition } from '@cohesivesystems/presentation-core'
+import type {
+  PresentationQueryFormStateAdapter,
+  PresentationQueryFormStateAdapterRegistry,
+} from './presentation-query-form-state'
+import { createProjectedQueryFormStateAdapter } from './projected-query-form-state-adapter'
+
+export function resolvePresentationQueryFormStateAdapters(
+  module: PresentationModuleDefinition | null,
+  registry: PresentationQueryFormStateAdapterRegistry,
+): readonly PresentationQueryFormStateAdapter[] {
+  if (!module) {
+    return Object.values(registry).filter(isPresentationQueryFormStateAdapter)
+  }
+
+  return module.QueryForms
+    .map((queryForm) => registry[queryForm.Id] ?? createProjectedQueryFormStateAdapter(queryForm.Id))
+    .filter(isPresentationQueryFormStateAdapter)
+}
+
+function isPresentationQueryFormStateAdapter(
+  value: PresentationQueryFormStateAdapter | undefined,
+): value is PresentationQueryFormStateAdapter {
+  return Boolean(value)
+}

package/src/presentation-query-form-state-context.ts

@@ -0,0 +1,56 @@
+import {
+  createContext,
+  useContext,
+  type Dispatch,
+  type SetStateAction,
+} from 'react'
+
+import type {
+  InputFormDefinition,
+  PresentationQueryFormStateMap,
+  QueryFormDefinition,
+} from '@cohesivesystems/presentation-core'
+
+export interface PresentationQueryFormStateEntry<TValue = unknown> {
+  readonly appliedValue: TValue
+  readonly draftValue: TValue
+  readonly inputForm: InputFormDefinition | null
+  readonly queryForm: QueryFormDefinition | null
+  readonly queryFormId: string
+  readonly setAppliedValue: Dispatch<SetStateAction<TValue>>
+  readonly setDraftValue: Dispatch<SetStateAction<TValue>>
+}
+
+export interface PresentationQueryFormStateContextValue {
+  readonly entries: Readonly<Record<string, PresentationQueryFormStateEntry>>
+  readonly queryFormStates: PresentationQueryFormStateMap
+}
+
+export const PresentationQueryFormStateContext =
+  createContext<PresentationQueryFormStateContextValue | null>(null)
+
+export function usePresentationQueryFormState<TValue = unknown>(
+  queryFormId: string,
+) {
+  const context = useRequiredPresentationQueryFormStateContext()
+  return context.entries[queryFormId] as
+    | PresentationQueryFormStateEntry<TValue>
+    | undefined
+}
+
+export function usePresentationQueryFormStateMap() {
+  return useRequiredPresentationQueryFormStateContext().queryFormStates
+}
+
+export function usePresentationQueryFormStateEntries() {
+  return useRequiredPresentationQueryFormStateContext().entries
+}
+
+function useRequiredPresentationQueryFormStateContext() {
+  const context = useContext(PresentationQueryFormStateContext)
+  if (!context) {
+    throw new Error('Presentation query form state must be used inside PresentationQueryFormStateProvider.')
+  }
+
+  return context
+}