sovrium 0.0.2

package/src/presentation/ui/sections/styling/interaction-props-builder.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 { buildHoverData } from './hover-interaction-handler'
+import type { Interactions } from '@/domain/models/app/page/common/interactions/interactions'
+
+/**
+ * Merges hover attributes into element props
+ *
+ * @param elementProps - Base element props
+ * @param hoverData - Hover data with attributes
+ * @returns Element props with hover attributes merged
+ */
+function mergeHoverAttributes(
+  elementProps: Record<string, unknown>,
+  hoverData: { readonly attributes: Record<string, string> } | undefined
+): Record<string, unknown> {
+  return hoverData ? { ...elementProps, ...hoverData.attributes } : elementProps
+}
+
+/**
+ * Builds interaction props with hover data merged into element props
+ *
+ * @param interactions - Component interactions configuration
+ * @param uniqueId - Unique ID for hover data
+ * @param elementProps - Base element props
+ * @param elementPropsWithSpacing - Base element props with spacing
+ * @returns Element props with hover attributes and hover data for style injection
+ */
+export function buildInteractionProps(
+  interactions: Interactions | undefined,
+  uniqueId: string,
+  elementProps: Record<string, unknown>,
+  elementPropsWithSpacing: Record<string, unknown>
+): {
+  readonly finalElementProps: Record<string, unknown>
+  readonly finalElementPropsWithSpacing: Record<string, unknown>
+  readonly hoverData:
+    | { readonly attributes: Record<string, string>; readonly styleContent: string }
+    | undefined
+} {
+  const hoverData = buildHoverData(interactions?.hover, uniqueId)
+  const finalElementProps = mergeHoverAttributes(elementProps, hoverData)
+  const finalElementPropsWithSpacing = mergeHoverAttributes(elementPropsWithSpacing, hoverData)
+
+  return {
+    finalElementProps,
+    finalElementPropsWithSpacing,
+    hoverData,
+  }
+}

package/src/presentation/ui/sections/styling/shadow-resolver.ts

@@ -0,0 +1,83 @@
+/**
+ * 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 type { Component } from '@/domain/models/app/page/sections'
+import type { Theme } from '@/domain/models/app/theme'
+
+/**
+ * Standard shadow size names
+ */
+const STANDARD_SHADOWS = ['sm', 'md', 'lg', 'xl', '2xl', 'inner', 'none'] as const
+
+/**
+ * Shadow mapping for component types
+ */
+const COMPONENT_SHADOW_MAP: Record<string, readonly string[]> = {
+  'list-item': ['sm'],
+  dropdown: ['lg'],
+  modal: ['xl'],
+  input: ['inner'],
+  button: ['brand', 'md'],
+  card: [], // Card uses custom logic
+}
+
+/**
+ * Find first available custom shadow (non-standard)
+ */
+function findCustomShadow(shadows: Theme['shadows']): string | undefined {
+  if (!shadows) return undefined
+  return Object.keys(shadows).find((name) => !STANDARD_SHADOWS.includes(name as never))
+}
+
+/**
+ * Get shadow value for component type
+ */
+function getShadowForType(type: Component['type'], shadows: Theme['shadows']): string | undefined {
+  if (!shadows) return undefined
+
+  // Special handling for card: custom shadows first, then md
+  if (type === 'card') {
+    const customShadow = findCustomShadow(shadows)
+    if (customShadow) {
+      return `var(--shadow-${customShadow})`
+    }
+    return shadows.md ? 'var(--shadow-md)' : undefined
+  }
+
+  // Standard component shadow resolution
+  const shadowPriority = COMPONENT_SHADOW_MAP[type]
+  if (!shadowPriority) {
+    return undefined
+  }
+
+  const foundShadow = shadowPriority.find((shadowName) =>
+    Boolean(shadows[shadowName as keyof typeof shadows])
+  )
+
+  return foundShadow ? `var(--shadow-${foundShadow})` : undefined
+}
+
+/**
+ * Apply theme shadows to component types based on conventions
+ * - Card components use available shadow tokens (md, neumorphic, etc.)
+ * - Modal components use xl shadow
+ * - Input components use inner shadow
+ * - Button components use md shadow (or custom like brand)
+ * - List-item components use sm shadow (lowest elevation)
+ * - Dropdown components use lg shadow (higher than card, lower than modal)
+ */
+export function getComponentShadow(
+  type: Component['type'],
+  theme?: Theme
+): Record<string, unknown> | undefined {
+  if (!theme?.shadows) {
+    return undefined
+  }
+
+  const shadowValue = getShadowForType(type, theme.shadows)
+  return shadowValue ? { boxShadow: shadowValue } : undefined
+}

