@cohesivesystems/presentation-react 0.1.0-alpha.1

package/src/presentation-action-group-runtime-options.ts

@@ -0,0 +1,121 @@
+import type { ReactNode } from 'react'
+
+import type {
+  ActionDefinition,
+  ActionPlacementDefinition,
+  PresentationDataSourceResolver,
+  PresentationModuleDefinition,
+  ViewDefinition,
+} from '@cohesivesystems/presentation-core'
+import type {
+  PresentationActionRuntimeRegistry,
+} from '@cohesivesystems/presentation-core'
+
+export interface PresentationActionRenderState {
+  readonly disabledReason?: ReactNode
+  readonly isDisabled?: boolean
+  readonly isHidden?: boolean
+  readonly isPending?: boolean
+  readonly label?: ReactNode
+}
+
+export interface PresentationActionGroupRenderContext<TContext> {
+  readonly context: TContext
+  readonly dataSourceResolver: PresentationDataSourceResolver
+  readonly module: Pick<PresentationModuleDefinition, 'Actions' | 'Targets'>
+  readonly view: ViewDefinition
+}
+
+export interface PresentationActionRenderContext<TContext>
+  extends PresentationActionGroupRenderContext<TContext> {
+  readonly action: ActionDefinition | null
+  readonly invalidatedDataSourceIds: readonly string[]
+  readonly isFetching: boolean
+  readonly placement: ActionPlacementDefinition
+}
+
+export interface PresentationActionGroupOptions<TContext> {
+  readonly canExecuteAction?: (context: PresentationActionRenderContext<TContext>) => boolean
+  readonly executeAction?: (context: PresentationActionRenderContext<TContext>) => Promise<void> | void
+  readonly renderActionLabel?: (context: PresentationActionRenderContext<TContext>) => ReactNode
+  readonly resolveActionState?: (
+    context: PresentationActionRenderContext<TContext>,
+  ) => PresentationActionRenderState | null | undefined
+}
+
+export interface PresentationActionGroupRuntimeOptions<TContext>
+  extends PresentationActionGroupOptions<TContext> {
+  readonly runtimes?: PresentationActionRuntimeRegistry<
+    PresentationActionRenderContext<TContext>,
+    ReactNode
+  >
+}
+
+/**
+ * Creates standard action-group options from a semantic action runtime registry.
+ */
+export function createPresentationActionGroupRuntimeOptions<TContext>({
+  canExecuteAction,
+  executeAction,
+  renderActionLabel,
+  resolveActionState,
+  runtimes,
+  ...options
+}: PresentationActionGroupRuntimeOptions<TContext> = {}): PresentationActionGroupOptions<TContext> {
+  const resolvedExecuteAction =
+    runtimes || executeAction
+      ? (context: PresentationActionRenderContext<TContext>) => {
+          const runtime = resolveRuntime(runtimes, context)
+          if (
+            runtime?.execute &&
+            !runtime.isDisabled &&
+            !runtime.isHidden &&
+            (runtime.canExecute?.(context) ?? true)
+          ) {
+            return runtime.execute(context)
+          }
+
+          return executeAction?.(context)
+        }
+      : undefined
+
+  return {
+    ...options,
+    canExecuteAction: (context) => {
+      const runtime = resolveRuntime(runtimes, context)
+      if (runtime?.isDisabled || runtime?.isHidden) {
+        return false
+      }
+
+      if (runtime?.canExecute && !runtime.canExecute(context)) {
+        return false
+      }
+
+      return canExecuteAction?.(context) ?? true
+    },
+    executeAction: resolvedExecuteAction,
+    renderActionLabel,
+    resolveActionState: (context) => {
+      const runtime = resolveRuntime(runtimes, context)
+      const baseState = resolveActionState?.(context)
+      return {
+        ...baseState,
+        disabledReason: runtime?.disabledReason ?? baseState?.disabledReason,
+        isDisabled: Boolean(baseState?.isDisabled || runtime?.isDisabled),
+        isHidden: Boolean(baseState?.isHidden || runtime?.isHidden),
+        isPending: Boolean(baseState?.isPending || runtime?.isPending),
+        label:
+          runtime?.isPending && runtime.pendingLabel
+            ? runtime.pendingLabel
+            : (runtime?.label ?? baseState?.label),
+      }
+    },
+  }
+}
+
+function resolveRuntime<TContext>(
+  runtimes: PresentationActionGroupRuntimeOptions<TContext>['runtimes'] | undefined,
+  context: PresentationActionRenderContext<TContext>,
+) {
+  return runtimes?.[context.placement.ActionId] ?? null
+}

