sovrium 0.0.2

package/src/presentation/ui/sections/responsive/responsive-props-merger.ts

@@ -0,0 +1,195 @@
+/**
+ * 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 { applyResponsiveOverrides, buildResponsiveClasses } from './responsive-resolver'
+import type { Responsive, VariantOverrides } from '@/domain/models/app/page/common/responsive'
+import type { Breakpoint } from '@/presentation/hooks/use-breakpoint'
+
+/**
+ * Result of merging responsive props
+ */
+export interface MergedResponsiveProps {
+  readonly mergedProps: Record<string, unknown> | undefined
+  readonly mergedChildren: ReadonlyArray<unknown> | undefined
+  readonly mergedContent: string | Record<string, unknown> | undefined
+  readonly visibilityClasses: string | undefined
+}
+
+/**
+ * Configuration for merging responsive props
+ */
+export interface MergeResponsivePropsConfig {
+  readonly responsive: Responsive | undefined
+  readonly componentProps: Record<string, unknown> | undefined
+  readonly children: ReadonlyArray<unknown> | undefined
+  readonly content: string | Record<string, unknown> | undefined
+  readonly currentBreakpoint: Breakpoint
+}
+
+/**
+ * Remove className from props object
+ */
+function removeClassNameFromProps(
+  props: Record<string, unknown> | undefined
+): Record<string, unknown> | undefined {
+  if (!props) return undefined
+
+  return Object.entries(props)
+    .filter(([key]) => key !== 'className')
+    .reduce<Record<string, unknown>>((acc, [key, value]) => ({ ...acc, [key]: value }), {})
+}
+
+/**
+ * Check if responsive config has content overrides
+ */
+function hasContentOverrides(responsive: Responsive | undefined): boolean {
+  return responsive
+    ? Object.values(responsive).some(
+        (override) => (override as VariantOverrides).content !== undefined
+      )
+    : false
+}
+
+/**
+ * Check if responsive config has children overrides
+ */
+function hasChildrenOverrides(responsive: Responsive | undefined): boolean {
+  return responsive
+    ? Object.values(responsive).some(
+        (override) => (override as VariantOverrides).children !== undefined
+      )
+    : false
+}
+
+/**
+ * Build visibility classes from responsive configuration
+ */
+function buildVisibilityClasses(responsive: Responsive | undefined): string | undefined {
+  if (!responsive) return undefined
+
+  const visibilityConfig = (Object.entries(responsive) as [string, VariantOverrides][])
+    .filter(([, overrides]) => overrides.visible !== undefined)
+    .reduce<Record<string, boolean>>((acc, [bp, overrides]) => {
+      return { ...acc, [bp]: overrides.visible! }
+    }, {})
+
+  // For mobile:false + lg:true pattern, use max-lg:hidden
+  if (visibilityConfig.mobile === false && visibilityConfig.lg === true) {
+    return 'max-lg:hidden'
+  }
+
+  // For mobile:true + lg:false pattern, use lg:hidden
+  if (visibilityConfig.mobile === true && visibilityConfig.lg === false) {
+    return 'lg:hidden'
+  }
+
+  // Default fallback: build individual responsive classes
+  return Object.entries(visibilityConfig)
+    .map(([bp, isVisible]) => {
+      if (bp === 'mobile') {
+        return isVisible ? '' : 'max-sm:hidden'
+      }
+      return isVisible ? `${bp}:inline` : `${bp}:hidden`
+    })
+    .filter(Boolean)
+    .join(' ')
+}
+
+/**
+ * Merges responsive overrides with component props (config object signature)
+ */
+export function mergeResponsiveProps(config: MergeResponsivePropsConfig): MergedResponsiveProps
+
+/**
+ * Merges responsive overrides with component props (individual parameters signature)
+ */
+// eslint-disable-next-line max-params -- Function overload signature
+export function mergeResponsiveProps(
+  responsive: Responsive | undefined,
+  componentProps: Record<string, unknown> | undefined,
+  children: ReadonlyArray<unknown> | undefined,
+  content: string | Record<string, unknown> | undefined,
+  currentBreakpoint: Breakpoint
+): MergedResponsiveProps
+
+/**
+ * Implementation
+ */
+// eslint-disable-next-line max-params, max-lines-per-function, complexity -- Implementation handles both signatures
+export function mergeResponsiveProps(
+  configOrResponsive: MergeResponsivePropsConfig | Responsive | undefined,
+  componentProps?: Record<string, unknown>,
+  children?: ReadonlyArray<unknown>,
+  content?: string | Record<string, unknown>,
+  currentBreakpoint?: Breakpoint
+): MergedResponsiveProps {
+  // Support both config object and individual parameters
+  const config: MergeResponsivePropsConfig =
+    configOrResponsive &&
+    typeof configOrResponsive === 'object' &&
+    'responsive' in configOrResponsive
+      ? configOrResponsive
+      : {
+          responsive: configOrResponsive as Responsive | undefined,
+          componentProps: componentProps!,
+          children: children!,
+          content: content!,
+          currentBreakpoint: currentBreakpoint!,
+        }
+
+  const {
+    responsive,
+    componentProps: props,
+    children: childrenProp,
+    content: contentProp,
+    currentBreakpoint: breakpoint,
+  } = config
+
+  // Apply responsive overrides for current breakpoint (used for SSR initial render)
+  const responsiveOverrides = applyResponsiveOverrides(responsive, breakpoint)
+
+  // Build CSS-based responsive classes (works without JavaScript via Tailwind media queries)
+  const baseClassName = props?.className as string | undefined
+  const responsiveClassName = buildResponsiveClasses(responsive, baseClassName)
+
+  // Merge responsive overrides with base component values
+  // For className, use CSS-based responsive classes instead of JS-based overrides
+  const mergedPropsWithoutClassName = removeClassNameFromProps(
+    responsiveOverrides?.props ? { ...props, ...responsiveOverrides.props } : props
+  )
+
+  const mergedProps: Record<string, unknown> | undefined = responsiveClassName
+    ? { ...mergedPropsWithoutClassName, className: responsiveClassName }
+    : mergedPropsWithoutClassName
+
+  const mergedChildren = responsiveOverrides?.children ?? childrenProp
+  const mergedContent = responsiveOverrides?.content ?? contentProp
+
+  // Build CSS classes for responsive visibility using Tailwind breakpoint utilities
+  // This works without JavaScript by using CSS media queries
+  // Skip visibility classes when content/children overrides exist (handled by variant builders)
+  const shouldBuildVisibility =
+    responsive && !hasContentOverrides(responsive) && !hasChildrenOverrides(responsive)
+
+  const visibilityClasses = shouldBuildVisibility ? buildVisibilityClasses(responsive) : undefined
+
+  const mergedPropsWithVisibility = visibilityClasses
+    ? {
+        ...mergedProps,
+        className: mergedProps?.className
+          ? `${mergedProps.className} ${visibilityClasses}`
+          : visibilityClasses,
+      }
+    : mergedProps
+
+  return {
+    mergedProps: mergedPropsWithVisibility,
+    mergedChildren,
+    mergedContent,
+    visibilityClasses,
+  }
+}

