@nordcraft/core 1.0.0

package/src/formula/formula.ts

@@ -0,0 +1,355 @@
+/* eslint-disable no-console */
+import type { Component, ComponentData } from '../component/component.types'
+import type {
+  CustomFormulaHandler,
+  FormulaHandler,
+  FormulaLookup,
+  Toddle,
+  ToddleMetadata,
+} from '../types'
+import { isDefined, toBoolean } from '../utils/util'
+import { isToddleFormula } from './formulaTypes'
+
+// Define the some objects types as union of ServerSide and ClientSide runtime types as applyFormula is used in both
+declare const document: Document | undefined
+type ShadowRoot = DocumentFragment
+
+export interface PathOperation extends ToddleMetadata {
+  type: 'path'
+  path: string[]
+}
+
+type FunctionArgument = {
+  name?: string
+  isFunction?: boolean
+  formula: Formula
+}
+
+export interface FunctionOperation extends ToddleMetadata {
+  type: 'function'
+  name: string
+  display_name?: string | null
+  package?: string
+  arguments: FunctionArgument[]
+  variableArguments?: boolean
+}
+
+export interface RecordOperation extends ToddleMetadata {
+  type: 'record'
+  entries: FunctionArgument[]
+}
+
+export interface ObjectOperation extends ToddleMetadata {
+  type: 'object'
+  arguments?: FunctionArgument[]
+}
+
+export interface ArrayOperation extends ToddleMetadata {
+  type: 'array'
+  arguments: Array<{ formula: Formula }>
+}
+
+export interface OrOperation extends ToddleMetadata {
+  type: 'or'
+  arguments: Array<{ formula: Formula }>
+}
+
+export interface AndOperation extends ToddleMetadata {
+  type: 'and'
+  arguments: Array<{ formula: Formula }>
+}
+
+export interface ApplyOperation extends ToddleMetadata {
+  type: 'apply'
+  name: string
+  arguments: FunctionArgument[]
+}
+
+export interface ValueOperation extends ToddleMetadata {
+  type: 'value'
+  value: ValueOperationValue
+}
+
+export type ValueOperationValue = string | number | boolean | null | object
+
+export interface SwitchOperation extends ToddleMetadata {
+  type: 'switch'
+  cases: Array<{
+    condition: Formula
+    formula: Formula
+  }>
+  default: Formula
+}
+
+export type Formula =
+  | FunctionOperation
+  | RecordOperation
+  | ObjectOperation
+  | ArrayOperation
+  | PathOperation
+  | SwitchOperation
+  | OrOperation
+  | AndOperation
+  | ValueOperation
+  | ApplyOperation
+
+export type FormulaContext = {
+  component: Component
+  formulaCache?: Record<
+    string,
+    {
+      get: (data: ComponentData) => any
+      set: (data: ComponentData, result: any) => void
+    }
+  >
+  data: ComponentData
+  root?: Document | ShadowRoot | null
+  package: string | undefined
+  toddle: {
+    getFormula: FormulaLookup
+    getCustomFormula: CustomFormulaHandler
+    errors: Error[]
+  }
+  env: ToddleEnv | undefined
+}
+
+export type ToddleServerEnv = {
+  branchName: string
+  // isServer will be true for SSR + proxied requests
+  isServer: true
+  request: {
+    headers: Record<string, string>
+    cookies: Record<string, string>
+    url: string
+  }
+  runtime: never
+  logErrors: boolean
+}
+
+export type ToddleEnv =
+  | ToddleServerEnv
+  | {
+      branchName: string
+      // isServer will be false for client-side
+      isServer: false
+      request: undefined
+      runtime: 'page' | 'custom-element' | 'preview'
+      logErrors: boolean
+    }
+
+export function isFormula(f: any): f is Formula {
+  return f && typeof f === 'object' && typeof f.type === 'string'
+}
+export function isFormulaApplyOperation(
+  formula: Formula,
+): formula is ApplyOperation {
+  return formula.type === 'apply'
+}
+
+export function applyFormula(
+  formula: Formula | string | number | undefined | null | boolean,
+  ctx: FormulaContext,
+): any {
+  if (!isFormula(formula)) {
+    return formula
+  }
+  try {
+    switch (formula.type) {
+      case 'value':
+        return formula.value
+      case 'path': {
+        let input: any = ctx.data
+        for (const key of formula.path) {
+          if (input && typeof input === 'object') {
+            input = input[key]
+          } else {
+            return null
+          }
+        }
+
+        return input
+      }
+      case 'switch': {
+        for (const branch of formula.cases) {
+          if (toBoolean(applyFormula(branch.condition, ctx))) {
+            return applyFormula(branch.formula, ctx)
+          }
+        }
+        return applyFormula(formula.default, ctx)
+      }
+      case 'or': {
+        for (const entry of formula.arguments) {
+          if (toBoolean(applyFormula(entry.formula, ctx))) {
+            return true
+          }
+        }
+        return false
+      }
+      case 'and': {
+        for (const entry of formula.arguments) {
+          if (!toBoolean(applyFormula(entry.formula, ctx))) {
+            return false
+          }
+        }
+        return true
+      }
+      case 'function': {
+        const packageName = formula.package ?? ctx.package
+        const newFunc = (
+          ctx.toddle ??
+          ((globalThis as any).toddle as Toddle<unknown, unknown> | undefined)
+        )?.getCustomFormula(formula.name, packageName)
+        const legacyFunc: FormulaHandler | undefined = (
+          ctx.toddle ?? ((globalThis as any).toddle as Toddle<unknown, unknown>)
+        ).getFormula(formula.name)
+        if (isDefined(newFunc)) {
+          const args = formula.arguments.reduce<Record<string, unknown>>(
+            (args, arg, i) => ({
+              ...args,
+              [arg.name ?? `${i}`]: arg.isFunction
+                ? (Args: any) =>
+                    applyFormula(arg.formula, {
+                      ...ctx,
+                      data: {
+                        ...ctx.data,
+                        Args: ctx.data.Args
+                          ? { ...Args, '@toddle.parent': ctx.data.Args }
+                          : Args,
+                      },
+                    })
+                : applyFormula(arg.formula, ctx),
+            }),
+            {},
+          )
+          try {
+            return isToddleFormula(newFunc)
+              ? applyFormula(newFunc.formula, {
+                  ...ctx,
+                  data: { ...ctx.data, Args: args },
+                })
+              : newFunc.handler(args, {
+                  root: ctx.root ?? document,
+                  env: ctx.env,
+                } as any)
+          } catch (e) {
+            ctx.toddle.errors.push(e as Error)
+            if (ctx.env?.logErrors) {
+              console.error(e)
+            }
+            return null
+          }
+        } else if (typeof legacyFunc === 'function') {
+          const args = (formula.arguments ?? []).map((arg) =>
+            arg.isFunction
+              ? (Args: any) =>
+                  applyFormula(arg.formula, {
+                    ...ctx,
+                    data: {
+                      ...ctx.data,
+                      Args: ctx.data.Args
+                        ? { ...Args, '@toddle.parent': ctx.data.Args }
+                        : Args,
+                    },
+                  })
+              : applyFormula(arg.formula, ctx),
+          )
+          try {
+            return legacyFunc(args, ctx as any)
+          } catch (e) {
+            ctx.toddle.errors.push(e as Error)
+            if (ctx.env?.logErrors) {
+              console.error(e)
+            }
+            return null
+          }
+        }
+        if (ctx.env?.logErrors) {
+          console.error(
+            `Could not find formula ${formula.name} in package ${
+              packageName ?? ''
+            }`,
+            formula,
+          )
+        }
+        return null
+      }
+      case 'object':
+        return Object.fromEntries(
+          formula.arguments?.map((entry) => [
+            entry.name,
+            applyFormula(entry.formula, ctx),
+          ]) ?? [],
+        )
+      case 'record': // object used to be called record, there are still examples in the wild.
+        return Object.fromEntries(
+          formula.entries.map((entry) => [
+            entry.name,
+            applyFormula(entry.formula, ctx),
+          ]),
+        )
+      case 'array':
+        return formula.arguments.map((entry) =>
+          applyFormula(entry.formula, ctx),
+        )
+      case 'apply': {
+        const componentFormula = ctx.component.formulas?.[formula.name]
+        if (!componentFormula) {
+          if (ctx.env?.logErrors) {
+            console.log(
+              'Component does not have a formula with the name ',
+              formula.name,
+            )
+          }
+          return null
+        }
+        const Input = Object.fromEntries(
+          formula.arguments.map((arg) =>
+            arg.isFunction
+              ? [
+                  arg.name,
+                  (Args: any) =>
+                    applyFormula(arg.formula, {
+                      ...ctx,
+                      data: {
+                        ...ctx.data,
+                        Args: ctx.data.Args
+                          ? { ...Args, '@toddle.parent': ctx.data.Args }
+                          : Args,
+                      },
+                    }),
+                ]
+              : [arg.name, applyFormula(arg.formula, ctx)],
+          ),
+        )
+        const data = {
+          ...ctx.data,
+          Args: ctx.data.Args
+            ? { ...Input, '@toddle.parent': ctx.data.Args }
+            : Input,
+        }
+        const cache = ctx.formulaCache?.[formula.name]?.get(data)
+
+        if (cache?.hit) {
+          return cache.data
+        } else {
+          const result = applyFormula(componentFormula.formula, {
+            ...ctx,
+            data,
+          })
+          ctx.formulaCache?.[formula.name]?.set(data, result)
+          return result
+        }
+      }
+
+      default:
+        if (ctx.env?.logErrors) {
+          console.error('Could not recognize formula', formula)
+        }
+    }
+  } catch (e) {
+    if (ctx.env?.logErrors) {
+      console.error(e)
+    }
+    return null
+  }
+}

