sovrium 0.0.2

package/src/presentation/ui/sections/translations/i18n-content-resolver.ts

@@ -0,0 +1,198 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { resolveChildTranslation } from './translation-handler'
+import type { Languages } from '@/domain/models/app/languages'
+
+/**
+ * Builds i18n content data attribute for client-side language switching (functional approach)
+ *
+ * Extracts content translations from i18n object and serializes to JSON.
+ * Includes default language content as fallback.
+ *
+ * @param i18n - Component i18n translations object
+ * @param defaultContent - Default content for base language
+ * @param defaultLang - Default language code
+ * @returns JSON-stringified i18n content data or undefined if no translations
+ */
+function buildI18nContentAttribute(
+  i18n: Record<string, unknown>,
+  defaultContent: string,
+  defaultLang: string | undefined
+): string | undefined {
+  // Extract content from i18n object using functional approach (reduce instead of for loop)
+  const i18nContentData = Object.entries(i18n).reduce<Record<string, string>>(
+    (acc, [lang, value]) => {
+      if (typeof value === 'object' && value !== null && 'content' in value && value.content) {
+        return { ...acc, [lang]: value.content as string }
+      }
+      return acc
+    },
+    {}
+  )
+
+  // Add default language content if not already present
+  const contentWithDefault =
+    defaultLang && !i18nContentData[defaultLang]
+      ? { ...i18nContentData, [defaultLang]: defaultContent }
+      : i18nContentData
+
+  // Only return attribute if there are translations
+  return Object.keys(contentWithDefault).length > 0 ? JSON.stringify(contentWithDefault) : undefined
+}
+
+/**
+ * Resolves component content with i18n priority
+ *
+ * Priority: component.i18n[lang].content > $t: pattern > content
+ *
+ * @param content - Base content string
+ * @param i18n - Component i18n translations
+ * @param currentLang - Current language code
+ * @param languages - Languages configuration
+ * @returns Resolved content string
+ */
+function resolveComponentContent(
+  content: string | Record<string, unknown> | undefined,
+  i18n: Record<string, unknown> | undefined,
+  currentLang: string | undefined,
+  languages: Languages | undefined
+): string | undefined {
+  // If content is an object (structured content like { button: {...} }), return undefined
+  // The component renderer will handle structured content directly
+  if (content && typeof content === 'object') {
+    return undefined
+  }
+
+  if (i18n && currentLang) {
+    const langData = i18n[currentLang]
+    if (
+      langData &&
+      typeof langData === 'object' &&
+      'content' in langData &&
+      typeof langData.content === 'string'
+    ) {
+      return langData.content
+    }
+  }
+  if (content) {
+    return resolveChildTranslation(content, currentLang, languages)
+  }
+  return content
+}
+
+/**
+ * Builds final element props with i18n data attribute
+ *
+ * @param baseProps - Base element props
+ * @param i18nAttribute - Optional i18n content JSON string
+ * @returns Element props with i18n data merged if present
+ */
+function buildFinalElementProps(
+  baseProps: Record<string, unknown>,
+  i18nAttribute: string | undefined
+): Record<string, unknown> {
+  return i18nAttribute ? { ...baseProps, 'data-i18n-content': i18nAttribute } : baseProps
+}
+
+/**
+ * Configuration for resolving i18n content
+ */
+export interface ResolveI18nContentConfig {
+  readonly content: string | Record<string, unknown> | undefined
+  readonly i18n: Record<string, unknown> | undefined
+  readonly currentLang: string | undefined
+  readonly languages: Languages | undefined
+  readonly elementProps: Record<string, unknown>
+  readonly elementPropsWithSpacing: Record<string, unknown>
+}
+
+/**
+ * Resolves i18n content and builds element props with i18n data attribute (config object signature)
+ */
+export function resolveI18nContent(config: ResolveI18nContentConfig): {
+  readonly resolvedContent: string | undefined
+  readonly finalElementProps: Record<string, unknown>
+  readonly finalElementPropsWithSpacing: Record<string, unknown>
+}
+
+/**
+ * Resolves i18n content and builds element props with i18n data attribute (individual parameters signature)
+ */
+// eslint-disable-next-line max-params -- Function overload signature
+export function resolveI18nContent(
+  content: string | Record<string, unknown> | undefined,
+  i18n: Record<string, unknown> | undefined,
+  currentLang: string | undefined,
+  languages: Languages | undefined,
+  elementProps: Record<string, unknown>,
+  elementPropsWithSpacing: Record<string, unknown>
+): {
+  readonly resolvedContent: string | undefined
+  readonly finalElementProps: Record<string, unknown>
+  readonly finalElementPropsWithSpacing: Record<string, unknown>
+}
+
+/**
+ * Implementation
+ */
+// eslint-disable-next-line max-params -- Implementation handles both signatures
+export function resolveI18nContent(
+  configOrContent: ResolveI18nContentConfig | string | Record<string, unknown> | undefined,
+  i18n?: Record<string, unknown>,
+  currentLang?: string,
+  languages?: Languages,
+  elementProps?: Record<string, unknown>,
+  elementPropsWithSpacing?: Record<string, unknown>
+): {
+  readonly resolvedContent: string | undefined
+  readonly finalElementProps: Record<string, unknown>
+  readonly finalElementPropsWithSpacing: Record<string, unknown>
+} {
+  // Support both config object and individual parameters
+  const config: ResolveI18nContentConfig =
+    configOrContent && typeof configOrContent === 'object' && 'content' in configOrContent
+      ? (configOrContent as ResolveI18nContentConfig)
+      : {
+          content: configOrContent as string | Record<string, unknown> | undefined,
+          i18n: i18n!,
+          currentLang: currentLang!,
+          languages: languages!,
+          elementProps: elementProps!,
+          elementPropsWithSpacing: elementPropsWithSpacing!,
+        }
+
+  const {
+    content,
+    i18n: i18nConfig,
+    currentLang: lang,
+    languages: langs,
+    elementProps: props,
+    elementPropsWithSpacing: propsWithSpacing,
+  } = config
+
+  // Resolve content with i18n priority: component.i18n[lang].content > $t: pattern > content
+  const resolvedContent = resolveComponentContent(content, i18nConfig, lang, langs)
+
+  // Build i18n content data attribute and merge into element props (functional approach)
+  const i18nContentAttribute =
+    i18nConfig && content
+      ? buildI18nContentAttribute(i18nConfig, content as string, langs?.default)
+      : undefined
+
+  const finalElementProps = buildFinalElementProps(props, i18nContentAttribute)
+  const finalElementPropsWithSpacing = buildFinalElementProps(
+    propsWithSpacing,
+    i18nContentAttribute
+  )
+
+  return {
+    resolvedContent,
+    finalElementProps,
+    finalElementPropsWithSpacing,
+  }
+}

