@cohesivesystems/presentation-react 0.1.0-alpha.1

package/src/presentation-query-form-state.tsx

@@ -0,0 +1,250 @@
+import {
+  useMemo,
+  useState,
+  type PropsWithChildren,
+  type SetStateAction,
+} from 'react'
+import { useLocation } from 'react-router'
+
+import {
+  findPresentationInputForm,
+  findPresentationQueryForm,
+  type InputFormDefinition,
+  type PresentationModuleDefinition,
+  type QueryFormDefinition,
+} from '@cohesivesystems/presentation-core'
+import { usePresentationModule } from './presentation-module-context'
+import {
+  PresentationQueryFormStateContext,
+  type PresentationQueryFormStateEntry,
+} from './presentation-query-form-state-context'
+import { resolvePresentationQueryFormStateAdapters } from './presentation-query-form-state-adapter-registry'
+import type {
+  PresentationQueryFormState,
+  PresentationQueryFormStateMap,
+} from '@cohesivesystems/presentation-core'
+
+export interface PresentationQueryFormStateAdapter<TValue extends object = object> {
+  readonly queryFormId: string
+
+  createAppliedSearch?(context: PresentationQueryFormAppliedSearchContext<TValue>): string
+  createDefaultValue(context: PresentationQueryFormStateAdapterContext): TValue
+  createSearchKey?(context: PresentationQueryFormStateAdapterContext): string
+  normalizeValue?(context: PresentationQueryFormAdapterValueContext<TValue>): TValue
+  readValueFromSearch?(context: PresentationQueryFormStateAdapterContext): TValue
+}
+
+export type PresentationQueryFormStateAdapterRegistry = Readonly<
+  Record<string, PresentationQueryFormStateAdapter | undefined>
+>
+
+export interface PresentationQueryFormStateAdapterContext {
+  readonly choiceValuesByFieldId?: Readonly<Record<string, readonly string[]>>
+  readonly inputForm: InputFormDefinition | null
+  readonly module: PresentationModuleDefinition | null
+  readonly queryForm: QueryFormDefinition | null
+  readonly search: string
+}
+
+export interface PresentationQueryFormAdapterValueContext<TValue extends object>
+  extends PresentationQueryFormStateAdapterContext {
+  readonly choiceValuesByFieldId: Readonly<Record<string, readonly string[]>>
+  readonly value: TValue
+}
+
+export type PresentationQueryFormAppliedSearchContext<TValue extends object> =
+  PresentationQueryFormAdapterValueContext<TValue>
+
+interface PresentationQueryFormStateProviderProps extends PropsWithChildren {
+  readonly adapterRegistry: PresentationQueryFormStateAdapterRegistry
+}
+
+interface PresentationQueryFormInitialState {
+  readonly initialValue: object
+  readonly inputForm: InputFormDefinition | null
+  readonly queryForm: QueryFormDefinition | null
+  readonly queryFormId: string
+}
+
+interface PresentationQueryFormStoredState {
+  readonly appliedValue: unknown
+  readonly draftValue: unknown
+}
+
+export function PresentationQueryFormStateProvider({
+  adapterRegistry,
+  children,
+}: PresentationQueryFormStateProviderProps) {
+  const location = useLocation()
+  const module = usePresentationModule()
+  const adapters = useMemo(
+    () => resolvePresentationQueryFormStateAdapters(module, adapterRegistry),
+    [adapterRegistry, module],
+  )
+  const initialStates = useMemo(
+    () =>
+      adapters.map((adapter) =>
+        createInitialQueryFormState(adapter, module, location.search),
+      ),
+    [adapters, location.search, module],
+  )
+  const stateKey = useMemo(
+    () =>
+      adapters.map((adapter) =>
+        createQueryFormStateKey(adapter, module, location.search),
+      ).join('|'),
+    [adapters, location.search, module],
+  )
+
+  return (
+    <PresentationQueryFormStateScope
+      initialStates={initialStates}
+      key={stateKey}
+    >
+      {children}
+    </PresentationQueryFormStateScope>
+  )
+}
+
+function PresentationQueryFormStateScope({
+  children,
+  initialStates,
+}: PropsWithChildren<{
+  readonly initialStates: readonly PresentationQueryFormInitialState[]
+}>) {
+  const [storedStates, setStoredStates] = useState<Record<string, PresentationQueryFormStoredState>>(() =>
+    Object.fromEntries(
+      initialStates.map((state) => [
+        state.queryFormId,
+        {
+          appliedValue: state.initialValue,
+          draftValue: state.initialValue,
+        } satisfies PresentationQueryFormStoredState,
+      ]),
+    ),
+  )
+  const entries = useMemo(
+    () =>
+      Object.fromEntries(
+        initialStates.map((state) => {
+          const storedState = storedStates[state.queryFormId] ?? {
+            appliedValue: state.initialValue,
+            draftValue: state.initialValue,
+          }
+          return [
+            state.queryFormId,
+            {
+              appliedValue: storedState.appliedValue,
+              draftValue: storedState.draftValue,
+              inputForm: state.inputForm,
+              queryForm: state.queryForm,
+              queryFormId: state.queryFormId,
+              setAppliedValue: (update: SetStateAction<unknown>) =>
+                setStoredStates((current) =>
+                  updateStoredQueryFormState(current, state.queryFormId, 'appliedValue', update),
+                ),
+              setDraftValue: (update: SetStateAction<unknown>) =>
+                setStoredStates((current) =>
+                  updateStoredQueryFormState(current, state.queryFormId, 'draftValue', update),
+                ),
+            } satisfies PresentationQueryFormStateEntry,
+          ]
+        }),
+      ),
+    [initialStates, storedStates],
+  )
+  const queryFormStates = useMemo(
+    () =>
+      Object.fromEntries(
+        Object.values(entries).flatMap((entry) =>
+          entry.queryForm
+            ? [[
+                entry.queryFormId,
+                {
+                  appliedValue: entry.appliedValue,
+                  draftValue: entry.draftValue,
+                  queryForm: entry.queryForm,
+                  queryFormId: entry.queryFormId,
+                } satisfies PresentationQueryFormState,
+              ]]
+            : [],
+        ),
+      ) satisfies PresentationQueryFormStateMap,
+    [entries],
+  )
+  const value = useMemo(
+    () => ({
+      entries,
+      queryFormStates,
+    }),
+    [entries, queryFormStates],
+  )
+
+  return (
+    <PresentationQueryFormStateContext.Provider value={value}>
+      {children}
+    </PresentationQueryFormStateContext.Provider>
+  )
+}
+
+function createInitialQueryFormState(
+  adapter: PresentationQueryFormStateAdapter,
+  module: PresentationModuleDefinition | null,
+  search: string,
+): PresentationQueryFormInitialState {
+  const adapterContext = createAdapterContext(adapter, module, search)
+  return {
+    initialValue: adapter.readValueFromSearch?.(adapterContext) ??
+      adapter.createDefaultValue(adapterContext),
+    inputForm: adapterContext.inputForm,
+    queryForm: adapterContext.queryForm,
+    queryFormId: adapter.queryFormId,
+  }
+}
+
+function createQueryFormStateKey(
+  adapter: PresentationQueryFormStateAdapter,
+  module: PresentationModuleDefinition | null,
+  search: string,
+) {
+  const adapterContext = createAdapterContext(adapter, module, search)
+  return `${adapter.queryFormId}:${adapter.createSearchKey?.(adapterContext) ?? ''}`
+}
+
+function createAdapterContext(
+  adapter: PresentationQueryFormStateAdapter,
+  module: PresentationModuleDefinition | null,
+  search: string,
+): PresentationQueryFormStateAdapterContext {
+  const queryForm = findPresentationQueryForm(module, adapter.queryFormId)
+  return {
+    inputForm: queryForm ? findPresentationInputForm(module, queryForm.FormId) : null,
+    module,
+    queryForm,
+    search,
+  }
+}
+
+function updateStoredQueryFormState(
+  current: Record<string, PresentationQueryFormStoredState>,
+  queryFormId: string,
+  field: keyof PresentationQueryFormStoredState,
+  update: SetStateAction<unknown>,
+) {
+  const currentState = current[queryFormId] ?? {
+    appliedValue: {},
+    draftValue: {},
+  }
+  const currentValue = currentState[field]
+  const nextValue = typeof update === 'function'
+    ? (update as (value: unknown) => unknown)(currentValue)
+    : update
+
+  return {
+    ...current,
+    [queryFormId]: {
+      ...currentState,
+      [field]: nextValue,
+    },
+  }
+}