package/src/presentation/ui/sections/responsive/responsive-resolver.ts

@@ -0,0 +1,213 @@
+/**
+ * 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 { Responsive, VariantOverrides } from '@/domain/models/app/page/common/responsive'
+import type { Breakpoint } from '@/presentation/hooks/use-breakpoint'
+
+/**
+ * Breakpoint order for progressive enhancement (mobile-first)
+ * Shared constant used across all responsive rendering logic
+ */
+export const BREAKPOINT_ORDER: readonly Breakpoint[] = [
+  'mobile',
+  'sm',
+  'md',
+  'lg',
+  'xl',
+  '2xl',
+] as const
+
+/**
+ * Map breakpoints to Tailwind responsive prefixes
+ */
+const BREAKPOINT_PREFIX: Record<Breakpoint, string> = {
+  mobile: '', // Mobile is base (no prefix)
+  sm: 'sm:',
+  md: 'md:',
+  lg: 'lg:',
+  xl: 'xl:',
+  '2xl': '2xl:',
+} as const
+
+/**
+ * Gets active breakpoints up to and including current breakpoint
+ *
+ * @param currentBreakpoint - Current viewport breakpoint
+ * @returns Array of active breakpoints in order
+ */
+function getActiveBreakpoints(currentBreakpoint: Breakpoint): readonly Breakpoint[] {
+  const currentIndex = BREAKPOINT_ORDER.indexOf(currentBreakpoint)
+  return BREAKPOINT_ORDER.slice(0, currentIndex + 1)
+}
+
+/**
+ * Merges className strings
+ *
+ * Override replaces base (no concatenation)
+ *
+ * @param base - Base className
+ * @param override - Override className
+ * @returns Override className if present, else base
+ */
+function mergeClassNames(
+  base: string | undefined,
+  override: string | undefined
+): string | undefined {
+  return override ?? base
+}
+
+/**
+ * Props value type from VariantOverrides
+ */
+type PropsValue = string | number | boolean | readonly unknown[] | { readonly [x: string]: unknown }
+
+/**
+ * Props record type from VariantOverrides
+ */
+type PropsRecord = { readonly [x: string]: PropsValue }
+
+/**
+ * Merges props objects, handling className specially
+ *
+ * @param base - Base props
+ * @param override - Override props
+ * @returns Merged props
+ */
+function mergeProps(
+  base: PropsRecord | undefined,
+  override: PropsRecord | undefined
+): PropsRecord | undefined {
+  if (!base && !override) return undefined
+  if (!base) return override
+  if (!override) return base
+
+  // Use reduce for functional approach
+  const overrideEntries = Object.entries(override).reduce<Record<string, PropsValue>>(
+    (acc, [key, value]) => {
+      if (key === 'className') {
+        const mergedClassName = mergeClassNames(
+          base.className as string | undefined,
+          value as string
+        )
+        return mergedClassName !== undefined ? { ...acc, className: mergedClassName } : acc
+      }
+      return { ...acc, [key]: value }
+    },
+    {}
+  )
+
+  return { ...base, ...overrideEntries }
+}
+
+/**
+ * Applies responsive overrides for current breakpoint
+ *
+ * Uses mobile-first approach: applies base values, then progressively
+ * overrides with larger breakpoint values up to current breakpoint.
+ *
+ * @param responsive - Responsive configuration
+ * @param currentBreakpoint - Current viewport breakpoint
+ * @returns Merged overrides for current breakpoint
+ */
+export function applyResponsiveOverrides(
+  responsive: Responsive | undefined,
+  currentBreakpoint: Breakpoint
+): VariantOverrides | undefined {
+  if (!responsive) return undefined
+
+  const activeBreakpoints = getActiveBreakpoints(currentBreakpoint)
+
+  // Use reduce for functional approach
+  const result = activeBreakpoints.reduce<VariantOverrides>((acc, bp) => {
+    const overrides = responsive[bp]
+    if (!overrides) return acc
+
+    // Build updated object functionally without let/mutations
+    const withProps = overrides.props
+      ? { ...acc, props: mergeProps(acc.props, overrides.props) }
+      : acc
+
+    const withContent =
+      overrides.content !== undefined ? { ...withProps, content: overrides.content } : withProps
+
+    const withVisible =
+      overrides.visible !== undefined ? { ...withContent, visible: overrides.visible } : withContent
+
+    const withChildren =
+      overrides.children !== undefined
+        ? { ...withVisible, children: overrides.children }
+        : withVisible
+
+    return withChildren
+  }, {})
+
+  return Object.keys(result).length > 0 ? result : undefined
+}
+
+/**
+ * Builds responsive CSS classes from responsive configuration
+ *
+ * Converts responsive className overrides into Tailwind responsive prefixes.
+ * Uses mobile-first approach: base className from props, then breakpoint-prefixed overrides.
+ *
+ * @example
+ * ```typescript
+ * buildResponsiveClasses(
+ *   {
+ *     mobile: { props: { className: 'text-sm' } },
+ *     md: { props: { className: 'p-8 max-w-4xl' } }
+ *   },
+ *   'p-4'  // Base className from props
+ * )
+ * // Returns: 'text-sm md:p-8 md:max-w-4xl'
+ * // Note: mobile override replaces base, md classes prefixed
+ * ```
+ *
+ * @param responsive - Responsive configuration
+ * @param baseClassName - Base className from component props
+ * @returns Combined CSS classes with responsive prefixes
+ */
+export function buildResponsiveClasses(
+  responsive: Responsive | undefined,
+  baseClassName: string | undefined
+): string | undefined {
+  if (!responsive) return baseClassName
+
+  // Extract className from each breakpoint's props
+  const classNamesByBreakpoint = BREAKPOINT_ORDER.reduce<Record<string, string>>((acc, bp) => {
+    const overrides = responsive[bp]
+    const className = overrides?.props?.className as string | undefined
+    return className ? { ...acc, [bp]: className } : acc
+  }, {})
+
+  // If no responsive classNames, return base
+  if (Object.keys(classNamesByBreakpoint).length === 0) return baseClassName
+
+  // Determine base classes (mobile override takes precedence over props.className)
+  const mobileClassName = classNamesByBreakpoint.mobile
+  const effectiveBase = mobileClassName ?? baseClassName
+
+  // Build responsive classes for breakpoints larger than mobile
+  const responsiveClasses = BREAKPOINT_ORDER.filter((bp) => bp !== 'mobile')
+    .map((bp) => {
+      const className = classNamesByBreakpoint[bp]
+      if (!className) return undefined
+
+      const prefix = BREAKPOINT_PREFIX[bp]
+      // Prefix each class with breakpoint
+      return className
+        .split(' ')
+        .filter(Boolean)
+        .map((cls) => `${prefix}${cls}`)
+        .join(' ')
+    })
+    .filter(Boolean)
+    .join(' ')
+
+  // Combine base with responsive classes
+  return [effectiveBase, responsiveClasses].filter(Boolean).join(' ').trim() || undefined
+}

