@cybertale/resolver 0.1.0

package/.idea/cybertale-resolver.iml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="WEB_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$" />
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

package/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/cybertale-resolver.iml" filepath="$PROJECT_DIR$/.idea/cybertale-resolver.iml" />
+    </modules>
+  </component>
+</project>

package/.idea/php.xml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="MessDetectorOptionsConfiguration">
+    <option name="transferred" value="true" />
+  </component>
+  <component name="PHPCSFixerOptionsConfiguration">
+    <option name="transferred" value="true" />
+  </component>
+  <component name="PHPCodeSnifferOptionsConfiguration">
+    <option name="highlightLevel" value="WARNING" />
+    <option name="transferred" value="true" />
+  </component>
+  <component name="PhpStanOptionsConfiguration">
+    <option name="transferred" value="true" />
+  </component>
+  <component name="PsalmOptionsConfiguration">
+    <option name="transferred" value="true" />
+  </component>
+</project>

package/README.md

@@ -0,0 +1,92 @@
+# 📦 `@cybertale/resolver`
+
+**A lightweight, framework-agnostic resolver engine** used to transform, compute, update, and manage `ObjectTemplate` structures from `@cybertale/interface`.
+
+This package extracts core logic from UI components (Vue/React) into a clean, reusable, testable library.
+
+---
+
+<p align="center">
+  <img src="https://img.shields.io/npm/v/%40cybertale%2Fresolver.svg?style=for-the-badge" />
+  <img src="https://img.shields.io/npm/dm/%40cybertale%2Fresolver.svg?style=for-the-badge" />
+  <img src="https://img.shields.io/bundlephobia/minzip/%40cybertale%2Fresolver?style=for-the-badge" />
+  <img src="https://img.shields.io/github/license/cybertale/resolver?style=for-the-badge" />
+</p>
+
+## 🚀 Why this exists
+Modern UI frameworks shouldn't contain domain logic.
+
+Before this package:
+- Buttons processed JSON in the component  
+- Fields decided validation class  
+- SelectList parsed arrays  
+- Many duplicated helpers across components  
+
+Now all that logic is extracted into:
+```
+@cybertale/resolver
+```
+
+Your UI becomes dumb — your resolver becomes smart.
+
+---
+
+# 🧩 Features
+
+### ✔ JSON parsing & normalization  
+### ✔ Template stat utilities  
+### ✔ Template actions  
+### ✔ Computed helpers  
+### ✔ Finalization helpers
+
+---
+
+# 📥 Installation
+
+```bash
+npm install @cybertale/resolver
+```
+
+---
+
+# 🧱 Architecture Overview
+
+```
+resolver/
+├── transform/
+├── form/
+├── compute/
+├── finalize/
+└── handlers/
+```
+
+---
+
+# 📚 Usage Examples
+
+## Extracted Field Logic (Vue)
+
+```ts
+import { getValueFromTemplate } from '@cybertale/resolver/form/value'
+```
+
+## Updating Template Data
+
+```ts
+import { updateValueForTemplate } from '@cybertale/resolver/handlers/update'
+```
+
+---
+
+# 🤝 Contributing
+
+1. Clone repo  
+2. Install deps  
+3. Run tests  
+4. Submit PR
+
+---
+
+# 📜 License
+
+MIT © Cybertale

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@cybertale/resolver",
+  "version": "0.1.0",
+  "type": "module",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "peerDependencies": {
+    "@cybertale/interface": "*"
+  }
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+
+// Barrel exports for @cybertale/template
+
+// transform
+export * as JsonTransform from './resolver/transform/json'
+export * as StatTransform from './resolver/transform/stat'
+
+// form
+export * as FormValue from './resolver/form/value'
+export * as FormInput from './resolver/form/input'
+export * as FormSelect from './resolver/form/select'
+
+// compute
+export * as ComputeLabel from './resolver/compute/label'
+export * as ComputeTooltip from './resolver/compute/tooltip'
+export * as ComputeValidation from './resolver/compute/validation'
+
+// finalize
+export * as FinalizeTemplate from './resolver/finalize/template'
+export * as FinalizeDefaults from './resolver/finalize/defaults'
+
+// handlers
+export * as HandlersRemove from './resolver/handlers/remove'
+export * as HandlersInsert from './resolver/handlers/insert'
+export * as HandlersUpdate from './resolver/handlers/update'

