@api-client/ui 0.5.58 → 0.6.1

package/src/modeling/lib/formula_parser.ts

@@ -0,0 +1,187 @@
+import { Validator, Jexl, type ValidationResult, ValidationSeverity, type FunctionFunction } from '@pawel-up/jexl'
+import * as stringFunctions from '@pawel-up/jexl/string.js'
+import * as mathFunctions from '@pawel-up/jexl/math.js'
+import * as dateFunctions from '@pawel-up/jexl/date.js'
+import * as arrayFunctions from '@pawel-up/jexl/array.js'
+import * as operatorFunctions from '@pawel-up/jexl/operators.js'
+import type { DomainProperty } from '@api-client/core/modeling/DomainProperty.js'
+
+function addModule(jexl: Jexl, module: Record<string, FunctionFunction>, prefix = '') {
+  Object.keys(module).forEach((key) => {
+    const functionName = prefix ? `${prefix}.${key}` : key
+    jexl.addFunction(functionName, module[key])
+  })
+}
+
+export interface FormulaTestRunResult {
+  /**
+   * Indicates if the formula evaluation was successful.
+   * If false, the `message` property will contain the error message.
+   */
+  error: boolean
+  /**
+   * An error message if the evaluation failed.
+   */
+  message?: string
+  /**
+   * The result of the formula evaluation.
+   * This can be a string, number, boolean, Date, or null.
+   */
+  value: string | number | boolean | Date | null | undefined
+}
+
+/**
+ * A class to parse and validate formulas from the calculated fields.
+ */
+export class FormulaParser {
+  /**
+   * A map of properties available in the entity.
+   * The keys are property keys, and the values are DomainProperty objects.
+   * This allows for quick lookup of properties by their keys.
+   */
+  protected properties: Map<string, DomainProperty>
+
+  constructor(
+    public formula: string,
+    public property: DomainProperty,
+    properties: DomainProperty[] = []
+  ) {
+    this.properties = new Map(properties.map((p) => [p.key, p]))
+  }
+
+  /**
+   * Parses the formula and returns the validation result.
+   */
+  public validate(): ValidationResult {
+    const defaultValue: ValidationResult = { valid: true, errors: [], info: [], issues: [], warnings: [] }
+    if (!this.formula.trim()) {
+      return defaultValue
+    }
+    const expression = this.getJexlExpression()
+    const jexl = new Jexl()
+
+    // Register appropriate functions for the data type
+    this.registerFunctions(jexl)
+
+    const validator = new Validator(jexl.grammar)
+    try {
+      // TODO: we need to extract variables from the text field and (possibly) add a context.
+      return validator.validate(expression, undefined, { allowUndefinedContext: true })
+    } catch (e) {
+      defaultValue.valid = false
+      defaultValue.errors.push({
+        message: (e as Error).message,
+        severity: ValidationSeverity.ERROR,
+      })
+      return defaultValue
+    }
+  }
+
+  public async test(dependencies?: string[]): Promise<FormulaTestRunResult | null> {
+    if (!this.formula.trim()) {
+      return {
+        error: true,
+        value: undefined,
+        message: 'Formula is empty.',
+      }
+    }
+    const expression = this.getJexlExpression()
+    const context = this.buildTestContext(dependencies)
+    const jexl = new Jexl()
+
+    // Register appropriate functions for the data type
+    this.registerFunctions(jexl)
+
+    const result: FormulaTestRunResult = { error: false, value: undefined }
+    // TODO: evaluate array and enum values.
+    // For arrays, we return the results as it would be evaluated normally,
+    // but we ensure the result is an array.
+    // For enums, we render value if the resulting value is one of the defined values,
+    // or otherwise we render error.
+    const dataType = this.property.type
+    try {
+      if (dataType === 'string') {
+        result.value = await jexl.evalAsString(expression, context)
+      } else if (dataType === 'number') {
+        result.value = await jexl.evalAsNumber(expression, context)
+      } else if (dataType === 'boolean') {
+        result.value = await jexl.evalAsBoolean(expression, context)
+      } else {
+        result.value = await jexl.eval(expression, context)
+      }
+    } catch (e) {
+      result.error = true
+      result.message = (e as Error).message
+    }
+    return result
+  }
+
+  private getJexlExpression(): string {
+    // For all types, we treat the input as a direct Jexl expression.
+    // The user is responsible for providing a valid Jexl expression, including quoting string literals.
+    // We just need to replace the mention syntax `{{field_name}}` with the Jexl identifier `property_key`.
+    return this.formula.replace(/\{\{([^}]+)\}\}/g, (match, id) => {
+      const prop = this.properties.get(id)
+      if (prop) {
+        // we use column names as identifiers in Jexl expressions
+        // the key is for fallback if the name is not set
+        return prop.info.name || prop.key
+      }
+      return match
+    })
+  }
+
+  /**
+   * Builds a test context for evaluating the formula.
+   * This context includes the values of the properties that are dependencies of the formula.
+   * @param dependencies The list of property keys that are dependencies in the formula.
+   * @returns An object containing the property values for testing.
+   */
+  buildTestContext(dependencies: string[] | undefined): Record<string, unknown> {
+    const context: Record<string, unknown> = {}
+    if (!dependencies || !dependencies.length) {
+      return context
+    }
+    for (const dep of dependencies || []) {
+      const prop = this.properties.get(dep)
+      if (prop) {
+        context[prop.info.name || prop.key] = prop.toExample('application/json', {
+          renderExamples: true,
+          renderOptional: true,
+          renderMocked: true,
+        })
+      }
+    }
+    return context
+  }
+
+  /**
+   * Registers appropriate Jexl functions based on the data type.
+   * @param jexl The Jexl instance to register functions on.
+   */
+  private registerFunctions(jexl: Jexl): void {
+    addModule(jexl, stringFunctions)
+    addModule(jexl, mathFunctions)
+    addModule(jexl, dateFunctions)
+    addModule(jexl, arrayFunctions)
+    addModule(jexl, operatorFunctions)
+  }
+
+  /**
+   * Extracts property dependencies from the formula.
+   * This method looks for {{field_name}} patterns in the original formula string.
+   * @returns The list of unique dependency keys.
+   */
+  public extractDependencies(): string[] {
+    const dependencies = new Set<string>()
+    const mentionPattern = /\{\{([^}]+)\}\}/g
+    let match
+    while ((match = mentionPattern.exec(this.formula)) !== null) {
+      const fieldKey = match[1]
+      if (this.properties.has(fieldKey)) {
+        dependencies.add(fieldKey)
+      }
+    }
+    return Array.from(dependencies)
+  }
+}