package/src/formula/formulaTypes.ts

@@ -0,0 +1,45 @@
+import type { Formula } from './formula'
+
+export interface BaseFormula {
+  name: string
+  description?: string
+  arguments: Array<{
+    name: string
+    formula?: Formula | null
+    testValue?: unknown
+  }>
+  // exported indicates that a formula is exported in a package
+  exported?: boolean
+  variableArguments?: boolean | null
+}
+
+export interface ToddleFormula extends BaseFormula {
+  formula: Formula
+}
+
+/**
+ * The Handler generic is a string server side, but a function client side
+ */
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+export interface CodeFormula<Handler = string | Function> extends BaseFormula {
+  version?: 2 | never
+  handler: Handler
+}
+
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+export type PluginFormula<Handler = string | Function> =
+  | ToddleFormula
+  | CodeFormula<Handler>
+
+export const isToddleFormula = <Handler>(
+  formula: PluginFormula<Handler>,
+): formula is ToddleFormula => Object.hasOwn(formula, 'formula')
+
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+export interface GlobalFormulas<Handler = string | Function> {
+  formulas?: Record<string, PluginFormula<Handler>>
+  packages?: Record<
+    string,
+    { formulas?: Record<string, PluginFormula<Handler>> }
+  >
+}

package/src/formula/formulaUtils.ts