package/src/presentation-renderer-registry.ts

@@ -0,0 +1,214 @@
+import type { ReactNode } from 'react'
+
+import {
+  createPresentationEnumDiscriminator,
+  mergePresentationRendererRegistries as mergeCorePresentationRendererRegistries,
+  resolvePresentationViewRenderer as resolveCorePresentationViewRenderer,
+  type FieldPresentationDefinition,
+  type PresentationDataSourceResolver,
+  type PresentationModuleDefinition,
+  type PresentationSurface,
+  type PresentationCompositeRendererRegistry as CorePresentationCompositeRendererRegistry,
+  type PresentationRendererBindingModuleProjection,
+  type PresentationRendererRegistry as CorePresentationRendererRegistry,
+  type PresentationViewRendererResolution as CorePresentationViewRendererResolution,
+  type PresentationViewRendererResolutionSource,
+  type ViewDefinition,
+} from '@cohesivesystems/presentation-core'
+import { presentationTargetKinds } from '@cohesivesystems/presentation-contracts'
+
+/**
+ * Options that let a view renderer project only selected regions of a view.
+ */
+export interface PresentationViewRegionRenderOptions {
+  /** Region ids to render. Omit this to render every region declared by the view. */
+  readonly includeRegionIds?: readonly string[]
+}
+
+/**
+ * Runtime context supplied to a concrete renderer for a semantic presentation view.
+ *
+ * @typeParam TContext - App-specific projection context carried through rendering.
+ */
+export interface PresentationViewRenderContext<TContext> {
+  /** Component key resolved from presentation target bindings, when matched. */
+  readonly componentKey: string | null
+
+  /** Component role resolved from presentation target bindings, when matched. */
+  readonly componentRole: string | null
+
+  /** App-specific runtime context supplied by the projection host. */
+  readonly context: TContext
+
+  /** Resolver for semantic data sources referenced by the view or nested renderers. */
+  readonly dataSourceResolver: PresentationDataSourceResolver
+
+  /** Presentation module that owns the projected view graph and bindings. */
+  readonly module: PresentationModuleDefinition
+
+  /** Renders this view's regions, optionally restricted to specific region ids. */
+  readonly renderRegions: (
+    view: ViewDefinition,
+    options?: PresentationViewRegionRenderOptions,
+  ) => ReactNode
+
+  /** Renders another view from the same presentation module by semantic view id. */
+  readonly renderView: (viewId: string) => ReactNode
+
+  /** Surface on which the current view is being projected. */
+  readonly surface: PresentationSurface
+
+  /** Semantic view definition being adapted to React. */
+  readonly view: ViewDefinition
+}
+
+/**
+ * React renderer for a semantic presentation view.
+ */
+export type PresentationViewRenderer<TContext> = (
+  context: PresentationViewRenderContext<TContext>,
+) => ReactNode
+
+/**
+ * Runtime context supplied when rendering a scalar or structured presentation value.
+ *
+ * @typeParam TContext - App-specific projection context carried through rendering.
+ */
+export interface PresentationValueRenderContext<TContext> {
+  /** App-specific runtime context supplied by the projection host. */
+  readonly context: TContext
+
+  /** Resolver for data sources available to value renderers. */
+  readonly dataSourceResolver: PresentationDataSourceResolver
+
+  /** Field metadata that describes the value, when the value came from a field. */
+  readonly field?: FieldPresentationDefinition | null
+
+  /** Presentation module that owns the value's field and binding definitions. */
+  readonly module: PresentationModuleDefinition
+
+  /** Raw value selected from the semantic data source. */
+  readonly value: unknown
+}
+
+/**
+ * React renderer for an individual presentation value.
+ */
+export type PresentationValueRenderer<TContext> = (
+  context: PresentationValueRenderContext<TContext>,
+) => ReactNode
+
+/**
+ * Runtime context supplied to presentation controls that are not tied to a single view.
+ *
+ * @typeParam TContext - App-specific projection context carried through rendering.
+ */
+export interface PresentationControlRenderContext<TContext> {
+  /** App-specific runtime context supplied by the projection host. */
+  readonly context: TContext
+
+  /** Resolver for data sources available to control renderers. */
+  readonly dataSourceResolver: PresentationDataSourceResolver
+
+  /** Presentation module that owns the control binding definitions. */
+  readonly module: PresentationModuleDefinition
+}
+
+/**
+ * React renderer for an auxiliary presentation control.
+ */
+export type PresentationControlRenderer<TContext> = (
+  context: PresentationControlRenderContext<TContext>,
+) => ReactNode
+
+export type PresentationCompositeRendererRegistry<TContext> =
+  CorePresentationCompositeRendererRegistry<PresentationViewRenderer<TContext>>
+
+/**
+ * Complete renderer registry used by the React presentation projection runtime.
+ */
+export interface PresentationRendererRegistry<TContext>
+  extends CorePresentationRendererRegistry<
+    PresentationViewRenderer<TContext>,
+    PresentationControlRenderer<TContext>,
+    PresentationValueRenderer<TContext>
+  > {
+  /** Composite renderers that adapt whole semantic views. */
+  readonly composites?: PresentationCompositeRendererRegistry<TContext>
+
+  /** Control renderers keyed by presentation control ids or component keys. */
+  readonly controls?: Readonly<Record<string, PresentationControlRenderer<TContext>>>
+
+  /** Value renderers keyed by semantic value or field renderer ids. */
+  readonly values?: Readonly<Record<string, PresentationValueRenderer<TContext>>>
+}
+
+export type PresentationViewRendererResolution<TContext> =
+  CorePresentationViewRendererResolution<PresentationViewRenderer<TContext>>
+
+export type { PresentationRendererBindingModuleProjection }
+
+export type { PresentationViewRendererResolutionSource }
+
+export interface ResolvePresentationViewRendererOptions<
+  TContext,
+  TModule extends PresentationRendererBindingModuleProjection =
+    PresentationRendererBindingModuleProjection,
+> {
+  readonly componentSet?: string | null
+  readonly module: TModule
+  readonly registry: PresentationRendererRegistry<TContext>
+  readonly routeId?: string | null
+  readonly view: ViewDefinition
+}
+
+/**
+ * Combines renderer registries in declaration order, with later registries
+ * overriding earlier renderer keys and fallback renderers.
+ */
+export function mergePresentationRendererRegistries<TContext>(
+  ...registries: readonly PresentationRendererRegistry<TContext>[]
+): PresentationRendererRegistry<TContext> {
+  return mergeCorePresentationRendererRegistries<
+    PresentationViewRenderer<TContext>,
+    PresentationControlRenderer<TContext>,
+    PresentationValueRenderer<TContext>
+  >(...registries) as PresentationRendererRegistry<TContext>
+}
+
+/**
+ * Resolves the React renderer for a semantic view while keeping binding
+ * resolution in the framework-neutral core package.
+ */
+export function resolvePresentationViewRenderer<
+  TContext,
+  TModule extends PresentationRendererBindingModuleProjection =
+    PresentationRendererBindingModuleProjection,
+>({
+  componentSet,
+  module,
+  registry,
+  routeId,
+  view,
+}: ResolvePresentationViewRendererOptions<
+  TContext,
+  TModule
+>): PresentationViewRendererResolution<TContext> {
+  return resolveCorePresentationViewRenderer<
+    PresentationViewRenderer<TContext>,
+    TModule
+  >({
+    componentSet,
+    module,
+    registry,
+    routeId,
+    targetKind: reactPresentationTargetKind,
+    view,
+  })
+}
+
+const reactPresentationTargetKind = createPresentationEnumDiscriminator(
+  presentationTargetKinds,
+  'react',
+  'React',
+)