package/src/presentation/ui/sections/translations/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+// Barrel export for translation utilities
+// Files will be added during migration

package/src/presentation/ui/sections/translations/translation-handler.ts

@@ -0,0 +1,143 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import {
+  collectTranslationsForKey,
+  resolveTranslationPattern,
+} from '@/presentation/translations/translation-resolver'
+import type { Languages } from '@/domain/models/app/languages'
+import type { Component } from '@/domain/models/app/page/sections'
+
+/**
+ * Find first translation key in children
+ */
+export function findFirstTranslationKey(
+  children: readonly (Component | string)[] | undefined
+): string | undefined {
+  return children
+    ?.find(
+      (child: Component | string): child is string =>
+        typeof child === 'string' && child.startsWith('$t:')
+    )
+    ?.slice(3) // Remove '$t:' prefix
+}
+
+/**
+ * Extract translation key from content string
+ * Returns the key portion after $t: prefix if content is a translation token
+ */
+export function extractTranslationKeyFromContent(content: string | undefined): string | undefined {
+  if (!content || typeof content !== 'string') return undefined
+  return content.startsWith('$t:') ? content.slice(3) : undefined
+}
+
+/**
+ * Get current language with fallback
+ */
+export function getCurrentLanguage(
+  currentLang: string | undefined,
+  languages: Languages | undefined
+): string {
+  return currentLang || languages?.default || 'en-US'
+}
+
+/**
+ * Resolve translation pattern for a child element
+ */
+export function resolveChildTranslation(
+  child: string,
+  currentLang: string | undefined,
+  languages: Languages | undefined
+): string {
+  const lang = getCurrentLanguage(currentLang, languages)
+  return resolveTranslationPattern(child, lang, languages)
+}
+
+/**
+ * Collect translation data for a key
+ */
+export function getTranslationData(
+  translationKey: string | undefined,
+  languages: Languages | undefined
+): Record<string, string> | undefined {
+  return translationKey ? collectTranslationsForKey(translationKey, languages) : undefined
+}
+
+/**
+ * Substitutes translation tokens in props recursively
+ *
+ * Walks through props object and replaces all $t:key patterns with actual translations.
+ * Handles nested objects (e.g., style props) recursively.
+ *
+ * @param props - Component props that may contain translation tokens
+ * @param currentLang - Current language code
+ * @param languages - Languages configuration
+ * @returns Props with translation tokens replaced
+ *
+ * @example
+ * ```typescript
+ * const languages = {
+ *   default: 'en',
+ *   translations: { 'en': { 'close.label': 'Close dialog' } }
+ * }
+ * const props = {
+ *   'aria-label': '$t:close.label',
+ *   title: 'Static text'
+ * }
+ * substitutePropsTranslationTokens(props, 'en-US', languages)
+ * // {
+ * //   'aria-label': 'Close dialog',
+ * //   title: 'Static text'
+ * // }
+ * ```
+ */
+export function substitutePropsTranslationTokens(
+  props: Record<string, unknown> | undefined,
+  currentLang: string | undefined,
+  languages: Languages | undefined
+): Record<string, unknown> | undefined {
+  if (!props || !languages) {
+    return props
+  }
+
+  const lang = getCurrentLanguage(currentLang, languages)
+
+  // Use functional Object.entries + reduce for immutable transformation
+  return Object.entries(props).reduce<Record<string, unknown>>((acc, [key, value]) => {
+    if (typeof value === 'string') {
+      return { ...acc, [key]: resolveTranslationPattern(value, lang, languages) }
+    } else if (Array.isArray(value)) {
+      // Recursively handle arrays (like navigation links, footer columns)
+      return {
+        ...acc,
+        [key]: value.map((item) =>
+          item && typeof item === 'object' && !Array.isArray(item)
+            ? substitutePropsTranslationTokens(
+                item as Record<string, unknown>,
+                currentLang,
+                languages
+              )
+            : typeof item === 'string'
+              ? resolveTranslationPattern(item, lang, languages)
+              : item
+        ),
+      }
+    } else if (value && typeof value === 'object') {
+      // Recursively handle nested objects (like style props)
+      return {
+        ...acc,
+        [key]: substitutePropsTranslationTokens(
+          value as Record<string, unknown>,
+          currentLang,
+          languages
+        ),
+      }
+    } else {
+      return { ...acc, [key]: value }
+    }
+  }, {})
+}