@@ -0,0 +1,287 @@
+import type { ActionModel } from '../component/component.types'
+import { isDefined } from '../utils/util'
+import type {
+  Formula,
+  FunctionOperation,
+  PathOperation,
+  ValueOperation,
+} from './formula'
+import { isFormula } from './formula'
+import type { GlobalFormulas } from './formulaTypes'
+import { isToddleFormula } from './formulaTypes'
+
+export const valueFormula = (
+  value: string | number | boolean | null | object,
+): ValueOperation => ({
+  type: 'value',
+  value,
+})
+
+export const pathFormula = (path: string[]): PathOperation => ({
+  type: 'path',
+  path,
+})
+
+export const functionFormula = (
+  name: string,
+  formula?: Omit<Partial<FunctionOperation>, 'type' | 'name'>,
+): FunctionOperation => ({
+  type: 'function',
+  name,
+  package: formula?.package,
+  arguments: formula?.arguments ?? [],
+  variableArguments: formula?.variableArguments,
+})
+
+export function* getFormulasInFormula<Handler>({
+  formula,
+  globalFormulas,
+  path = [],
+  visitedFormulas = new Set<string>(),
+}: {
+  formula: Formula | undefined | null
+  globalFormulas: GlobalFormulas<Handler>
+  path?: (string | number)[]
+  visitedFormulas?: Set<string>
+}): Generator<[(string | number)[], Formula]> {
+  if (!isDefined(formula)) {
+    return
+  }
+
+  yield [path, formula]
+  switch (formula.type) {
+    case 'path':
+    case 'value':
+      break
+    case 'record':
+      for (const [key, entry] of formula.entries.entries()) {
+        yield* getFormulasInFormula({
+          formula: entry.formula,
+          globalFormulas,
+          path: [...path, 'entries', key, 'formula'],
+          visitedFormulas,
+        })
+      }
+      break
+    case 'function': {
+      const formulaKey = [formula.package, formula.name]
+        .filter(isDefined)
+        .join('/')
+      const shouldVisitFormula = !visitedFormulas.has(formulaKey)
+      visitedFormulas.add(formulaKey)
+      const globalFormula = formula.package
+        ? globalFormulas.packages?.[formula.package]?.formulas?.[formula.name]
+        : globalFormulas.formulas?.[formula.name]
+      for (const [key, arg] of (
+        (formula.arguments as typeof formula.arguments | undefined) ?? []
+      ).entries()) {
+        yield* getFormulasInFormula({
+          formula: arg.formula,
+          globalFormulas,
+          path: [...path, 'arguments', key, 'formula'],
+          visitedFormulas,
+        })
+      }
+      // Lookup the actual function and traverse its potential formula references
+      // if this formula wasn't already visited
+      if (
+        globalFormula &&
+        isToddleFormula(globalFormula) &&
+        shouldVisitFormula
+      ) {
+        yield* getFormulasInFormula({
+          formula: globalFormula.formula,
+          globalFormulas,
+          path: [...path, 'formula'],
+          visitedFormulas,
+        })
+      }
+      break
+    }
+    case 'array':
+    case 'or':
+    case 'and':
+    case 'object':
+      for (const [key, arg] of (
+        (formula.arguments as typeof formula.arguments | undefined) ?? []
+      ).entries()) {
+        yield* getFormulasInFormula({
+          formula: arg.formula,
+          globalFormulas,
+          path: [...path, 'arguments', key, 'formula'],
+          visitedFormulas,
+        })
+      }
+      break
+    case 'apply':
+      for (const [key, arg] of (
+        (formula.arguments as typeof formula.arguments | undefined) ?? []
+      ).entries()) {
+        yield* getFormulasInFormula({
+          formula: arg.formula,
+          globalFormulas,
+          path: [...path, 'arguments', key, 'formula'],
+          visitedFormulas,
+        })
+      }
+      break
+    case 'switch':
+      for (const [key, c] of formula.cases.entries()) {
+        yield* getFormulasInFormula({
+          formula: c.condition,
+          globalFormulas,
+          path: [...path, 'cases', key, 'condition'],
+          visitedFormulas,
+        })
+        yield* getFormulasInFormula({
+          formula: c.formula,
+          globalFormulas,
+          path: [...path, 'cases', key, 'formula'],
+          visitedFormulas,
+        })
+      }
+      yield* getFormulasInFormula({
+        formula: formula.default,
+        globalFormulas,
+        path: [...path, 'default'],
+        visitedFormulas,
+      })
+      break
+  }
+}
+export function* getFormulasInAction<Handler>({
+  action,
+  globalFormulas,
+  path = [],
+  visitedFormulas = new Set<string>(),
+}: {
+  action: ActionModel | null
+  globalFormulas: GlobalFormulas<Handler>
+  path?: (string | number)[]
+  visitedFormulas?: Set<string>
+}): Generator<[(string | number)[], Formula]> {
+  if (!isDefined(action)) {
+    return
+  }
+
+  switch (action.type) {
+    case 'Fetch':
+      for (const [inputKey, input] of Object.entries(action.inputs ?? {})) {
+        yield* getFormulasInFormula({
+          formula: input.formula,
+          globalFormulas,
+          path: [...path, 'input', inputKey, 'formula'],
+          visitedFormulas,
+        })
+      }
+      for (const [key, a] of Object.entries(action.onSuccess?.actions ?? {})) {
+        yield* getFormulasInAction({
+          action: a,
+          globalFormulas,
+          path: [...path, 'onSuccess', 'actions', key],
+          visitedFormulas,
+        })
+      }
+      for (const [key, a] of Object.entries(action.onError?.actions ?? {})) {
+        yield* getFormulasInAction({
+          action: a,
+          globalFormulas,
+          path: [...path, 'onError', 'actions', key],
+          visitedFormulas,
+        })
+      }
+      for (const [key, a] of Object.entries(action.onMessage?.actions ?? {})) {
+        yield* getFormulasInAction({
+          action: a,
+          globalFormulas,
+          path: [...path, 'onMessage', 'actions', key],
+          visitedFormulas,
+        })
+      }
+      break
+    case 'Custom':
+    case undefined:
+      if (isFormula(action.data)) {
+        yield* getFormulasInFormula({
+          formula: action.data,
+          globalFormulas,
+          path: [...path, 'data'],
+          visitedFormulas,
+        })
+      }
+      for (const [key, a] of Object.entries(action.arguments ?? {})) {
+        yield* getFormulasInFormula({
+          formula: a.formula,
+          globalFormulas,
+          path: [...path, 'arguments', key, 'formula'],
+          visitedFormulas,
+        })
+      }
+
+      for (const [eventKey, event] of Object.entries(action.events ?? {})) {
+        for (const [key, a] of Object.entries(event.actions ?? {})) {
+          yield* getFormulasInAction({
+            action: a,
+            globalFormulas,
+            path: [...path, 'events', eventKey, 'actions', key],
+            visitedFormulas,
+          })
+        }
+      }
+      break
+    case 'SetVariable':
+    case 'SetURLParameter':
+    case 'TriggerEvent':
+      yield* getFormulasInFormula({
+        formula: action.data,
+        globalFormulas,
+        path: [...path, 'data'],
+        visitedFormulas,
+      })
+      break
+    case 'TriggerWorkflow':
+      for (const [key, a] of Object.entries(action.parameters ?? {})) {
+        yield* getFormulasInFormula({
+          formula: a.formula,
+          globalFormulas,
+          path: [...path, 'parameters', key, 'formula'],
+          visitedFormulas,
+        })
+      }
+      break
+    case 'Switch':
+      if (isDefined(action.data) && isFormula(action.data)) {
+        yield* getFormulasInFormula({
+          formula: action.data,
+          globalFormulas,
+          path: [...path, 'data'],
+          visitedFormulas,
+        })
+      }
+      for (const [key, c] of action.cases.entries()) {
+        yield* getFormulasInFormula({
+          formula: c.condition,
+          globalFormulas,
+          path: [...path, 'cases', key, 'condition'],
+          visitedFormulas,
+        })
+        for (const [actionKey, a] of Object.entries(c.actions)) {
+          yield* getFormulasInAction({
+            action: a,
+            globalFormulas,
+            path: [...path, 'cases', key, 'actions', actionKey],
+            visitedFormulas,
+          })
+        }
+      }
+      for (const [actionKey, a] of Object.entries(action.default.actions)) {
+        yield* getFormulasInAction({
+          action: a,
+          globalFormulas,
+          path: [...path, 'default', 'actions', actionKey],
+          visitedFormulas,
+        })
+      }
+      break
+  }
+}

package/src/styling/className.test.ts

@@ -0,0 +1,19 @@
+import { toValidClassName } from './className'
+
+describe('toValidClassName()', () => {
+  test('it trims leading and trailing whitespace and replace the remaining whitespace with hyphens', () => {
+    expect(toValidClassName('  my class  ')).toBe('my-class')
+  })
+
+  test('it escapes invalid characters by prefixing them with a backslash, if flag is set', () => {
+    expect(toValidClassName('my.class', true)).toBe('my\\.class')
+  })
+
+  test('it does not escape invalid characters by default', () => {
+    expect(toValidClassName('my.class')).toBe('my.class')
+  })
+
+  test('it ensures the class name does not start with a number or special character', () => {
+    expect(toValidClassName('1class')).toBe('_1class')
+  })
+})