package/src/presentation-standards-context.ts

@@ -0,0 +1,21 @@
+import {
+  createContext,
+  useContext,
+  type Context,
+} from 'react'
+
+export function createPresentationStandardsContext<TStandards>() {
+  return createContext<TStandards | null>(null)
+}
+
+export function usePresentationStandards<TStandards>(
+  context: Context<TStandards | null>,
+  label = 'Presentation standards',
+) {
+  const standards = useContext(context)
+  if (!standards) {
+    throw new Error(`${label} are not available.`)
+  }
+
+  return standards
+}

package/src/presentation-standards-provider.tsx

@@ -0,0 +1,44 @@
+import {
+  useContext,
+  useMemo,
+  type Context,
+  type PropsWithChildren,
+} from 'react'
+
+import type { PresentationStandardsComposer } from '@cohesivesystems/presentation-core'
+
+export interface PresentationStandardsProviderProps<TStandards, TContribution>
+  extends PropsWithChildren {
+  readonly compose: PresentationStandardsComposer<TStandards, TContribution>
+  readonly context: Context<TStandards | null>
+  readonly standards: TContribution
+}
+
+/**
+ * Generic standards provider. Nested providers compose their local contribution
+ * over the inherited standards, so feature areas can override or enrich app
+ * defaults without replacing the whole standards object.
+ */
+export function PresentationStandardsProvider<TStandards, TContribution>({
+  children,
+  compose,
+  context,
+  standards,
+}: PresentationStandardsProviderProps<TStandards, TContribution>) {
+  const StandardsContext = context
+  const parent = useContext(StandardsContext)
+  const value = useMemo(
+    () => (
+      parent
+        ? compose(parent as unknown as TContribution, standards)
+        : compose(standards)
+    ),
+    [compose, parent, standards],
+  )
+
+  return (
+    <StandardsContext.Provider value={value}>
+      {children}
+    </StandardsContext.Provider>
+  )
+}