package/src/presentation/ui/sections/styling/spacing-resolver.ts

@@ -0,0 +1,104 @@
+/**
+ * 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 { isCssValue } from '@/presentation/styling/style-utils'
+import { getSectionColorStyle } from './color-resolver'
+import type { Component } from '@/domain/models/app/page/sections'
+import type { Theme } from '@/domain/models/app/theme'
+
+/**
+ * Component types that should receive section spacing
+ */
+const SECTION_TYPES = new Set(['section', 'header', 'footer', 'hero'])
+
+/**
+ * Apply theme spacing to section elements when spacing.section is a CSS value
+ */
+export function getSectionSpacingStyle(
+  type: Component['type'],
+  theme?: Theme
+): Record<string, unknown> | undefined {
+  const sectionSpacing = SECTION_TYPES.has(type) && theme?.spacing?.section
+  return sectionSpacing && isCssValue(sectionSpacing) ? { padding: sectionSpacing } : undefined
+}
+
+/**
+ * Apply theme spacing to container elements when spacing.container is a CSS value
+ */
+export function getContainerSpacingStyle(
+  type: Component['type'],
+  theme?: Theme
+): Record<string, unknown> | undefined {
+  const containerSpacing = type === 'container' && theme?.spacing?.container
+  return containerSpacing && isCssValue(containerSpacing)
+    ? { maxWidth: containerSpacing, margin: '0 auto' }
+    : undefined
+}
+
+/**
+ * Apply theme spacing to flex elements when spacing.gap is a CSS value
+ */
+export function getFlexSpacingStyle(
+  type: Component['type'],
+  theme?: Theme
+): Record<string, unknown> | undefined {
+  const flexSpacing = type === 'flex' && theme?.spacing?.gap
+  return flexSpacing && isCssValue(flexSpacing) ? { display: 'flex', gap: flexSpacing } : undefined
+}
+
+/**
+ * Apply all spacing and color styles in order: color → section → container → flex
+ */
+export function applySpacingStyles(
+  type: Component['type'],
+  baseProps: Record<string, unknown>,
+  theme?: Theme
+): Record<string, unknown> {
+  const colorStyle = getSectionColorStyle(type, theme)
+  const propsWithColor = colorStyle
+    ? {
+        ...baseProps,
+        style: {
+          ...(baseProps.style as Record<string, unknown> | undefined),
+          ...colorStyle,
+        },
+      }
+    : baseProps
+
+  const sectionSpacingStyle = getSectionSpacingStyle(type, theme)
+  const propsWithSection = sectionSpacingStyle
+    ? {
+        ...propsWithColor,
+        style: {
+          ...(propsWithColor.style as Record<string, unknown> | undefined),
+          ...sectionSpacingStyle,
+        },
+      }
+    : propsWithColor
+
+  const containerSpacingStyle = getContainerSpacingStyle(type, theme)
+  const propsWithContainer = containerSpacingStyle
+    ? {
+        ...propsWithSection,
+        style: {
+          ...(propsWithSection.style as Record<string, unknown> | undefined),
+          ...containerSpacingStyle,
+        },
+      }
+    : propsWithSection
+
+  const flexSpacingStyle = getFlexSpacingStyle(type, theme)
+  return flexSpacingStyle
+    ? {
+        ...propsWithContainer,
+        style: {
+          ...(propsWithContainer.style as Record<string, unknown> | undefined),
+          ...flexSpacingStyle,
+        },
+      }
+    : propsWithContainer
+}

package/src/presentation/ui/sections/styling/style-processor.ts