package/src/presentation/ui/sections/styling/animation-composer-wrapper.ts

@@ -0,0 +1,65 @@
+/**
+ * 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 { composeAnimation } from '@/presentation/styling/animation-composer'
+import type { Component } from '@/domain/models/app/page/sections'
+import type { Theme } from '@/domain/models/app/theme'
+
+/**
+ * Apply all component-specific animations functionally using composition
+ * Compose fadeOut animation for toast components
+ * Compose scaleUp animation for card components with scroll trigger
+ * Compose float animation for fab components (continuous floating effect)
+ */
+export function applyComponentAnimations(
+  type: Component['type'],
+  baseStyle: Record<string, unknown> | undefined,
+  theme?: Theme
+): Record<string, unknown> | undefined {
+  const styleWithFadeOut =
+    type === 'toast'
+      ? composeAnimation({
+          baseStyle,
+          animationName: 'fadeOut',
+          theme,
+          defaultDuration: '300ms',
+          defaultEasing: 'ease-out',
+        })
+      : baseStyle
+
+  const styleWithScaleUp =
+    type === 'card'
+      ? composeAnimation({
+          baseStyle: styleWithFadeOut,
+          animationName: 'scaleUp',
+          theme,
+          defaultDuration: '500ms',
+          defaultEasing: 'cubic-bezier(0.34, 1.56, 0.64, 1)',
+          options: {
+            animationPlayState: 'paused',
+            animationFillMode: 'forwards',
+            opacity: 0,
+          },
+        })
+      : styleWithFadeOut
+
+  const finalStyle =
+    type === 'fab'
+      ? composeAnimation({
+          baseStyle: styleWithScaleUp,
+          animationName: 'float',
+          theme,
+          defaultDuration: '3s',
+          defaultEasing: 'ease-in-out',
+          options: {
+            infinite: true,
+          },
+        })
+      : styleWithScaleUp
+
+  return finalStyle
+}