package/src/resolver/compute/label.ts

@@ -0,0 +1,42 @@
+
+import type { ObjectTemplate, StatTypeEnum } from '@cybertale/interface'
+import { getStringStat } from '../transform/stat'
+import { isJSONObject, parseJSON } from '../transform/json'
+
+export interface LabelData {
+  iconClass?: string
+  title?: string
+  styleData?: string
+  contentValue?: string
+  contentClass?: string
+  translate?: string
+}
+
+/**
+ * Attempts to parse Stat.Label as a LabelData object; if it is a plain string,
+ * it is returned as `title` for convenience.
+ */
+export function getLabelData(
+  object: ObjectTemplate,
+  labelStat: StatTypeEnum,
+): LabelData {
+  const raw = getStringStat(object, labelStat)
+  if (!raw) return { title: '' }
+
+  if (isJSONObject(raw)) {
+    const parsed = parseJSON<LabelData>(raw)
+    if (parsed) return parsed
+  }
+
+  return { title: raw }
+}
+
+/**
+ * Returns the plain label text (usually LabelData.title or raw string).
+ */
+export function getLabelText(
+  object: ObjectTemplate,
+  labelStat: StatTypeEnum,
+): string {
+  return getLabelData(object, labelStat).title ?? ''
+}

package/src/resolver/compute/tooltip.ts

@@ -0,0 +1,47 @@
+
+import type { ObjectTemplate, StatTypeEnum } from '@cybertale/interface'
+import { getStringStat } from '../transform/stat'
+import { isJSONObject, parseJSON } from '../transform/json'
+
+export interface TooltipData {
+  toggleBy: string
+  value: string
+  translate?: string
+}
+
+/**
+ * Tooltip is stored either as a simple string or as a JSON-encoded TooltipData.
+ */
+export function getTooltip(
+  object: ObjectTemplate,
+  tooltipStat: StatTypeEnum,
+): TooltipData | string | null {
+  const raw = getStringStat(object, tooltipStat)
+  if (!raw) return null
+
+  if (isJSONObject(raw)) {
+    return parseJSON<TooltipData>(raw)
+  }
+
+  return raw
+}
+
+export function getTooltipToggleBy(
+  object: ObjectTemplate,
+  tooltipStat: StatTypeEnum,
+): string {
+  const tooltip = getTooltip(object, tooltipStat)
+  if (!tooltip) return 'tooltip'
+  if (typeof tooltip === 'string') return 'tooltip'
+  return tooltip.toggleBy || 'tooltip'
+}
+
+export function getTooltipText(
+  object: ObjectTemplate,
+  tooltipStat: StatTypeEnum,
+): string {
+  const tooltip = getTooltip(object, tooltipStat)
+  if (!tooltip) return ''
+  if (typeof tooltip === 'string') return tooltip
+  return tooltip.value
+}

package/src/resolver/compute/validation.ts

@@ -0,0 +1,21 @@
+
+import type { ObjectTemplate, StatTypeEnum } from '@cybertale/interface'
+import { getRawStat, getStringStat } from '../transform/stat'
+
+/**
+ * Computes a Bootstrap-esque validation class ('is-valid' | 'is-invalid' | '').
+ * This mirrors the repeated logic you had in several components.
+ */
+export function computeValidationClass(
+  object: ObjectTemplate,
+  isValidStat: StatTypeEnum,
+  errorMessageStat: StatTypeEnum,
+): string {
+  const isValidRaw = getRawStat(object, isValidStat)
+  const errorMessage = getStringStat(object, errorMessageStat)
+
+  if (isValidRaw === undefined || isValidRaw === '') return ''
+  if (isValidRaw) return 'is-valid'
+  if (errorMessage) return 'is-invalid'
+  return ''
+}

package/src/resolver/finalize/defaults.ts

