KArtSell.Aegis/docs/Design/kbx-foundation-v52-fe-operational-navigation-screen-anatomy/packages/kbx-contracts/src/screen.ts

import type { KbxCommandDefinition } from './command'

export type KbxScreenType =
  | 'list'
  | 'master'
  | 'transaction'
  | 'fast-entry'
  | 'master-detail'
  | 'queue'
  | 'reconcile'
  | 'import'
  | 'wms-mobile'

export type KbxTemplateMetricTone = 'default' | 'info' | 'success' | 'warning' | 'danger'

export type KbxTemplateStateCapability =
  | 'idle'
  | 'loading'
  | 'refreshing'
  | 'empty'
  | 'error'
  | 'permission'
  | 'dirty'
  | 'conflict'
  | 'validation'
  | 'job'
  | 'network'

export interface KbxTemplateMetric {
  key: string
  label: string
  value: string | number
  tone?: KbxTemplateMetricTone
  emphasis?: boolean
}

export interface KbxTemplateContext {
  label?: string
  hint?: string
  updatedAt?: string
  metrics?: KbxTemplateMetric[]
}


export interface KbxTemplateManifestEntry {
  code: 'T01'|'T02'|'T03'|'T04'|'T05'|'T06'|'T07'|'T08'|'T09'
  type: KbxScreenType
  component: string
  purpose: string
  requiredSurfaces: string[]
  optionalSurfaces: string[]
  keyboard: string[]
  referenceScreens: string[]
  defaultDensity: 'compact' | 'comfortable' | 'touch'
  runtimeStates: ('idle'|'loading'|'empty'|'error'|'ready')[]
  /** State concerns the template must expose or deliberately delegate to a shared KBX component. */
  stateCapabilities: KbxTemplateStateCapability[]
  utilitySurfaces: ('help'|'ai'|'suggestion'|'audit')[]
  accessibility: string[]
  /** Canonical KBX components expected for a production-grade implementation of this template. */
  coreComponents: string[]
  /** Review items that must be resolved before a screen of this type is considered complete. */
  completionChecks: string[]
}

export type KbxScreenTemplateCode = 'T01'|'T02'|'T03'|'T04'|'T05'|'T06'|'T07'|'T08'|'T09'

export type KbxRecipePermissionKind = 'none'|'write'|'execute'

export interface KbxScreenRecipeCommand {
  id: string
  label: string
  group: 'query'|'edit'|'workflow'|'output'|'more'
  shortcut?: string
  variant?: 'primary'|'secondary'|'danger'|'ghost'
  permissionKind: KbxRecipePermissionKind
}

export interface KbxScreenRecipeTestProfile {
  /** Scenario kinds that must exist in the canonical recipe coverage. */
  requiredScenarioKinds: ('e2e'|'integration'|'contract')[]
  /** Behavioral tags that must be covered by the recipe's canonical scenarios. */
  requiredTags: string[]
  /** Evidence classes that must be emitted by at least one canonical scenario. */
  requiredEvidence: string[]
  /** Stable review/test intents generated for every screen using the recipe. */
  requiredChecks: string[]
}

export interface KbxScreenRecipeDefinition {
  code: KbxScreenTemplateCode
  type: KbxScreenType
  templateComponent: string
  defaultCommands: KbxScreenRecipeCommand[]
  requiredPolicies: string[]
  recoveryPolicies: string[]
  securityPolicies: string[]
  canonicalScenarioIds: string[]
  scaffoldSurfaces: string[]
  testProfile: KbxScreenRecipeTestProfile
}

export interface KbxScreenDefinition {
  id: string
  version: string
  module: 'OMS' | 'ERP' | 'WMS' | 'COMMON'
  type: KbxScreenType
  /** Explicit template/recipe identity. Type and templateCode must agree. */
  templateCode: KbxScreenTemplateCode
  title: string
  description?: string
  permissions?: string[]
  commands?: KbxCommandDefinition[]
  helpKey?: string
  telemetry?: { enabled: boolean }
}

export function defineKbxScreen<T extends KbxScreenDefinition>(definition: T): T {
  return definition
}