@cohesivesystems/presentation-core 0.1.0-alpha.1

package/src/query-form-url-state.ts

@@ -0,0 +1,346 @@
+import type {
+  InputFormDefinition,
+  QueryFormDefinition,
+  QueryFormUrlPolicyDefinition,
+} from './module'
+import {
+  readObjectPath,
+  writeObjectPath,
+} from './object-path'
+
+export interface QueryFormUrlFieldBinding {
+  readonly fieldId: string
+  readonly valuePath: string
+}
+
+export interface QueryFormUrlFieldCodec<TValue extends object> {
+  readonly deleteParams?: (context: QueryFormUrlFieldDeleteContext<TValue>) => void
+  readonly read?: (context: QueryFormUrlFieldReadContext<TValue>) => unknown
+  readonly write?: (context: QueryFormUrlFieldWriteContext<TValue>) => void
+}
+
+export type QueryFormUrlFieldCodecs<TValue extends object> = Readonly<
+  Record<string, QueryFormUrlFieldCodec<TValue> | undefined>
+>
+
+export interface QueryFormUrlFieldDeleteContext<TValue extends object> {
+  readonly defaultValue: TValue
+  readonly field: QueryFormUrlFieldBinding
+  readonly key: string
+  readonly params: URLSearchParams
+  readonly queryForm: QueryFormDefinition | null
+}
+
+export interface QueryFormUrlFieldReadContext<TValue extends object>
+  extends QueryFormUrlFieldDeleteContext<TValue> {
+  readonly defaultFieldValue: unknown
+}
+
+export interface QueryFormUrlFieldWriteContext<TValue extends object>
+  extends QueryFormUrlFieldReadContext<TValue> {
+  readonly allValues: readonly string[]
+  readonly fieldValue: unknown
+  readonly value: TValue
+}
+
+export interface QueryFormUrlValueOptions<TValue extends object> {
+  readonly defaultValue: TValue
+  readonly fieldCodecs?: QueryFormUrlFieldCodecs<TValue>
+  readonly fields: readonly QueryFormUrlFieldBinding[]
+  readonly policy?: QueryFormUrlPolicyDefinition | null
+  readonly queryForm?: QueryFormDefinition | null
+  readonly search: string
+}
+
+export interface CreateQueryFormUrlSearchOptions<TValue extends object>
+  extends QueryFormUrlValueOptions<TValue> {
+  readonly allValuesByFieldId?: Readonly<Record<string, readonly string[] | undefined>>
+  readonly value: TValue
+}
+
+export function createQueryFormUrlFields(
+  inputForm: InputFormDefinition | null,
+  queryForm: QueryFormDefinition | null,
+): readonly QueryFormUrlFieldBinding[] {
+  if (!inputForm) {
+    return []
+  }
+
+  const targetFieldIds = new Set([
+    ...(queryForm?.Target.Predicates.map((predicate) => predicate.FieldId) ?? []),
+    ...(queryForm?.Target.Result.RequestBindings.map((binding) => binding.FieldId) ?? []),
+  ])
+  const includeAllFields = targetFieldIds.size === 0
+
+  return inputForm.Fields
+    .filter((field) =>
+      field.ValuePath &&
+      (includeAllFields || targetFieldIds.has(field.Id) || targetFieldIds.has(field.FieldId))
+    )
+    .map((field) => ({
+      fieldId: field.Id,
+      valuePath: field.ValuePath,
+    }))
+}
+
+export function readQueryFormUrlValue<TValue extends object>({
+  defaultValue,
+  fieldCodecs = {},
+  fields,
+  policy,
+  queryForm = null,
+  search,
+}: QueryFormUrlValueOptions<TValue>): TValue {
+  const urlPolicy = resolveQueryFormUrlPolicy(queryForm, policy)
+  if (!urlPolicy) {
+    return clonePlainValue(defaultValue)
+  }
+
+  const params = new URLSearchParams(search)
+  const result = clonePlainValue(defaultValue)
+
+  for (const field of fields) {
+    const key = createQueryFormUrlFieldParamKey(queryForm, urlPolicy, field.fieldId)
+    const defaultFieldValue = readObjectPath(defaultValue, field.valuePath)
+    const codec = fieldCodecs[field.fieldId]
+    const nextValue = codec?.read
+      ? codec.read({
+          defaultFieldValue,
+          defaultValue,
+          field,
+          key,
+          params,
+          queryForm,
+        })
+      : readDefaultQueryFormUrlFieldValue(params, key, defaultFieldValue)
+
+    if (nextValue !== undefined) {
+      writeObjectPath(result as Record<string, unknown>, field.valuePath, nextValue)
+    }
+  }
+
+  return result
+}
+
+export function createQueryFormUrlSearch<TValue extends object>({
+  allValuesByFieldId = {},
+  defaultValue,
+  fieldCodecs = {},
+  fields,
+  policy,
+  queryForm = null,
+  search,
+  value,
+}: CreateQueryFormUrlSearchOptions<TValue>) {
+  const urlPolicy = resolveQueryFormUrlPolicy(queryForm, policy)
+  if (!urlPolicy) {
+    return normalizeSearch(search)
+  }
+
+  const params = new URLSearchParams(search)
+
+  for (const field of fields) {
+    const key = createQueryFormUrlFieldParamKey(queryForm, urlPolicy, field.fieldId)
+    const codec = fieldCodecs[field.fieldId]
+    if (codec?.deleteParams) {
+      codec.deleteParams({ defaultValue, field, key, params, queryForm })
+    } else {
+      params.delete(key)
+    }
+  }
+
+  for (const field of fields) {
+    const key = createQueryFormUrlFieldParamKey(queryForm, urlPolicy, field.fieldId)
+    const defaultFieldValue = readObjectPath(defaultValue, field.valuePath)
+    const fieldValue = readObjectPath(value, field.valuePath)
+    const codec = fieldCodecs[field.fieldId]
+
+    if (codec?.write) {
+      codec.write({
+        allValues: allValuesByFieldId[field.fieldId] ?? [],
+        defaultFieldValue,
+        defaultValue,
+        field,
+        fieldValue,
+        key,
+        params,
+        queryForm,
+        value,
+      })
+    } else {
+      writeDefaultQueryFormUrlFieldValue(
+        params,
+        key,
+        fieldValue,
+        defaultFieldValue,
+        allValuesByFieldId[field.fieldId] ?? [],
+      )
+    }
+  }
+
+  const nextSearch = params.toString()
+  return nextSearch.length > 0 ? `?${nextSearch}` : ''
+}
+
+export function createQueryFormUrlSearchKey<TValue extends object>(
+  options: QueryFormUrlValueOptions<TValue> &
+    Pick<CreateQueryFormUrlSearchOptions<TValue>, 'allValuesByFieldId'>,
+) {
+  const value = readQueryFormUrlValue(options)
+  return createQueryFormUrlSearch({
+    ...options,
+    search: '',
+    value,
+  })
+}
+
+export function createQueryFormUrlFieldParamKey(
+  queryForm: QueryFormDefinition | null,
+  policy: QueryFormUrlPolicyDefinition,
+  fieldId: string,
+) {
+  const prefix = toQueryParamSegment(
+    policy.ParameterPrefix?.trim() || queryForm?.Id || 'query',
+  )
+  return `${prefix}_${toQueryParamSegment(fieldId)}`
+}
+
+function resolveQueryFormUrlPolicy(
+  queryForm: QueryFormDefinition | null,
+  policy: QueryFormUrlPolicyDefinition | null | undefined,
+) {
+  const resolvedPolicy = policy ?? queryForm?.Target.State.Url ?? null
+  return resolvedPolicy?.IsEnabled && resolvedPolicy.IncludeAppliedFilters
+    ? resolvedPolicy
+    : null
+}
+
+function readDefaultQueryFormUrlFieldValue(
+  params: URLSearchParams,
+  key: string,
+  defaultValue: unknown,
+) {
+  const values = params.getAll(key).map((value) => value.trim()).filter(Boolean)
+  if (values.length === 0) {
+    return defaultValue
+  }
+
+  if (Array.isArray(defaultValue)) {
+    return normalizeStringSet(values)
+  }
+
+  if (typeof defaultValue === 'boolean') {
+    const value = values[0]?.toLocaleLowerCase()
+    if (value === 'true') {
+      return true
+    }
+    if (value === 'false') {
+      return false
+    }
+    return defaultValue
+  }
+
+  if (typeof defaultValue === 'number') {
+    const parsed = Number.parseFloat(values[0] ?? '')
+    return Number.isFinite(parsed) ? parsed : defaultValue
+  }
+
+  return values[0] ?? defaultValue
+}
+
+function writeDefaultQueryFormUrlFieldValue(
+  params: URLSearchParams,
+  key: string,
+  value: unknown,
+  defaultValue: unknown,
+  allValues: readonly string[],
+) {
+  if (Array.isArray(value)) {
+    const selectedValues = normalizeStringSet(value)
+    if (
+      selectedValues.length === 0 ||
+      areStringSetsEqual(selectedValues, normalizeStringSet(allValues)) ||
+      areStringSetsEqual(selectedValues, normalizeStringSet(asStringArray(defaultValue)))
+    ) {
+      return
+    }
+
+    selectedValues.forEach((selectedValue) => params.append(key, selectedValue))
+    return
+  }
+
+  if (typeof value === 'string') {
+    const nextValue = value.trim()
+    const defaultText = typeof defaultValue === 'string' ? defaultValue.trim() : ''
+    if (nextValue && nextValue !== defaultText) {
+      params.set(key, nextValue)
+    }
+    return
+  }
+
+  if (typeof value === 'boolean') {
+    if (value !== defaultValue) {
+      params.set(key, String(value))
+    }
+    return
+  }
+
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    if (value !== defaultValue) {
+      params.set(key, String(value))
+    }
+  }
+}
+
+function clonePlainValue<TValue>(value: TValue): TValue {
+  if (Array.isArray(value)) {
+    return value.map(clonePlainValue) as TValue
+  }
+
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entryValue]) => [key, clonePlainValue(entryValue)]),
+    ) as TValue
+  }
+
+  return value
+}
+
+function normalizeSearch(search: string) {
+  if (!search) {
+    return ''
+  }
+
+  return search.startsWith('?') ? search : `?${search}`
+}
+
+function toQueryParamSegment(value: string) {
+  return value
+    .trim()
+    .replace(/[^a-zA-Z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .toLocaleLowerCase()
+}
+
+function asStringArray(value: unknown) {
+  return Array.isArray(value) ? value : []
+}
+
+function normalizeStringSet(values: readonly unknown[]) {
+  return Array.from(
+    new Set(
+      values
+        .map((value) => String(value).trim())
+        .filter((value) => value.length > 0),
+    ),
+  )
+}
+
+function areStringSetsEqual(left: readonly string[], right: readonly string[]) {
+  if (left.length === 0 || right.length === 0 || left.length !== right.length) {
+    return false
+  }
+
+  const rightValues = new Set(right)
+  return left.every((value) => rightValues.has(value))
+}

package/src/query-offset-page.ts

@@ -0,0 +1,50 @@
+export interface QueryOffsetPageResult<TItem> {
+  readonly Items: TItem[]
+  readonly Limit: number
+  readonly Offset: number
+}
+
+export type QueryOffsetPageInput =
+  | URLSearchParams
+  | {
+      readonly Limit?: unknown
+      readonly Offset?: unknown
+      readonly limit?: unknown
+      readonly offset?: unknown
+    }
+
+export function queryOffsetPage<TItem>(
+  items: readonly TItem[],
+  query: QueryOffsetPageInput,
+): QueryOffsetPageResult<TItem> {
+  const limit = readQueryInteger(query, 'limit', 'Limit', 10)
+  const offset = readQueryInteger(query, 'offset', 'Offset', 0)
+  return {
+    Items: items.slice(offset, offset + limit),
+    Limit: limit,
+    Offset: offset,
+  }
+}
+
+function readQueryInteger(
+  query: QueryOffsetPageInput,
+  lowerName: 'limit' | 'offset',
+  upperName: 'Limit' | 'Offset',
+  fallback: number,
+) {
+  if (query instanceof URLSearchParams) {
+    return readInteger(query.get(lowerName) ?? query.get(upperName), fallback)
+  }
+
+  return readInteger(query[lowerName] ?? query[upperName], fallback)
+}
+
+function readInteger(value: unknown, fallback: number) {
+  if (value === null || value === undefined || value === '') {
+    return fallback
+  }
+
+  const text = Array.isArray(value) ? value[0] : value
+  const parsed = Number.parseInt(String(text), 10)
+  return Number.isFinite(parsed) ? parsed : fallback
+}

package/src/relation-query-input-form-target.ts

@@ -0,0 +1,61 @@
+import type {
+  DataSourceQueryDefinition,
+  InputFormDefinition,
+  QueryFormDefinition,
+  ViewDefinition,
+} from './module'
+import type { PresentationDataSourceResolver } from './presentation-data-source-runtime'
+import { resolvePresentationViewDataSourceIds } from './presentation-data-source-runtime'
+import type { ProjectedInputFormTargetContext } from './projected-input-form-runtime'
+
+export function createRelationQueryInputFormTarget({
+  dataSourceResolver,
+  inputForm,
+  queryForm,
+  view,
+}: {
+  readonly dataSourceResolver: PresentationDataSourceResolver
+  readonly inputForm: InputFormDefinition
+  readonly queryForm: QueryFormDefinition
+  readonly view: ViewDefinition
+}): ProjectedInputFormTargetContext {
+  return {
+    queryDefinition: resolveProjectedQueryDefinition({
+      dataSourceResolver,
+      inputForm,
+      queryForm,
+      view,
+    }),
+    queryForm,
+    stateId: inputForm.SharedStateId ?? queryForm.Target.State.StateId,
+  }
+}
+
+function resolveProjectedQueryDefinition({
+  dataSourceResolver,
+  inputForm,
+  queryForm,
+  view,
+}: {
+  readonly dataSourceResolver: PresentationDataSourceResolver
+  readonly inputForm: InputFormDefinition
+  readonly queryForm: QueryFormDefinition
+  readonly view: ViewDefinition
+}): DataSourceQueryDefinition | null {
+  const candidateDataSourceIds = [
+    inputForm.StateDataSourceId,
+    queryForm.Target.State.DraftDataSourceId,
+    queryForm.Target.Result.DataSourceId,
+    queryForm.Target.State.ResultDataSourceId,
+    ...resolvePresentationViewDataSourceIds(view),
+  ].filter((dataSourceId): dataSourceId is string => Boolean(dataSourceId))
+
+  for (const dataSourceId of Array.from(new Set(candidateDataSourceIds))) {
+    const query = dataSourceResolver.resolve(dataSourceId)?.definition?.Query
+    if (query) {
+      return query
+    }
+  }
+
+  return null
+}

package/src/scope-selection.ts

@@ -0,0 +1,201 @@
+/**
+ * Request-selected authorization scope for API calls made by a presentation host.
+ */
+export type PresentationScopeRequestSelection =
+  | { readonly mode: 'default' }
+  | { readonly mode: 'single'; readonly scopeId: string | null }
+  | { readonly mode: 'multiple'; readonly scopeIds: readonly string[] }
+  | { readonly mode: 'all' }
+
+/**
+ * Scope visible to an authenticated principal.
+ */
+export interface PresentationScopeAccess<TMetadata = unknown> {
+  /** Stable scope id. */
+  readonly id: string
+
+  /** Human-facing scope label. */
+  readonly label: string
+
+  /** Optional semantic scope kind, for example tenant, workspace, or organization. */
+  readonly kind?: string | null
+
+  /** Capability ids granted inside this scope. */
+  readonly capabilities?: readonly string[]
+
+  /** Whether this scope is the principal's default scope. */
+  readonly isDefault?: boolean
+
+  /** Host-specific source object for adapters that need to preserve more detail. */
+  readonly metadata?: TMetadata
+}
+
+/**
+ * Header names and formatting used to project selected scopes into API requests.
+ */
+export interface PresentationScopeRequestHeaderOptions {
+  /** Header carrying one selected scope id. */
+  readonly singleScopeHeaderName: string
+
+  /** Header carrying comma-separated selected scope ids. */
+  readonly multipleScopesHeaderName: string
+
+  /** Header carrying the requested selection mode. */
+  readonly scopeModeHeaderName: string
+
+  /** Header value used for multi-scope requests. */
+  readonly multipleModeHeaderValue?: string
+
+  /** Header value used for all-accessible-scope requests. */
+  readonly allModeHeaderValue?: string
+}
+
+/**
+ * Label options for stable query/cache suffixes.
+ */
+export interface PresentationScopeSelectionQuerySuffixOptions {
+  /** Label used for single-scope suffixes. */
+  readonly singleScopeLabel?: string
+
+  /** Label used for multi-scope suffixes. */
+  readonly multipleScopesLabel?: string
+}
+
+/**
+ * Mutable request-scope store used by host HTTP clients.
+ */
+export interface PresentationScopeRequestStore {
+  /** Stores the current request-scope selection. */
+  readonly setSelection: (selection: PresentationScopeRequestSelection) => void
+
+  /** Reads the current normalized request-scope selection. */
+  readonly getSelection: () => PresentationScopeRequestSelection
+
+  /** Returns request headers for the current selection. */
+  readonly getHeaders: () => Readonly<Record<string, string>> | undefined
+
+  /** Returns a stable query/cache suffix for a selection. */
+  readonly formatQuerySuffix: (selection: PresentationScopeRequestSelection) => string
+
+  /** Returns a normalized copy of a selection. */
+  readonly normalizeSelection: (selection: PresentationScopeRequestSelection) => PresentationScopeRequestSelection
+}
+
+/**
+ * Creates a host request-scope store that can project selected scopes into headers.
+ */
+export function createPresentationScopeRequestStore({
+  headerOptions,
+  querySuffixOptions,
+}: {
+  readonly headerOptions: PresentationScopeRequestHeaderOptions
+  readonly querySuffixOptions?: PresentationScopeSelectionQuerySuffixOptions
+}): PresentationScopeRequestStore {
+  let currentSelection: PresentationScopeRequestSelection = { mode: 'default' }
+
+  return {
+    setSelection(selection) {
+      currentSelection = normalizePresentationScopeRequestSelection(selection)
+    },
+    getSelection() {
+      return currentSelection
+    },
+    getHeaders() {
+      return createPresentationScopeRequestHeaders(currentSelection, headerOptions)
+    },
+    formatQuerySuffix(selection) {
+      return formatPresentationScopeSelectionQuerySuffix(selection, querySuffixOptions)
+    },
+    normalizeSelection: normalizePresentationScopeRequestSelection,
+  }
+}
+
+/**
+ * Returns a normalized copy of a request-scope selection.
+ */
+export function normalizePresentationScopeRequestSelection(
+  selection: PresentationScopeRequestSelection,
+): PresentationScopeRequestSelection {
+  switch (selection.mode) {
+    case 'single':
+      return {
+        mode: 'single',
+        scopeId: normalizeScopeId(selection.scopeId),
+      }
+    case 'multiple':
+      return {
+        mode: 'multiple',
+        scopeIds: normalizeScopeIds(selection.scopeIds),
+      }
+    case 'all':
+    case 'default':
+      return selection
+  }
+}
+
+/**
+ * Returns request headers for a selection.
+ */
+export function createPresentationScopeRequestHeaders(
+  selection: PresentationScopeRequestSelection,
+  options: PresentationScopeRequestHeaderOptions,
+): Readonly<Record<string, string>> | undefined {
+  const normalized = normalizePresentationScopeRequestSelection(selection)
+  switch (normalized.mode) {
+    case 'single':
+      return normalized.scopeId
+        ? { [options.singleScopeHeaderName]: normalized.scopeId }
+        : undefined
+    case 'multiple':
+      return normalized.scopeIds.length > 0
+        ? {
+            [options.multipleScopesHeaderName]: normalized.scopeIds.join(','),
+            [options.scopeModeHeaderName]: options.multipleModeHeaderValue ?? 'multiple',
+          }
+        : undefined
+    case 'all':
+      return { [options.scopeModeHeaderName]: options.allModeHeaderValue ?? 'all' }
+    case 'default':
+      return undefined
+  }
+}
+
+/**
+ * Returns a stable query/cache suffix for a selection.
+ */
+export function formatPresentationScopeSelectionQuerySuffix(
+  selection: PresentationScopeRequestSelection,
+  options: PresentationScopeSelectionQuerySuffixOptions = {},
+) {
+  const singleScopeLabel = options.singleScopeLabel ?? 'scope'
+  const multipleScopesLabel = options.multipleScopesLabel ?? 'scopes'
+  const normalized = normalizePresentationScopeRequestSelection(selection)
+  switch (normalized.mode) {
+    case 'single':
+      return `${singleScopeLabel}:${normalized.scopeId ?? 'default'}`
+    case 'multiple':
+      return `${multipleScopesLabel}:${normalized.scopeIds.join(',') || 'none'}`
+    case 'all':
+      return `${multipleScopesLabel}:all`
+    case 'default':
+      return `${singleScopeLabel}:default`
+  }
+}
+
+/**
+ * Returns normalized unique scope ids in stable order.
+ */
+export function normalizeScopeIds(scopeIds: readonly string[]) {
+  return Array.from(
+    new Set(
+      scopeIds
+        .map(normalizeScopeId)
+        .filter((scopeId): scopeId is string => scopeId !== null),
+    ),
+  ).sort((left, right) => left.localeCompare(right))
+}
+
+function normalizeScopeId(scopeId: string | null | undefined) {
+  const trimmed = scopeId?.trim()
+  return trimmed && trimmed.length > 0 ? trimmed : null
+}