package/src/presentation/ui/sections/translations/variable-substitution.ts

@@ -0,0 +1,225 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { toKebabCase } from '@/presentation/utils/string-utils'
+import type { Component } from '@/domain/models/app/page/sections'
+
+/**
+ * Replaces variable placeholders in a string with actual values
+ *
+ * Uses regex with word boundary checking to avoid partial matches.
+ * For example, $icon will not match inside $iconColor.
+ *
+ * @param value - String that may contain $variable placeholders
+ * @param vars - Variables for substitution
+ * @returns String with all variables replaced
+ *
+ * @example
+ * ```typescript
+ * replaceVariables('$title', { title: 'Hello' })  // 'Hello'
+ * replaceVariables('$price/month', { price: '49' })  // '49/month'
+ * replaceVariables('box-$variant', { variant: 'primary' })  // 'box-primary'
+ * ```
+ */
+function replaceVariables(value: string, vars: Record<string, string | number | boolean>): string {
+  // Use regex with word boundary to avoid partial matches
+  // e.g., $icon should not match inside $iconColor
+  return Object.entries(vars).reduce<string>((str, [varName, varValue]) => {
+    // Create regex that matches $varName as a whole word
+    // Use negative lookahead to ensure we don't match if followed by alphanumeric or underscore
+    const regex = new RegExp(`\\$${varName}(?![a-zA-Z0-9_])`, 'g')
+    return str.replace(regex, String(varValue))
+  }, value)
+}
+
+/**
+ * Substitutes variable values in a value
+ *
+ * Replaces `$variableName` patterns with actual variable values.
+ * Supports both full replacement ($title → 'Welcome') and partial replacement
+ * within strings ($price/month → '49/month').
+ *
+ * @param value - Value that may contain variable placeholders
+ * @param vars - Variables for substitution
+ * @returns Value with variables replaced
+ *
+ * @example
+ * ```typescript
+ * substituteVariableValues('$title', { title: 'Hello' }) // 'Hello'
+ * substituteVariableValues('$price/month', { price: '49' }) // '49/month'
+ * substituteVariableValues('static', { title: 'Hello' }) // 'static'
+ * substituteVariableValues(123, { title: 'Hello' })       // 123
+ * ```
+ */
+export function substituteVariableValues(
+  value: unknown,
+  vars?: Record<string, string | number | boolean>
+): unknown {
+  if (typeof value !== 'string') {
+    return value
+  }
+
+  if (!vars || !value.includes('$')) {
+    return value
+  }
+
+  return replaceVariables(value, vars)
+}
+
+/**
+ * Substitutes variables in component children recursively
+ *
+ * Pure function that walks through the children tree and replaces $variable
+ * placeholders with actual values from the vars object.
+ *
+ * @param children - Array of children (can be strings or components)
+ * @param vars - Variables for substitution
+ * @returns Children with variables substituted
+ *
+ * @example
+ * ```typescript
+ * substituteChildrenVariables(
+ *   [
+ *     '$greeting',
+ *     { type: 'span', content: '$name' }
+ *   ],
+ *   { greeting: 'Hello', name: 'World' }
+ * )
+ * // ['Hello', { type: 'span', content: 'World' }]
+ * ```
+ */
+export function substituteChildrenVariables(
+  children: ReadonlyArray<Component | string> | undefined,
+  vars?: Record<string, string | number | boolean>
+): ReadonlyArray<Component | string> | undefined {
+  if (!children || !vars) {
+    return children
+  }
+
+  return children.map((child) => {
+    // If child is a string, apply variable substitution
+    if (typeof child === 'string') {
+      const substituted = substituteVariableValues(child, vars)
+      return substituted as string
+    }
+
+    // If child is a component, recursively substitute in its props, children and content
+    const substitutedProps = substitutePropsVariables(child.props, vars)
+    const substitutedChildren = substituteChildrenVariables(child.children, vars)
+    const substitutedContent =
+      typeof child.content === 'string'
+        ? (substituteVariableValues(child.content, vars) as string)
+        : child.content
+
+    return {
+      ...child,
+      props: substitutedProps,
+      children: substitutedChildren,
+      content: substitutedContent,
+    }
+  })
+}
+
+/**
+ * Converts camelCase prop names to kebab-case for HTML attributes
+ *
+ * React JSX expects certain attributes in kebab-case (aria-*, data-*),
+ * but our schema may define them in camelCase for convenience.
+ * This function normalizes prop names to the format React expects.
+ *
+ * Handles both camelCase (ariaLabel) and already-kebab-case (aria-label) inputs.
+ * If prop is already in kebab-case, it returns unchanged to avoid double-conversion.
+ *
+ * @param key - Property key (potentially in camelCase or kebab-case)
+ * @returns Normalized key (kebab-case for aria/data attributes)
+ *
+ * @example
+ * ```typescript
+ * normalizeAriaDataProps('ariaLabel') // 'aria-label'
+ * normalizeAriaDataProps('aria-label') // 'aria-label' (unchanged)
+ * normalizeAriaDataProps('dataTestId') // 'data-test-id'
+ * normalizeAriaDataProps('data-test-id') // 'data-test-id' (unchanged)
+ * normalizeAriaDataProps('className') // 'className' (unchanged)
+ * ```
+ */
+function normalizeAriaDataProps(key: string): string {
+  // Convert ariaLabel → aria-label, dataTestId → data-test-id
+  // Check if fifth character is uppercase letter (not hyphen or other character)
+  // to avoid double-conversion (aria-label → aria--label)
+  if (key.startsWith('aria') && key.length > 4 && key[4] !== undefined && /[A-Z]/.test(key[4])) {
+    // ariaLabel → aria-label
+    const suffix = key.slice(4) // 'Label'
+    const kebabSuffix = toKebabCase(suffix) // 'label'
+    return `aria-${kebabSuffix}`
+  }
+
+  if (key.startsWith('data') && key.length > 4 && key[4] !== undefined && /[A-Z]/.test(key[4])) {
+    // dataTestId → data-test-id
+    const suffix = key.slice(4) // 'TestId'
+    const kebabSuffix = toKebabCase(suffix) // 'test-id'
+    return `data-${kebabSuffix}`
+  }
+
+  return key
+}
+
+/**
+ * Substitutes variables in props recursively
+ *
+ * Walks through props object and replaces all $variable strings with actual values.
+ * Handles nested objects (e.g., style props) recursively.
+ * Supports variable substitution in string values, including partial substitution
+ * within strings (e.g., 'box-$variant' → 'box-primary').
+ * Normalizes aria* and data* prop names to kebab-case for React compatibility.
+ *
+ * @param props - Component props that may contain variable placeholders
+ * @param vars - Variables for substitution
+ * @returns Props with variables replaced and prop names normalized
+ *
+ * @example
+ * ```typescript
+ * const vars = { variant: 'primary', boxId: 'main-box', label: 'Main content' }
+ * const props = {
+ *   className: 'box-$variant',
+ *   id: '$boxId',
+ *   ariaLabel: '$label'
+ * }
+ * substitutePropsVariables(props, vars)
+ * // {
+ * //   className: 'box-primary',
+ * //   id: 'main-box',
+ * //   'aria-label': 'Main content'
+ * // }
+ * ```
+ */
+export function substitutePropsVariables(
+  props: Record<string, unknown> | undefined,
+  vars?: Record<string, string | number | boolean>
+): Record<string, unknown> | undefined {
+  if (!props || !vars) {
+    return props
+  }
+
+  // Use functional Object.entries + reduce for immutable transformation
+  return Object.entries(props).reduce<Record<string, unknown>>((acc, [key, value]) => {
+    // Normalize aria/data prop names (ariaLabel → aria-label)
+    const normalizedKey = normalizeAriaDataProps(key)
+
+    if (typeof value === 'string') {
+      // Handle partial substitution within strings (e.g., 'box-$variant' → 'box-primary')
+      return { ...acc, [normalizedKey]: replaceVariables(value, vars) }
+    } else if (value && typeof value === 'object' && !Array.isArray(value)) {
+      // Recursively handle nested objects (like style props)
+      return {
+        ...acc,
+        [normalizedKey]: substitutePropsVariables(value as Record<string, unknown>, vars),
+      }
+    } else {
+      return { ...acc, [normalizedKey]: value }
+    }
+  }, {})
+}