@@ -0,0 +1,30 @@
+import type { ObjectTemplate, StatTypeEnum } from '@cybertale/interface'
+import { getRawStat } from '../transform/stat'
+
+/**
+ * Applies default values to stats that are currently empty / undefined.
+ * `defaults` is a map of StatTypeEnum -> default Data value.
+ */
+export function applyDefaults(
+    template: ObjectTemplate,
+    defaults: Partial<Record<StatTypeEnum, unknown>>,
+): ObjectTemplate {
+  for (const [key, value] of Object.entries(defaults)) {
+    const statKey = Number(key) as StatTypeEnum
+
+    // Only apply if undefined or empty
+    if (getRawStat(template, statKey) == null && template.Stats) {
+      const stringValue = value !== undefined && value !== null
+          ? String(value)            // <—— FIX HERE
+          : ''
+
+      if (!template.Stats[statKey]) {
+        // Create new stat entry
+        template.Stats[statKey] = { Data: stringValue } as any
+      } else {
+        template.Stats[statKey].Data = stringValue
+      }
+    }
+  }
+  return template
+}

package/src/resolver/finalize/template.ts

@@ -0,0 +1,25 @@
+
+import type { ObjectTemplate } from '@cybertale/interface'
+
+/**
+ * Finalization hook for a single ObjectTemplate before it is sent to the backend
+ * or stored. For now this is a light pass-through, but centralizing this
+ * allows you to add future cleanup in one place (e.g. stripping transient stats).
+ */
+export function finalizeTemplate(template: ObjectTemplate): ObjectTemplate {
+  // Shallow clone to avoid accidental external mutation
+  return new (template.constructor as typeof ObjectTemplate)(
+    template.Region,
+    template.ObjectEnum,
+    template.SubObjectEnum,
+    template.ActionEnum,
+    template.Stats,
+  )
+}
+
+/**
+ * Convenience function for finalizing an array of templates.
+ */
+export function finalizeTemplates(templates: ObjectTemplate[]): ObjectTemplate[] {
+  return templates.map(finalizeTemplate)
+}

package/src/resolver/form/input.ts

@@ -0,0 +1,14 @@
+
+import type { ObjectTemplate, StatTypeEnum } from '@cybertale/interface'
+import { getStringStat } from '../transform/stat'
+
+/**
+ * Returns the input type for a given template.
+ * In your current code this is usually driven by StatTypeEnum.ElementType.
+ */
+export function getInputTypeFromTemplate(
+  object: ObjectTemplate,
+  elementTypeStat: StatTypeEnum,
+): string {
+  return getStringStat(object, elementTypeStat)
+}

package/src/resolver/form/select.ts

@@ -0,0 +1,49 @@
+
+import type { ObjectTemplate, StatTypeEnum } from '@cybertale/interface'
+import { getStringStat } from '../transform/stat'
+import { parseJSON, isJSONArray } from '../transform/json'
+
+export interface SelectItem {
+  id: string | number
+  name?: string
+  [key: string]: unknown
+}
+
+/**
+ * Parses the ItemList stat (usually JSON) into a typed array.
+ */
+export function getSelectItems(
+  object: ObjectTemplate,
+  itemListStat: StatTypeEnum,
+): SelectItem[] {
+  const raw = getStringStat(object, itemListStat)
+  if (!raw || !isJSONArray(raw)) return []
+  const parsed = parseJSON<unknown[]>(raw) ?? []
+  return parsed.filter((item): item is SelectItem => {
+    return !!item && typeof (item as any).id !== 'undefined'
+  })
+}
+
+/**
+ * Gets the currently selected item id from the template.
+ * This simply returns Stat.Value (or similar), but extracted in one place.
+ */
+export function getSelectedId(
+  object: ObjectTemplate,
+  valueStat: StatTypeEnum,
+): string {
+  return getStringStat(object, valueStat)
+}
+
+/**
+ * Returns the selected SelectItem, if found.
+ */
+export function getSelectedItem(
+  object: ObjectTemplate,
+  itemListStat: StatTypeEnum,
+  valueStat: StatTypeEnum,
+): SelectItem | null {
+  const items = getSelectItems(object, itemListStat)
+  const selectedId = getSelectedId(object, valueStat)
+  return items.find(item => String(item.id) === selectedId) ?? null
+}

package/src/resolver/form/value.ts