package/src/presentation/ui/sections/styling/class-builders.ts

@@ -0,0 +1,45 @@
+/**
+ * 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.
+ */
+
+/**
+ * Build flex-specific classes based on props
+ */
+export function buildFlexClasses(props?: Record<string, unknown>): string {
+  const baseClasses = ['flex']
+  const alignmentClass =
+    props?.align === 'start'
+      ? 'items-start'
+      : props?.align === 'center'
+        ? 'items-center'
+        : props?.align === 'end'
+          ? 'items-end'
+          : undefined
+  const gapClass = typeof props?.gap === 'number' ? `gap-${props.gap}` : undefined
+
+  return [...baseClasses, alignmentClass, gapClass].filter(Boolean).join(' ')
+}
+
+/**
+ * Build grid-specific classes based on columns prop with responsive breakpoints
+ */
+export function buildGridClasses(props?: Record<string, unknown>): string | undefined {
+  const baseClasses = ['grid']
+
+  // Get base column count (default to 1 for mobile-first)
+  const baseColumns = typeof props?.columns === 'number' ? props.columns : 1
+  const baseClass = `grid-cols-${baseColumns}`
+
+  // Build responsive classes from responsive property
+  const responsive = props?.responsive as Record<string, unknown> | undefined
+  const mdColumns = typeof responsive?.md === 'number' ? responsive.md : undefined
+  const lgColumns = typeof responsive?.lg === 'number' ? responsive.lg : undefined
+
+  const mdClass = mdColumns ? `md:grid-cols-${mdColumns}` : undefined
+  const lgClass = lgColumns ? `lg:grid-cols-${lgColumns}` : undefined
+
+  return [...baseClasses, baseClass, mdClass, lgClass].filter(Boolean).join(' ')
+}

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