package/src/presentation/ui/sections/utils/time-parser.ts

@@ -0,0 +1,82 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+/**
+ * Time string parsing and formatting utilities
+ *
+ * Provides pure functions for converting between time strings (e.g., "100ms", "0.5s")
+ * and millisecond values. Used for animation timing calculations.
+ */
+
+/**
+ * Parse time string to milliseconds
+ *
+ * @param timeStr - Time string (e.g., "100ms", "0.5s", "1s")
+ * @returns Time in milliseconds
+ *
+ * @example
+ * parseTimeToMs('100ms') // => 100
+ * parseTimeToMs('0.5s')  // => 500
+ * parseTimeToMs('1s')    // => 1000
+ */
+export function parseTimeToMs(timeStr: string): number {
+  if (timeStr.endsWith('ms')) {
+    return parseInt(timeStr.slice(0, -2), 10)
+  }
+  if (timeStr.endsWith('s')) {
+    return parseFloat(timeStr.slice(0, -1)) * 1000
+  }
+  return 0
+}
+
+/**
+ * Format milliseconds to time string
+ *
+ * @param ms - Time in milliseconds
+ * @returns Time string in milliseconds format
+ *
+ * @example
+ * formatMsToTime(100)  // => "100ms"
+ * formatMsToTime(500)  // => "500ms"
+ * formatMsToTime(1000) // => "1000ms"
+ */
+export function formatMsToTime(ms: number): string {
+  return `${ms}ms`
+}
+
+/**
+ * Calculate total delay including stagger offset
+ *
+ * Adds stagger delay based on child index to create sequential animation effects.
+ * Commonly used for entrance animations of multiple child elements.
+ *
+ * @param delay - Base delay string (e.g., "100ms")
+ * @param stagger - Stagger delay per sibling (e.g., "50ms")
+ * @param childIndex - Current child index (0-based)
+ * @returns Total delay string or undefined if no stagger
+ *
+ * @example
+ * calculateTotalDelay('100ms', '50ms', 0) // => "100ms"
+ * calculateTotalDelay('100ms', '50ms', 1) // => "150ms"
+ * calculateTotalDelay('100ms', '50ms', 2) // => "200ms"
+ * calculateTotalDelay('100ms', undefined, 2) // => "100ms"
+ */
+export function calculateTotalDelay(
+  delay: string | undefined,
+  stagger: string | undefined,
+  childIndex: number | undefined
+): string | undefined {
+  if (!stagger || childIndex === undefined) {
+    return delay
+  }
+
+  const baseDelayMs = delay ? parseTimeToMs(delay) : 0
+  const staggerMs = parseTimeToMs(stagger)
+  const totalDelayMs = baseDelayMs + staggerMs * childIndex
+
+  return formatMsToTime(totalDelayMs)
+}