@@ -0,0 +1,170 @@
+/**
+ * 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 {
+  isCssProperty,
+  normalizeStyleAnimations,
+  parseStyle,
+} from '@/presentation/styling/parse-style'
+import { applyComponentAnimations } from './animation-composer-wrapper'
+import { buildFlexClasses, buildGridClasses } from './class-builders'
+import { getComponentShadow } from './shadow-resolver'
+import type { Interactions } from '@/domain/models/app/page/common/interactions/interactions'
+import type { Component } from '@/domain/models/app/page/sections'
+import type { Theme } from '@/domain/models/app/theme'
+
+/**
+ * Extract CSS properties from props object
+ * Separates CSS properties (e.g., maxWidth, backgroundColor) from other props
+ *
+ * @param props - Props object that may contain CSS properties
+ * @returns Object with cssProps and remainingProps
+ */
+export function extractCssProperties(props: Record<string, unknown> | undefined): {
+  readonly cssProps: Record<string, unknown>
+  readonly remainingProps: Record<string, unknown>
+} {
+  if (!props) {
+    return { cssProps: {}, remainingProps: {} }
+  }
+
+  // Use reduce for immutable accumulation
+  return Object.entries(props).reduce<{
+    readonly cssProps: Record<string, unknown>
+    readonly remainingProps: Record<string, unknown>
+  }>(
+    (acc, [key, value]) => {
+      if (isCssProperty(key)) {
+        return {
+          ...acc,
+          cssProps: { ...acc.cssProps, [key]: value },
+        }
+      }
+      return {
+        ...acc,
+        remainingProps: { ...acc.remainingProps, [key]: value },
+      }
+    },
+    { cssProps: {}, remainingProps: {} }
+  )
+}
+
+/**
+ * Parse and normalize style object
+ * Extracts CSS properties from the root of the props object and merges them with the style property
+ */
+export function parseComponentStyle(
+  styleValue: unknown,
+  props: Record<string, unknown> | undefined
+): Record<string, unknown> | undefined {
+  // Parse the explicit style property
+  const explicitStyle = styleValue
+    ? normalizeStyleAnimations(
+        typeof styleValue === 'string'
+          ? parseStyle(styleValue)
+          : (styleValue as Record<string, unknown>)
+      )
+    : undefined
+
+  // Extract CSS properties from props (excluding the style property itself)
+  const { cssProps } = extractCssProperties(props)
+
+  // Remove the style property from cssProps if it exists (already handled above)
+  const { style: _style, ...cssPropsWithoutStyle } = cssProps
+
+  // Merge CSS properties with explicit style
+  const mergedStyle = {
+    ...cssPropsWithoutStyle,
+    ...explicitStyle,
+  }
+
+  return Object.keys(mergedStyle).length > 0 ? mergedStyle : undefined
+}
+
+/**
+ * Maps component types to their corresponding CSS class names in @layer components.
+ * These classes are automatically added to the element when rendering.
+ *
+ * Most types map directly (e.g. 'card' -> 'card'), but 'button' maps to 'btn'
+ * because the CSS components layer uses `.btn` (not a `button` type selector)
+ * to avoid applying default button styles to all `<button>` elements globally.
+ */
+const COMPONENT_TYPE_CLASS_MAP: Partial<Record<string, string>> = {
+  card: 'card',
+  badge: 'badge',
+  btn: 'btn',
+  button: 'btn',
+}
+
+/**
+ * Build entrance animation class from interactions
+ *
+ * @param interactions - Component interactions
+ * @returns Animation class or undefined
+ */
+function buildEntranceAnimationClass(interactions: Interactions | undefined): string | undefined {
+  if (!interactions?.entrance?.animation) return undefined
+
+  return `animate-${interactions.entrance.animation}`
+}
+
+/**
+ * Configuration for building final className
+ */
+type BuildClassNameConfig = {
+  readonly type: Component['type']
+  readonly className: unknown
+  readonly substitutedProps: Record<string, unknown> | undefined
+  readonly interactions: Interactions | undefined
+}
+
+/**
+ * Build final className based on component type
+ */
+export function buildFinalClassName(config: BuildClassNameConfig): string | undefined {
+  const { type, className, substitutedProps, interactions } = config
+
+  // Build classes array immutably
+  const typeClass = COMPONENT_TYPE_CLASS_MAP[type]
+  const flexClass = type === 'flex' ? buildFlexClasses(substitutedProps) : undefined
+  const gridClass = type === 'grid' ? buildGridClasses(substitutedProps) : undefined
+  const customClass = className as string | undefined
+  const entranceClass = buildEntranceAnimationClass(interactions)
+  // Don't add scroll animation class to initial className - it will be added by scroll-animation.js
+  const scrollClass = undefined
+
+  const classes = [typeClass, flexClass, gridClass, customClass, entranceClass, scrollClass]
+    .filter(Boolean)
+    .join(' ')
+  return classes || undefined
+}
+
+/**
+ * Apply shadow to style based on component type
+ */
+export function applyComponentShadow(
+  type: Component['type'],
+  style: Record<string, unknown> | undefined,
+  theme: Theme | undefined
+): Record<string, unknown> | undefined {
+  const componentShadow = getComponentShadow(type, theme)
+  return componentShadow ? { ...style, ...componentShadow } : style
+}
+
+/**
+ * Process style with animations and shadows
+ */
+export function processComponentStyle(
+  type: Component['type'],
+  styleValue: unknown,
+  theme: Theme | undefined,
+  props?: Record<string, unknown> | undefined
+): Record<string, unknown> | undefined {
+  const baseStyle = parseComponentStyle(styleValue, props)
+  const styleWithAnimations = applyComponentAnimations(type, baseStyle, theme)
+  return applyComponentShadow(type, styleWithAnimations, theme)
+}