package/src/projected-document-action-runtime-bindings.ts

@@ -0,0 +1,132 @@
+import type {
+  PresentationActionRuntimeBinding,
+} from '@cohesivesystems/presentation-core'
+import {
+  createPresentationActionRuntimeBinding,
+} from '@cohesivesystems/presentation-core'
+import {
+  resolveActionPendingLabel,
+} from '@cohesivesystems/presentation-core'
+import type {
+  ProjectedDocumentActionRuntime,
+  ProjectedDocumentJsonValidationState,
+} from './projected-document-action-runtime'
+import {
+  actionSemanticsKinds,
+  documentWorkspaceActionKinds,
+  localDocumentEditorActionKinds,
+} from '@cohesivesystems/presentation-contracts'
+
+export interface ProjectDocumentActionRuntimeBindingsOptions<
+  TLabel = string,
+> {
+  readonly formatDocument?: () => void
+  readonly hasResource: boolean
+  readonly isEditorDirty: boolean
+  readonly jsonValidation: ProjectedDocumentJsonValidationState
+  readonly pendingLabels?: {
+    readonly save?: TLabel
+  }
+  readonly resetDocument?: () => void
+  readonly runtime: ProjectedDocumentActionRuntime
+}
+
+/**
+ * Projects generic document action runtime state into adapter-neutral action
+ * bindings. The runtime owns the semantic document mechanics; UI adapters own
+ * how these bindings become concrete controls.
+ */
+export function projectDocumentActionRuntimeBindings<
+  TExecuteContext = unknown,
+  TLabel = string,
+>({
+  formatDocument,
+  hasResource,
+  isEditorDirty,
+  jsonValidation,
+  pendingLabels,
+  resetDocument,
+  runtime,
+}: ProjectDocumentActionRuntimeBindingsOptions<
+  TLabel
+>): readonly PresentationActionRuntimeBinding<TExecuteContext, TLabel>[] {
+  const savePendingLabel = resolveActionPendingLabel({
+    action: runtime.actions.save,
+    fallback: pendingLabels?.save ?? ('Saving' as TLabel),
+  })
+  const saveCommitPendingLabel = resolveActionPendingLabel({
+    action: runtime.actions.saveCommit,
+    fallback: savePendingLabel,
+  })
+
+  return [
+    createPresentationActionRuntimeBinding<TExecuteContext, TLabel>({
+      documentWorkspaceKind: documentWorkspaceActionKinds.saveReview,
+      id: 'document-save-preview-flow',
+      semanticsKind: actionSemanticsKinds.documentWorkspace,
+      project: () => ({
+        execute: runtime.requestSaveReview,
+        isDisabled:
+          !isEditorDirty ||
+          !jsonValidation.ok ||
+          !runtime.save.endpointId ||
+          runtime.save.isPending ||
+          runtime.isSaveReviewOpen,
+        isHidden: !hasResource,
+        isPending: runtime.save.isPending,
+        pendingLabel: savePendingLabel,
+      }),
+    }),
+    createPresentationActionRuntimeBinding<TExecuteContext, TLabel>({
+      documentWorkspaceKind: documentWorkspaceActionKinds.saveCommit,
+      id: 'accept-save-review',
+      semanticsKind: actionSemanticsKinds.documentWorkspace,
+      project: () => ({
+        execute: runtime.acceptSaveReview,
+        isDisabled: runtime.save.isPending,
+        isHidden: !runtime.isSaveReviewOpen,
+        isPending: runtime.save.isPending,
+        pendingLabel: saveCommitPendingLabel,
+      }),
+    }),
+    createPresentationActionRuntimeBinding<TExecuteContext, TLabel>({
+      documentWorkspaceKind: documentWorkspaceActionKinds.saveCancel,
+      id: 'cancel-save-review',
+      semanticsKind: actionSemanticsKinds.documentWorkspace,
+      project: () => ({
+        execute: runtime.cancelSaveReview,
+        isDisabled: runtime.save.isPending,
+        isHidden: !runtime.isSaveReviewOpen,
+      }),
+    }),
+    createPresentationActionRuntimeBinding<TExecuteContext, TLabel>({
+      documentWorkspaceKind: documentWorkspaceActionKinds.saveRevert,
+      id: 'revert-save-review',
+      semanticsKind: actionSemanticsKinds.documentWorkspace,
+      project: () => ({
+        execute: runtime.resetSaveReview,
+        isDisabled: runtime.save.isPending,
+        isHidden: !runtime.isSaveReviewOpen,
+      }),
+    }),
+    createPresentationActionRuntimeBinding<TExecuteContext, TLabel>({
+      id: 'reset-json-document',
+      localDocumentEditorKind: localDocumentEditorActionKinds.reset,
+      semanticsKind: actionSemanticsKinds.localDocumentEditor,
+      project: () => ({
+        execute: resetDocument ?? runtime.resetDocument,
+        isHidden: !hasResource,
+      }),
+    }),
+    createPresentationActionRuntimeBinding<TExecuteContext, TLabel>({
+      id: 'format-json-document',
+      localDocumentEditorKind: localDocumentEditorActionKinds.format,
+      semanticsKind: actionSemanticsKinds.localDocumentEditor,
+      project: () => ({
+        execute: formatDocument ?? runtime.formatDocument,
+        isDisabled: !jsonValidation.ok,
+        isHidden: !hasResource,
+      }),
+    }),
+  ]
+}