package/src/presentation-action-runtime.ts

@@ -0,0 +1,190 @@
+import { useMutation, useQueryClient, type QueryClient } from '@tanstack/react-query'
+import { useMemo } from 'react'
+
+import type {
+  PresentationActionEndpointExecutionRequest,
+} from '@cohesivesystems/presentation-core'
+import {
+  findPresentationAction,
+  type ActionDefinition,
+  type PresentationBindingDefinition,
+  type PresentationModuleDefinition,
+  resolvePresentationActionEndpointBinding,
+} from '@cohesivesystems/presentation-core'
+
+export type { PresentationActionEndpointExecutionRequest } from '@cohesivesystems/presentation-core'
+
+export type PresentationActionEndpointExecutor = <TResult = unknown>(
+  endpointId: string,
+  request: PresentationActionEndpointExecutionRequest,
+) => Promise<TResult>
+
+export interface PresentationActionRequestPreparationContext<TInput> {
+  readonly action: ActionDefinition | null
+  readonly actionId: string
+  readonly binding: PresentationBindingDefinition | null
+  readonly endpointId: string
+  readonly input: TInput
+  readonly module: PresentationModuleDefinition | null
+}
+
+export interface PresentationActionSuccessContext<TInput, TResult> {
+  readonly action: ActionDefinition | null
+  readonly actionId: string
+  readonly endpointId: string
+  readonly input: TInput
+  readonly queryClient: QueryClient
+  readonly result: TResult
+}
+
+export interface UsePresentationActionExecutorOptions<TInput, TResult> {
+  readonly actionId: string
+  readonly componentSet?: string | null
+  readonly dataSourceId?: string | null
+  readonly dataSourceQueryKey?: (dataSourceId: string) => readonly unknown[]
+  readonly executeEndpoint: PresentationActionEndpointExecutor
+  readonly invalidateDataSourceIds?:
+    | readonly string[]
+    | ((context: PresentationActionSuccessContext<TInput, TResult>) => readonly string[])
+  readonly module: PresentationModuleDefinition | null
+  readonly prepareRequest: (
+    context: PresentationActionRequestPreparationContext<TInput>,
+  ) => PresentationActionEndpointExecutionRequest
+  readonly processResult?: (context: PresentationActionSuccessContext<TInput, TResult>) => void
+  readonly setResultQueryData?: (context: PresentationActionSuccessContext<TInput, TResult>) => void
+  readonly onSuccess?: (context: PresentationActionSuccessContext<TInput, TResult>) => void
+}
+
+export interface PresentationActionExecutor<TInput, TResult> {
+  readonly action: ActionDefinition | null
+  readonly endpointId: string | null
+  readonly error: unknown
+  readonly execute: (input: TInput) => void
+  readonly executeAsync: (input: TInput) => Promise<TResult>
+  readonly isPending: boolean
+  readonly isSuccess: boolean
+  readonly reset: () => void
+}
+
+/**
+ * Runtime projection for endpoint-backed presentation actions. It resolves the
+ * endpoint from the action definition/target bindings, prepares an endpoint
+ * request from the caller's semantic input, executes it through the app's API
+ * adapter, and applies result/query invalidation policy.
+ */
+export function usePresentationActionExecutor<TInput = void, TResult = unknown>({
+  actionId,
+  componentSet = 'cohesive.presentation.react',
+  dataSourceId,
+  dataSourceQueryKey,
+  executeEndpoint,
+  invalidateDataSourceIds,
+  module,
+  onSuccess,
+  prepareRequest,
+  processResult,
+  setResultQueryData,
+}: UsePresentationActionExecutorOptions<TInput, TResult>): PresentationActionExecutor<TInput, TResult> {
+  const queryClient = useQueryClient()
+  const action = useMemo(
+    () => findPresentationAction<ActionDefinition>(module, actionId),
+    [actionId, module],
+  )
+  const binding = useMemo(
+    () =>
+      resolvePresentationActionEndpointBinding({
+        actionId,
+        componentSet,
+        dataSourceId,
+        module,
+      }),
+    [actionId, componentSet, dataSourceId, module],
+  )
+  const endpointId = binding?.EndpointId ?? null
+  const mutation = useMutation<TResult, unknown, TInput>({
+    mutationFn: async (input) => {
+      if (!endpointId) {
+        throw new Error(`No endpoint binding is registered for action '${actionId}'.`)
+      }
+
+      return await executeEndpoint<TResult>(
+        endpointId,
+        prepareRequest({
+          action,
+          actionId,
+          binding,
+          endpointId,
+          input,
+          module,
+        }),
+      )
+    },
+    onSuccess: async (result, input) => {
+      if (!endpointId) {
+        return
+      }
+
+      const context = {
+        action,
+        actionId,
+        endpointId,
+        input,
+        queryClient,
+        result,
+      } satisfies PresentationActionSuccessContext<TInput, TResult>
+
+      setResultQueryData?.(context)
+      processResult?.(context)
+      await invalidatePresentationActionDataSources({
+        action,
+        context,
+        dataSourceQueryKey,
+        invalidateDataSourceIds,
+        queryClient,
+      })
+      onSuccess?.(context)
+    },
+  })
+
+  return {
+    action,
+    endpointId,
+    error: mutation.error,
+    execute: mutation.mutate,
+    executeAsync: mutation.mutateAsync,
+    isPending: mutation.isPending,
+    isSuccess: mutation.isSuccess,
+    reset: mutation.reset,
+  }
+}
+
+async function invalidatePresentationActionDataSources<TInput, TResult>({
+  action,
+  context,
+  dataSourceQueryKey,
+  invalidateDataSourceIds,
+  queryClient,
+}: {
+  readonly action: ActionDefinition | null
+  readonly context: PresentationActionSuccessContext<TInput, TResult>
+  readonly dataSourceQueryKey?: (dataSourceId: string) => readonly unknown[]
+  readonly invalidateDataSourceIds?:
+    | readonly string[]
+    | ((context: PresentationActionSuccessContext<TInput, TResult>) => readonly string[])
+  readonly queryClient: QueryClient
+}) {
+  if (!dataSourceQueryKey) {
+    return
+  }
+
+  const dataSourceIds =
+    typeof invalidateDataSourceIds === 'function'
+      ? invalidateDataSourceIds(context)
+      : (invalidateDataSourceIds ?? action?.Result?.InvalidateDataSourceIds ?? [])
+
+  await Promise.all(
+    Array.from(new Set(dataSourceIds)).map((dataSourceId) =>
+      queryClient.invalidateQueries({ queryKey: dataSourceQueryKey(dataSourceId) }),
+    ),
+  )
+}

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