@@ -0,0 +1,54 @@
+import type { ObjectTemplate } from '@cybertale/interface'
+import { StatTypeEnum } from '@cybertale/interface'
+import { getStringStat, hasStat } from '../transform/stat'
+import { isJSONArray, parseJSON } from '../transform/json'
+
+/**
+ * Generic value resolution from ObjectTemplate stats.
+ *
+ * This encapsulates the common pattern you used in multiple components:
+ * - Stat.Value stores an array (JSON string)
+ * - Stat.Option (or other index stat) selects one element from that array
+ * - OptionIndices may itself be a JSON array of indices
+ */
+export function getValueFromTemplate(
+    object: ObjectTemplate,
+    valueStat: StatTypeEnum,
+    indexStat: StatTypeEnum = (StatTypeEnum as any).Option,
+): unknown {
+  const raw = getStringStat(object, valueStat)
+  if (!raw) return ''
+
+  if (!hasStat(object, indexStat) || !isJSONArray(raw)) {
+    return raw
+  }
+
+  const data = parseJSON<unknown[]>(raw)
+  if (!data) return ''
+
+  const indexRaw = getStringStat(object, indexStat)
+
+  // JSON-array index case
+  if (isJSONArray(indexRaw)) {
+    const optionIndicesStat = (StatTypeEnum as any).OptionIndices as StatTypeEnum
+    const indices = parseJSON<number[]>(indexRaw) ?? []
+
+    const optionIndex = Number(getStringStat(object, optionIndicesStat))
+    const mappedIndex = indices[optionIndex]
+
+    // FIXED: redundant typeof removed, replaced with correct bounds + null check
+    if (mappedIndex != null && mappedIndex in data) {
+      return data[mappedIndex]
+    }
+
+    return ''
+  }
+
+  // Simple numeric index
+  const index = Number(indexRaw)
+  if (Number.isNaN(index) || !(index in data)) {
+    return ''
+  }
+
+  return data[index]
+}

package/src/resolver/handlers/insert.ts

@@ -0,0 +1,33 @@
+
+import type { ObjectTemplate } from '@cybertale/interface'
+
+/**
+ * Inserts a single ObjectTemplate at the given index and returns a new array.
+ */
+export function insertTemplateAt(
+  templates: ObjectTemplate[],
+  index: number,
+  template: ObjectTemplate,
+): ObjectTemplate[] {
+  return [
+    ...templates.slice(0, index),
+    template,
+    ...templates.slice(index),
+  ]
+}
+
+/**
+ * Inserts multiple ObjectTemplates starting at the given index and returns
+ * a new array.
+ */
+export function insertTemplatesAt(
+  templates: ObjectTemplate[],
+  index: number,
+  newTemplates: ObjectTemplate[],
+): ObjectTemplate[] {
+  return [
+    ...templates.slice(0, index),
+    ...newTemplates,
+    ...templates.slice(index),
+  ]
+}

package/src/resolver/handlers/remove.ts

@@ -0,0 +1,52 @@
+
+import type { ObjectTemplate, StatTypeEnum } from '@cybertale/interface'
+import { getStringStat, hasStat } from '../transform/stat'
+
+/**
+ * Finds the index of an ObjectTemplate by a tag-like stat. Supports the
+ * 'tag|something' pattern you use for button payloads.
+ */
+export function findTemplateIndexByStat(
+  templates: ObjectTemplate[],
+  value: string,
+  searchByStat: StatTypeEnum,
+): number {
+  return templates.findIndex(t => {
+    const statValue = getStringStat(t, searchByStat)
+    return statValue === value || statValue === value.split('|')[1]
+  })
+}
+
+/**
+ * Removes the first template whose `searchByStat` matches `value`.
+ * Returns a new array (non-mutating).
+ */
+export function removeByStatValue(
+  templates: ObjectTemplate[],
+  value: string,
+  searchByStat: StatTypeEnum,
+): ObjectTemplate[] {
+  const index = findTemplateIndexByStat(templates, value, searchByStat)
+  if (index === -1) return templates
+  return [
+    ...templates.slice(0, index),
+    ...templates.slice(index + 1),
+  ]
+}
+
+/**
+ * Removes all templates where Stat.DependsOn.Data includes the provided key.
+ * This mirrors your old removeElementFromArray implementation, but returns
+ * a new array instead of mutating in-place.
+ */
+export function removeByDependsOn(
+  templates: ObjectTemplate[],
+  dependsOn: string,
+  dependsOnStat: StatTypeEnum,
+): ObjectTemplate[] {
+  return templates.filter(t => {
+    if (!hasStat(t, dependsOnStat)) return true
+    const dep = getStringStat(t, dependsOnStat)
+    return !dep.includes(dependsOn)
+  })
+}

package/src/resolver/handlers/update.ts