package/src/modeling/lib/ui_mapping.ts

@@ -0,0 +1,258 @@
+import type { DomainAssociation } from '@api-client/core/modeling/DomainAssociation.js'
+import type { DomainPropertyInputConfig } from '../types.js'
+import type { IconType } from '../../md/icons/Icons.js'
+import type { DomainProperty } from '@api-client/core/modeling/DomainProperty.js'
+import {
+  DomainAssociationKind,
+  DomainEntityKind,
+  DomainModelKind,
+  DomainNamespaceKind,
+  DomainPropertyKind,
+} from '@api-client/core/models/kinds.js'
+import type { DomainPropertyFormat } from '@api-client/core/modeling/DataFormat.js'
+
+/**
+ * Returns the icon to use for the given field (DomainProperty or DomainAssociation).
+ * This is used to render the icon in the UI.
+ *
+ * @param p The field to get the icon for.
+ * @returns The icon to use.
+ */
+export function getFieldIcon(p: DomainAssociation | DomainProperty): IconType {
+  if (p.kind === DomainAssociationKind) {
+    return 'link'
+  }
+  return getPropertyIcon(p as DomainProperty)
+}
+
+/**
+ * Returns the label to use for the given field (DomainProperty or DomainAssociation).
+ * @param p The field to get the label for.
+ * @returns The label to use in the data type label.
+ */
+export function getFieldDataTypeLabel(p: DomainAssociation | DomainProperty): string {
+  if (p.kind === DomainAssociationKind) {
+    return 'Reference'
+  }
+  return getPropertyTypeLabel(p as DomainProperty)
+}
+
+/**
+ * Generates an icon name for the DomainProperty that illustrate its primary purpose.
+ */
+export function getPropertyIcon(p: DomainProperty): IconType {
+  if (p.primary) {
+    return 'key'
+  }
+  switch (p.type) {
+    // case 'integer':
+    case 'number':
+      return 'number'
+    case 'date':
+      return 'calendarToday'
+    case 'time':
+      return 'schedule'
+    case 'datetime':
+      return 'event'
+    case 'boolean':
+      return 'checkCircle'
+    case 'binary':
+      return 'draft'
+    default:
+      return 'textFields'
+  }
+}
+
+/**
+ * @returns The type label to use when rendering the DomainProperty in the UI
+ */
+export function getPropertyTypeLabel(p: DomainProperty): string {
+  switch (p.type) {
+    case 'string':
+      return 'String'
+    case 'number':
+      return 'Number'
+    // case 'integer':
+    //   return 'Integer'
+    // case 'nil':
+    //   return 'Nil'
+    case 'boolean':
+      return 'Boolean'
+    case 'date':
+      return 'Date'
+    case 'datetime':
+      return 'Date and time'
+    case 'time':
+      return 'Time'
+    // case 'any':
+    //   return 'Any'
+    case 'binary':
+      return 'Binary'
+    default:
+      return 'Unknown'
+  }
+}
+
+/**
+ * Gathers information about the HTML input's requirements for the given DomainProperty.
+ *
+ * @param model The data property model to gather HTML input's configuration for.
+ * @returns Input attributes to set.
+ */
+export function getPropertyInputOptions(model: DomainProperty): DomainPropertyInputConfig {
+  const result: DomainPropertyInputConfig = { type: 'text' }
+  if (model.type === 'date') {
+    result.type = 'date'
+    result.help = 'Date in YYYY-MM-DD format'
+    return result
+  }
+  if (model.type === 'datetime') {
+    result.type = 'datetime-local'
+    result.help = 'Date and time in YYYY-MM-DDTHH:mm format'
+    return result
+  }
+  if (model.type === 'time') {
+    result.type = 'time'
+    result.help = 'Time in HH:mm format'
+    return result
+  }
+  if (model.type !== 'number') {
+    return result
+  }
+  const schema = model.schema || {}
+  const wb = model.getWebBinding()
+  if (!wb) {
+    return result
+  }
+  const format = wb.format
+  if (format === 'float') {
+    result.type = 'number'
+    result.step = schema.multipleOf ?? 0.000001
+    result.help = '32-bit number with decimals'
+    return result
+  }
+  if (format === 'double') {
+    result.type = 'number'
+    result.step = schema.multipleOf ?? 0.000001
+    result.help = '64-bit number with decimals'
+    return result
+  } else if (format === 'int32') {
+    result.type = 'number'
+    result.step = schema.multipleOf ?? 1
+    result.help = '-2,147,483,648…+2,147,483,647 (32 bit)'
+    result.min = -2147483648
+    result.max = 2147483647
+    return result
+  } else if (format === 'int64') {
+    result.type = 'number'
+    result.step = schema.multipleOf ?? 1
+    result.help = 'Negative or positive 64-bit integer'
+    return result
+  }
+  return result
+}
+
+export function getFormatInfo(format: DomainPropertyFormat): { label: string; help: string } {
+  if (format === 'float') {
+    return { label: 'Float', help: '32-bit number with decimals' }
+  }
+  if (format === 'double') {
+    return { label: 'Double', help: '64-bit number with decimals' }
+  }
+  if (format === 'int32') {
+    return { label: 'Integer (32-bit)', help: '-2,147,483,648…+2,147,483,647' }
+  }
+  if (format === 'int64') {
+    return { label: 'Integer (64-bit)', help: 'Negative or positive 64-bit integer' }
+  }
+  if (format === 'hex') {
+    return { label: 'Hex', help: 'Hex-encoded binary data' }
+  }
+  if (format === 'base64') {
+    return { label: 'Base64', help: 'Base64-encoded binary data' }
+  }
+  return { label: 'Unknown', help: 'An error occurred...' }
+}
+
+export function getDomainLabel(kind: string, options: { capitalize?: boolean } = {}): string {
+  const { capitalize = false } = options
+  let result = kind
+  if (result === DomainNamespaceKind) {
+    result = 'namespace'
+  } else if (result === DomainModelKind) {
+    result = 'model'
+  } else if (result === DomainEntityKind) {
+    result = 'entity'
+  } else if (result === DomainPropertyKind) {
+    result = 'property'
+  } else if (result === DomainAssociationKind) {
+    result = 'association'
+  }
+  if (!result) {
+    return result
+  }
+  return capitalize ? result.charAt(0).toUpperCase() + result.slice(1) : result
+}
+
+/**
+ * Gets the icon type for a given item kind.
+ * @param kind - The kind of the item.
+ * @returns The icon type.
+ */
+export function getDomainIconType(kind: string): IconType {
+  if (kind === DomainModelKind) {
+    return 'schemaModel'
+  }
+  if (kind === DomainNamespaceKind) {
+    return 'schemaNamespace'
+  }
+  return 'schemaEntity'
+}
+
+/**
+ * Maps an API Action kind to a user-friendly label.
+ * @param kind The API Action kind.
+ * @returns The label to render with the UI that correspond to the action.
+ */
+export function apiActionKindToLabel(kind: string): string {
+  switch (kind) {
+    case 'list':
+      return 'List'
+    case 'create':
+      return 'Create'
+    case 'read':
+      return 'Read'
+    case 'update':
+      return 'Update'
+    case 'delete':
+      return 'Delete'
+    case 'search':
+      return 'Search'
+    default:
+      return 'Unknown'
+  }
+}
+
+/**
+ * Maps an API Action kind to an icon name.
+ * @param kind The API Action kind.
+ * @returns The icon name to use for the action kind.
+ */
+export function apiActionKindToIcon(kind: string): string {
+  switch (kind) {
+    case 'list':
+      return 'list'
+    case 'create':
+      return 'add_box'
+    case 'read':
+      return 'get_app'
+    case 'update':
+      return 'edit'
+    case 'delete':
+      return 'delete'
+    case 'search':
+      return 'search'
+    default:
+      return 'help_circle'
+  }
+}

package/src/modeling/lib/validators.ts

@@ -0,0 +1,30 @@
+import type { AccessRule } from '@api-client/core/modeling/types.js'
+import type { ApiModelAccessTarget, ApiModelOperationName } from '../types.js'
+
+/**
+ * Check if the given value is a valid operation name.
+ */
+export function isValidOperationName(value = ''): value is ApiModelOperationName {
+  return ['list', 'read', 'create', 'update', 'delete', 'search'].includes(value)
+}
+
+/**
+ * Check if the given value is a valid access target.
+ */
+export function isValidAccessTarget(value = ''): value is ApiModelAccessTarget {
+  return ['api', 'action', 'endpoint'].includes(value)
+}
+
+/**
+ * Check if the given value is a valid access rule type.
+ */
+export function isValidAccessRuleType(value = ''): value is AccessRule['type'] {
+  return [
+    'public',
+    'authenticated',
+    'resourceOwner',
+    'matchUserRole',
+    'matchUserProperty',
+    'matchEmailDomain',
+  ].includes(value)
+}