package/src/presentation/ui/sections/styling/theme-tokens.ts

@@ -0,0 +1,184 @@
+/**
+ * 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 type { Theme } from '@/domain/models/app/theme'
+
+/**
+ * Substitutes theme tokens in a value
+ *
+ * Replaces `$theme.category.key` patterns with actual theme values.
+ * Supports multiple tokens in a single string.
+ *
+ * @param value - Value that may contain theme tokens
+ * @param theme - Theme configuration
+ * @returns Value with theme tokens replaced
+ *
+ * @example
+ * ```typescript
+ * const theme = {
+ *   colors: { primary: '#007bff' },
+ *   spacing: { section: 'py-16', container: 'px-4' }
+ * }
+ * substituteThemeTokens('$theme.colors.primary', theme)
+ * // '#007bff'
+ *
+ * substituteThemeTokens('$theme.spacing.section $theme.spacing.container', theme)
+ * // 'py-16 px-4'
+ *
+ * substituteThemeTokens('static', theme)
+ * // 'static'
+ *
+ * substituteThemeTokens(123, theme)
+ * // 123
+ * ```
+ */
+export function substituteThemeTokens(value: unknown, theme?: Theme): unknown {
+  if (typeof value !== 'string') {
+    return value
+  }
+
+  if (!theme || !value.includes('$theme.')) {
+    return value
+  }
+
+  // Handle multiple theme tokens in a single string
+  // Example: "$theme.spacing.section $theme.spacing.container" → "py-16 px-4"
+  // Supports color names with numbers like gray-100, primary-500, etc.
+  return value.replace(/\$theme\.[a-z]+(\.[a-z0-9-]+)+/g, (match) => {
+    // Extract the path: $theme.colors.primary → ['colors', 'primary']
+    const path = match.slice(7).split('.')
+
+    // Navigate through the theme object using functional reduce
+    const result = path.reduce<unknown>((acc, key) => {
+      if (acc && typeof acc === 'object' && key in acc) {
+        return (acc as Record<string, unknown>)[key]
+      }
+      // Return a sentinel to indicate path not found
+      return undefined
+    }, theme as unknown)
+
+    // If path navigation failed, return original token
+    return result !== undefined ? String(result) : match
+  })
+}
+
+/**
+ * Resolve shorthand theme token reference
+ *
+ * Handles tokens in format: $category.key (e.g., $easing.smooth, $colors.primary)
+ * without the `theme.` prefix.
+ *
+ * @param category - Theme category (colors, easing, spacing, etc.)
+ * @param tokenName - Token key within category
+ * @param theme - Theme configuration
+ * @returns Resolved token value or original token string if not found
+ */
+function resolveShorthandToken(category: string, tokenName: string, theme?: Theme): string {
+  if (!theme) return `$${category}.${tokenName}`
+
+  const themeCategory = theme[category as keyof Theme]
+  if (!themeCategory || typeof themeCategory !== 'object') {
+    return `$${category}.${tokenName}`
+  }
+
+  // Handle nested animations category (easing, duration, keyframes)
+  if (category === 'easing' && theme.animations) {
+    const animations = theme.animations as Record<string, unknown>
+    const easingTokens = animations.easing as Record<string, unknown> | undefined
+    if (easingTokens && typeof easingTokens === 'object') {
+      const value = easingTokens[tokenName]
+      return value !== undefined ? String(value) : `$${category}.${tokenName}`
+    }
+  }
+
+  const value = (themeCategory as Record<string, unknown>)[tokenName]
+  return value !== undefined ? String(value) : `$${category}.${tokenName}`
+}
+
+/**
+ * Resolve shorthand theme tokens in string
+ *
+ * Replaces tokens in format: $category.key (e.g., $easing.smooth, $colors.primary)
+ * Supports multiple tokens in a single string.
+ *
+ * @param value - String that may contain shorthand theme tokens
+ * @param theme - Theme configuration
+ * @returns String with shorthand tokens replaced
+ *
+ * @example
+ * ```typescript
+ * const theme = {
+ *   colors: { primary: '#007bff' },
+ *   animations: { easing: { smooth: 'cubic-bezier(0.4, 0, 0.2, 1)' } }
+ * }
+ * resolveShorthandThemeTokens('colorPulse 2s $easing.smooth infinite', theme)
+ * // 'colorPulse 2s cubic-bezier(0.4, 0, 0.2, 1) infinite'
+ * ```
+ */
+function resolveShorthandThemeTokens(value: unknown, theme?: Theme): unknown {
+  if (typeof value !== 'string') {
+    return value
+  }
+
+  if (!theme || !value.includes('$')) {
+    return value
+  }
+
+  // Replace shorthand tokens: $category.key (without theme. prefix)
+  return value.replace(/\$(\w+)\.(\w+)/g, (_match, category, tokenName) =>
+    resolveShorthandToken(category, tokenName, theme)
+  )
+}
+
+/**
+ * Substitutes theme tokens in props recursively
+ *
+ * Walks through props object and replaces all theme token strings with actual theme values.
+ * Handles nested objects (e.g., style props) recursively.
+ * Supports both full syntax ($theme.colors.primary) and shorthand ($colors.primary, $easing.smooth).
+ *
+ * @param props - Component props that may contain theme tokens
+ * @param theme - Theme configuration
+ * @returns Props with theme tokens replaced
+ *
+ * @example
+ * ```typescript
+ * const theme = { colors: { primary: '#007bff', secondary: '#6c757d' } }
+ * const props = {
+ *   color: '$theme.colors.primary',
+ *   style: { backgroundColor: '$theme.colors.secondary' }
+ * }
+ * substitutePropsThemeTokens(props, theme)
+ * // {
+ * //   color: '#007bff',
+ * //   style: { backgroundColor: '#6c757d' }
+ * // }
+ * ```
+ */
+export function substitutePropsThemeTokens(
+  props: Record<string, unknown> | undefined,
+  theme?: Theme
+): Record<string, unknown> | undefined {
+  if (!props || !theme) {
+    return props
+  }
+
+  // Use functional Object.entries + reduce for immutable transformation
+  return Object.entries(props).reduce<Record<string, unknown>>((acc, [key, value]) => {
+    if (typeof value === 'string') {
+      // Apply both full syntax and shorthand token resolution
+      const fullSyntaxResolved = substituteThemeTokens(value, theme)
+      const shorthandResolved = resolveShorthandThemeTokens(fullSyntaxResolved, theme)
+      return { ...acc, [key]: shorthandResolved }
+    } else if (value && typeof value === 'object' && !Array.isArray(value)) {
+      // Recursively handle nested objects (like style props)
+      return { ...acc, [key]: substitutePropsThemeTokens(value as Record<string, unknown>, theme) }
+    } else {
+      return { ...acc, [key]: value }
+    }
+  }, {})
+}