@@ -0,0 +1,109 @@
+import { useQueries } from '@tanstack/react-query'
+import { useMemo } from 'react'
+
+import {
+  findPresentationDataSource,
+  isTanStackQueryBinding,
+  resolveDataSourceAuthorization,
+  type DataSourceDefinition,
+  type PresentationDataSourceBinding,
+  type PresentationDataSourceState,
+  type PresentationDataSourceStateMap,
+  type PresentationLocalValueDataSourceBinding,
+  type PresentationTanStackQueryDataSourceBinding,
+} from '@cohesivesystems/presentation-core'
+import { usePresentationModule } from './presentation-module-context'
+
+interface PresentationAsyncDataSourceResult {
+  readonly data: unknown
+  readonly error: unknown
+  readonly isFetching: boolean
+  readonly isPending: boolean
+  readonly refetch: () => Promise<unknown>
+}
+
+export function usePresentationDataSources(
+  bindings: readonly PresentationDataSourceBinding[],
+) {
+  const module = usePresentationModule()
+  const queryBindings = useMemo(
+    () => bindings.filter(isTanStackQueryBinding),
+    [bindings],
+  )
+  const queryResults = useQueries({
+    queries: queryBindings.map((binding) => {
+      const authorization = resolveDataSourceAuthorization(binding)
+      return {
+        enabled: (binding.enabled ?? true) && !authorization.isBlocked,
+        queryFn: binding.queryFn,
+        queryKey: binding.queryKey,
+        refetchInterval: binding.refetchInterval,
+        retry: binding.retry,
+        staleTime: binding.staleTime,
+      }
+    }),
+  })
+  const dataSources = useMemo<PresentationDataSourceStateMap>(() => {
+    const definitionsById = new Map(
+      module?.DataSources.map((definition) => [definition.Id, definition] as const) ?? [],
+    )
+    const asyncResultsByDataSourceId = new Map(
+      queryBindings.map((binding, index) => [binding.dataSourceId, queryResults[index]] as const),
+    )
+    return Object.fromEntries(
+      bindings.map((binding) => {
+        const definition =
+          definitionsById.get(binding.dataSourceId) ??
+          findPresentationDataSource(module, binding.dataSourceId)
+        const state = isTanStackQueryBinding(binding)
+          ? createAsyncDataSourceState(
+              binding,
+              asyncResultsByDataSourceId.get(binding.dataSourceId) as PresentationAsyncDataSourceResult,
+              definition,
+            )
+          : createLocalValueDataSourceState(binding, definition)
+        return [binding.dataSourceId, state]
+      }),
+    )
+  }, [bindings, module, queryBindings, queryResults])
+  return dataSources
+}
+
+function createAsyncDataSourceState(
+  binding: PresentationTanStackQueryDataSourceBinding,
+  result: PresentationAsyncDataSourceResult,
+  definition: DataSourceDefinition | null,
+): PresentationDataSourceState {
+  const authorization = resolveDataSourceAuthorization(binding)
+  return {
+    blockedLabel: authorization.blockedLabel,
+    data: result.data === undefined ? binding.fallbackData : result.data,
+    definition,
+    emptyMessage: binding.emptyMessage,
+    error: result.error,
+    isBlocked: authorization.isBlocked,
+    isFetching: result.isFetching,
+    isPending: result.isPending,
+    pendingLabel: binding.pendingLabel,
+    refetch: result.refetch,
+  }
+}
+
+function createLocalValueDataSourceState(
+  binding: PresentationLocalValueDataSourceBinding,
+  definition: DataSourceDefinition | null,
+): PresentationDataSourceState {
+  const authorization = resolveDataSourceAuthorization(binding)
+  return {
+    blockedLabel: authorization.blockedLabel,
+    data: binding.data,
+    definition,
+    emptyMessage: binding.emptyMessage,
+    error: binding.error,
+    isBlocked: authorization.isBlocked,
+    isFetching: binding.isFetching,
+    isPending: binding.isPending,
+    pendingLabel: binding.pendingLabel,
+    refetch: binding.refetch,
+  }
+}

package/src/presentation-data-source-binding.tsx

@@ -0,0 +1,24 @@
+import { type ReactNode } from 'react'
+
+import {
+  type PresentationDataSourceBinding,
+  type PresentationDataSourceStateMap,
+} from '@cohesivesystems/presentation-core'
+import { usePresentationDataSources } from './presentation-data-source-binding-runtime'
+
+export interface PresentationDataSourceBinderProps {
+  readonly bindings: readonly PresentationDataSourceBinding[]
+  readonly children: (dataSources: PresentationDataSourceStateMap) => ReactNode
+}
+
+/**
+ * Binds declared presentation data sources to runtime state for projected React
+ * components.
+ */
+export function PresentationDataSourceBinder({
+  bindings,
+  children,
+}: PresentationDataSourceBinderProps) {
+  const dataSources = usePresentationDataSources(bindings)
+  return <>{children(dataSources)}</>
+}