@@ -0,0 +1,43 @@
+/**
+ * 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'
+
+/**
+ * Component types and their corresponding theme color mapping
+ */
+const COMPONENT_COLOR_MAP: Record<string, keyof NonNullable<Theme['colors']>> = {
+  header: 'primary',
+  footer: 'secondary',
+  hero: 'background',
+}
+
+/**
+ * Apply theme colors to section elements automatically
+ *
+ * Maps component types to theme colors:
+ * - header → theme.colors.primary
+ * - footer → theme.colors.secondary
+ * - hero → theme.colors.background
+ *
+ * @param type - Component type
+ * @param theme - Theme configuration
+ * @returns Style object with background color or undefined
+ */
+export function getSectionColorStyle(
+  type: Component['type'],
+  theme?: Theme
+): Record<string, unknown> | undefined {
+  if (!theme?.colors) return undefined
+
+  const colorKey = COMPONENT_COLOR_MAP[type]
+  if (!colorKey) return undefined
+
+  const color = theme.colors[colorKey]
+  return color ? { backgroundColor: color } : undefined
+}

package/src/presentation/ui/sections/styling/hover-interaction-handler.ts

@@ -0,0 +1,107 @@
+/**
+ * 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 { HoverInteraction } from '@/domain/models/app/page/common/interactions/hover-interaction'
+
+/**
+ * Maps hover interaction properties to CSS property names
+ *
+ * @param hover - Hover interaction configuration
+ * @returns Array of CSS property names
+ */
+function getAnimatableProperties(hover: HoverInteraction): ReadonlyArray<string> {
+  return [
+    (hover.scale !== undefined || hover.transform) && 'transform',
+    hover.opacity !== undefined && 'opacity',
+    hover.backgroundColor && 'background-color',
+    hover.color && 'color',
+    hover.borderColor && 'border-color',
+    hover.shadow && 'box-shadow',
+  ].filter((prop): prop is string => Boolean(prop))
+}
+
+/**
+ * Build CSS transition styles for base element state
+ *
+ * Generates transition property for smooth hover animations.
+ * Applied to the base element to define which properties should animate.
+ * Uses explicit transition properties (transitionProperty, transitionDuration, transitionTimingFunction)
+ * in camelCase for React style objects.
+ *
+ * @param hover - Hover interaction configuration
+ * @returns Transition style object or undefined
+ */
+export function buildHoverTransitionStyles(
+  hover: HoverInteraction | undefined
+): Record<string, string> | undefined {
+  if (!hover) return undefined
+
+  const duration = hover.duration ?? '200ms'
+  const easing = hover.easing ?? 'ease-out'
+  const transitionProps = getAnimatableProperties(hover)
+
+  if (transitionProps.length === 0) return undefined
+
+  return {
+    transitionProperty: transitionProps.join(', '),
+    transitionDuration: duration,
+    transitionTimingFunction: easing,
+  }
+}
+
+/**
+ * Converts scale number to transform string
+ *
+ * @param scale - Scale factor (e.g., 1.05)
+ * @returns CSS transform string (e.g., 'scale(1.05)')
+ */
+function scaleToTransform(scale: number): string {
+  return `scale(${scale})`
+}
+
+/**
+ * Build hover effect data for component
+ *
+ * Returns data attributes and style tag content for hover interactions.
+ * Uses a unique identifier to scope hover styles to specific elements.
+ *
+ * @param hover - Hover interaction configuration
+ * @param uniqueId - Unique identifier for the element
+ * @returns Hover data object with attributes and styles
+ */
+export function buildHoverData(
+  hover: HoverInteraction | undefined,
+  uniqueId: string
+):
+  | {
+      readonly attributes: Record<string, string>
+      readonly styleContent: string
+    }
+  | undefined {
+  if (!hover) return undefined
+
+  // Convert scale to transform if present (scale takes priority over transform)
+  const transformValue = hover.scale !== undefined ? scaleToTransform(hover.scale) : hover.transform
+
+  // Build hover rules list (immutable)
+  // Use !important to override inline styles from props.style
+  const hoverRules = [
+    transformValue && `transform: ${transformValue} !important`,
+    hover.opacity !== undefined && `opacity: ${hover.opacity} !important`,
+    hover.backgroundColor && `background-color: ${hover.backgroundColor} !important`,
+    hover.color && `color: ${hover.color} !important`,
+    hover.borderColor && `border-color: ${hover.borderColor} !important`,
+    hover.shadow && `box-shadow: ${hover.shadow} !important`,
+  ].filter((rule): rule is string => Boolean(rule))
+
+  if (hoverRules.length === 0) return undefined
+
+  return {
+    attributes: { 'data-hover-id': uniqueId },
+    styleContent: `[data-hover-id="${uniqueId}"]:hover { ${hoverRules.join('; ')} }`,
+  }
+}

package/src/presentation/ui/sections/styling/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 component styling utilities
+// Files will be added during migration