@@ -0,0 +1,55 @@
+
+import type { ObjectTemplate } from '@cybertale/interface'
+import { StatTypeEnum } from '@cybertale/interface'
+import { findTemplateIndexByStat } from './remove'
+import { isJSONArray, parseJSON } from '../transform/json'
+import { getStringStat } from '../transform/stat'
+
+/**
+ * Updates a value-like stat on the template that matches the payload by some key stat.
+ * This mirrors your updateValueData logic, including JSON-array handling.
+ */
+export function updateValueForTemplate(
+  templates: ObjectTemplate[],
+  payload: ObjectTemplate,
+  options?: {
+    valueStat?: StatTypeEnum
+    searchByStat?: StatTypeEnum
+    valueIndicesStat?: StatTypeEnum
+  },
+): ObjectTemplate[] {
+  const valueStat = options?.valueStat ?? (StatTypeEnum as any).Value
+  const searchByStat = options?.searchByStat ?? (StatTypeEnum as any).Tag
+  const valueIndicesStat = options?.valueIndicesStat ?? (StatTypeEnum as any).ValueIndices
+
+  const index = findTemplateIndexByStat(templates, getStringStat(payload, searchByStat), searchByStat)
+  if (index === -1) return templates
+
+  const target = templates[index]
+  const currentRaw = getStringStat(target, valueStat)
+  const payloadValue = getStringStat(payload, options?.valueStat ?? valueStat)
+
+  // If current value is a JSON array, update at ValueIndices
+  if (isJSONArray(currentRaw)) {
+    const arr = parseJSON<unknown[]>(currentRaw) ?? []
+    const indicesRaw = getStringStat(payload, valueIndicesStat)
+    const idx = Number(indicesRaw)
+    if (!Number.isNaN(idx)) {
+      arr[idx] = payloadValue
+    }
+    // Write back as JSON string
+    if (target.Stats) {
+      target.Stats[valueStat].Data = JSON.stringify(arr)
+    }
+  } else {
+    // Simple scalar assignment
+    if (target.Stats) {
+      target.Stats[valueStat].Data = payloadValue
+    }
+  }
+
+  // Return a new array instance to preserve immutability semantics
+  const clone = [...templates]
+  clone[index] = target
+  return clone
+}

package/src/resolver/transform/json.ts

@@ -0,0 +1,23 @@
+
+// JSON-related transformation utilities for ObjectTemplate stats.
+// These are intentionally generic and environment-agnostic so they can be reused
+// both in browser and Node contexts.
+
+export function parseJSON<T = unknown>(value: string | null | undefined): T | null {
+  if (value == null || value === "") return null
+  try {
+    return JSON.parse(value) as T
+  } catch {
+    return null
+  }
+}
+
+export function isJSONArray(value: string | null | undefined): boolean {
+  const parsed = parseJSON(value)
+  return Array.isArray(parsed)
+}
+
+export function isJSONObject(value: string | null | undefined): boolean {
+  const parsed = parseJSON(value)
+  return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+}

package/src/resolver/transform/stat.ts

@@ -0,0 +1,32 @@
+
+import type { ObjectTemplate, StatTypeEnum } from '@cybertale/interface'
+import { parseJSON } from './json'
+
+// Safe stat accessors for ObjectTemplate. These centralize the common
+// patterns used across UI and resolver code.
+
+export function hasStat(object: ObjectTemplate, stat: StatTypeEnum): boolean {
+  return !!object.Stats && object.Stats[stat] !== undefined
+}
+
+export function getRawStat(object: ObjectTemplate, stat: StatTypeEnum): unknown {
+  return object.Stats?.[stat]?.Data
+}
+
+export function getStringStat(object: ObjectTemplate, stat: StatTypeEnum): string {
+  const raw = getRawStat(object, stat)
+  if (raw == null) return ''
+  return String(raw)
+}
+
+export function getBooleanStat(object: ObjectTemplate, stat: StatTypeEnum): boolean {
+  const raw = getRawStat(object, stat)
+  // Treat empty string / null / undefined as false, anything else as true.
+  return !!raw
+}
+
+export function getJSONStat<T = unknown>(object: ObjectTemplate, stat: StatTypeEnum): T | null {
+  const raw = getRawStat(object, stat)
+  if (typeof raw !== 'string') return null
+  return parseJSON<T>(raw)
+}