sovrium 0.0.2

package/src/infrastructure/css/compiler.ts

@@ -0,0 +1,210 @@
+/**
+ * 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 tailwindcss from '@tailwindcss/postcss'
+import { Console, Effect } from 'effect'
+import postcss from 'postcss'
+import {
+  getOrComputeCachedCSS,
+  getThemeCacheKey,
+  type CompiledCSS,
+} from '@/infrastructure/css/cache/css-cache-service'
+import { generateAnimationStyles } from '@/infrastructure/css/styles/animation-styles-generator'
+import {
+  generateComponentsLayer,
+  generateUtilitiesLayer,
+} from '@/infrastructure/css/styles/component-layer-generators'
+import {
+  generateThemeBorderRadius,
+  generateThemeBreakpoints,
+  generateThemeColors,
+  generateThemeFonts,
+  generateThemeShadows,
+  generateThemeSpacing,
+} from '@/infrastructure/css/theme/theme-generators'
+import { generateBaseLayer } from '@/infrastructure/css/theme/theme-layer-generators'
+import { CSSCompilationError } from '@/infrastructure/errors/css-compilation-error'
+import { logDebug, logError } from '@/infrastructure/logging/logger'
+import type { App } from '@/domain/models/app'
+import type { Theme } from '@/domain/models/app/theme'
+
+// Re-export CompiledCSS type for external use
+export type { CompiledCSS } from '@/infrastructure/css/cache/css-cache-service'
+
+/**
+ * Generate complete Tailwind @theme CSS from app theme
+ */
+function generateThemeCSS(theme?: Theme): string {
+  if (!theme) return ''
+
+  const themeTokens = [
+    generateThemeColors(theme.colors),
+    generateThemeFonts(theme.fonts),
+    generateThemeSpacing(theme.spacing),
+    generateThemeShadows(theme.shadows),
+    generateThemeBorderRadius(theme.borderRadius),
+    generateThemeBreakpoints(theme.breakpoints),
+  ].filter(Boolean)
+
+  if (themeTokens.length === 0) return ''
+
+  return `@theme {\n${themeTokens.join('\n')}\n  }`
+}
+
+/**
+ * Static CSS imports and custom variants
+ */
+const STATIC_IMPORTS = `@import 'tailwindcss';
+    @import 'tw-animate-css';
+    /*---break---
+     */
+    @custom-variant dark (&:is(.dark *));`
+
+/**
+ * Final base layer for global resets
+ * Note: Removed hardcoded utilities (border-border, bg-background, etc.)
+ * These should be defined in the app theme if needed
+ */
+const FINAL_BASE_LAYER = ''
+
+/**
+ * Build dynamic SOURCE_CSS with theme tokens
+ * Generates Tailwind CSS with @theme directive based on app theme
+ */
+function buildSourceCSS(theme?: Theme): string {
+  const themeCSS = generateThemeCSS(theme)
+  const animationCSS = generateAnimationStyles(theme?.animations, theme)
+  const baseLayerCSS = generateBaseLayer(theme)
+  const componentsLayerCSS = generateComponentsLayer(theme)
+  const utilitiesLayerCSS = generateUtilitiesLayer()
+
+  return [
+    STATIC_IMPORTS,
+    baseLayerCSS,
+    componentsLayerCSS,
+    utilitiesLayerCSS,
+    '/*---break---\n     */',
+    themeCSS,
+    '/*---break---\n     */',
+    animationCSS,
+    '/*---break---\n     */',
+    FINAL_BASE_LAYER,
+  ]
+    .filter(Boolean)
+    .join('\n\n    ')
+}
+
+/**
+ * Internal CSS compilation logic (without caching)
+ * Generates and compiles Tailwind CSS from theme configuration
+ */
+const compileCSSInternal = (theme?: Theme): Effect.Effect<CompiledCSS, CSSCompilationError> =>
+  Effect.gen(function* () {
+    // Build SOURCE_CSS with theme
+    const sourceCSS = buildSourceCSS(theme)
+
+    // Diagnostic logging for CI debugging
+    yield* Console.log(`CSS Compiler - Source CSS length: ${sourceCSS.length} bytes`)
+    yield* Console.log(
+      `CSS Compiler - Contains @import 'tailwindcss': ${sourceCSS.includes("@import 'tailwindcss'")}`
+    )
+    yield* Console.log(
+      `CSS Compiler - Contains @import 'tw-animate-css': ${sourceCSS.includes("@import 'tw-animate-css'")}`
+    )
+
+    // Process CSS through PostCSS with Tailwind plugin
+    const result = yield* Effect.tryPromise({
+      try: async () => {
+        // Verify PostCSS and Tailwind plugin are available
+        if (!postcss || typeof postcss !== 'function') {
+          // eslint-disable-next-line unicorn/no-useless-promise-resolve-reject
+          return Promise.reject(new Error('PostCSS is not available'))
+        }
+        if (!tailwindcss || typeof tailwindcss !== 'function') {
+          // eslint-disable-next-line unicorn/no-useless-promise-resolve-reject
+          return Promise.reject(new Error('Tailwind CSS plugin is not available'))
+        }
+
+        // Cast needed: @tailwindcss/postcss bundles its own PostCSS types
+        // which are structurally identical but nominally different from top-level postcss
+        const processor = postcss([tailwindcss() as postcss.AcceptedPlugin])
+        return await processor.process(sourceCSS, {
+          from: process.cwd() + '/src/styles/global.css', // Source context for import resolution
+          to: undefined, // No output file (in-memory compilation)
+        })
+      },
+      catch: (error) => {
+        // Enhanced error logging for CI debugging
+        logError('CSS Compilation Error Details', error)
+        logDebug(`Error type: ${error instanceof Error ? error.constructor.name : typeof error}`)
+        logDebug(`Error message: ${error instanceof Error ? error.message : String(error)}`)
+        if (error instanceof Error && error.stack) {
+          logDebug(`Error stack: ${error.stack}`)
+        }
+        logDebug(`Source CSS preview (first 500 chars): ${sourceCSS.slice(0, 500)}`)
+
+        return new CSSCompilationError(error)
+      },
+    })
+
+    yield* Console.log('CSS compiled and cached')
+
+    // Create compiled CSS result
+    return {
+      css: result.css,
+      timestamp: Date.now(),
+    }
+  })
+
+/**
+ * Compiles Tailwind CSS using PostCSS with @tailwindcss/postcss plugin
+ *
+ * This function:
+ * 1. Extracts theme from app config (if provided)
+ * 2. Generates dynamic SOURCE_CSS with @theme tokens
+ * 3. Processes through PostCSS with Tailwind CSS v4 plugin
+ * 4. Returns the compiled CSS string
+ * 5. Caches the result in memory per theme (subsequent requests use cache)
+ *
+ * Uses getOrComputeCachedCSS for declarative caching with normalized theme keys.
+ * Same theme content always produces the same cache key regardless of property order.
+ *
+ * @param app - Optional app configuration containing theme
+ * @returns Effect that yields compiled CSS string or CSSCompilationError
+ *
+ * @example
+ * ```typescript
+ * // Without theme (minimal CSS)
+ * const program = Effect.gen(function* () {
+ *   const result = yield* compileCSS()
+ *   console.log(`Compiled ${result.css.length} bytes of CSS`)
+ * })
+ *
+ * // With app theme
+ * const programWithTheme = Effect.gen(function* () {
+ *   const result = yield* compileCSS(app)
+ *   console.log(`Compiled ${result.css.length} bytes of CSS with theme`)
+ * })
+ *
+ * Effect.runPromise(program)
+ * ```
+ */
+export const compileCSS = (app?: App): Effect.Effect<CompiledCSS, CSSCompilationError> =>
+  Effect.gen(function* () {
+    const theme = app?.theme
+    const cacheKey = getThemeCacheKey(theme)
+
+    // Use declarative cache helper with theme-based key
+    const result = yield* getOrComputeCachedCSS(cacheKey, compileCSSInternal(theme))
+
+    // Log cache status (hit if timestamp is old, compiled if fresh)
+    if (Date.now() - result.timestamp > 100) {
+      yield* Console.log('CSS cache hit')
+    }
+
+    return result
+  })

package/src/infrastructure/css/css-compiler-live.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 { Layer } from 'effect'
+import { CSSCompiler } from '@/application/ports/services/css-compiler'
+import { compileCSS } from '@/infrastructure/css/compiler'
+
+/**
+ * Live implementation of CSSCompiler using PostCSS and Tailwind
+ *
+ * This layer provides the production implementation of CSS compilation
+ * using the infrastructure's PostCSS-based compiler.
+ */
+export const CSSCompilerLive = Layer.succeed(CSSCompiler, {
+  compile: compileCSS,
+})

package/src/infrastructure/css/index.ts

@@ -0,0 +1,25 @@
+/**
+ * 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.
+ */
+
+/**
+ * CSS Infrastructure Module
+ *
+ * Provides CSS compilation utilities using Tailwind CSS via PostCSS.
+ * Compiles Tailwind CSS on-demand for development and production builds.
+ *
+ * @example
+ * ```typescript
+ * import { compileCSS } from '@/infrastructure/css'
+ *
+ * const program = Effect.gen(function* () {
+ *   const compiledCSS = yield* compileCSS()
+ *   return compiledCSS
+ * })
+ * ```
+ */
+
+export { compileCSS } from './compiler'

package/src/infrastructure/css/styles/animation-styles-generator.ts

@@ -0,0 +1,177 @@
+/**
+ * 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 { resolveTokenReference } from '@/infrastructure/css/theme/theme-token-resolver'
+import type { Theme } from '@/domain/models/app/theme'
+import type { AnimationConfigObject, AnimationsConfig } from '@/domain/models/app/theme/animations'
+
+/**
+ * Generate @keyframes CSS for a single animation
+ * Supports token references like $colors.primary
+ *
+ * @param name - Animation name
+ * @param keyframes - Keyframe steps definition
+ * @param theme - Optional theme for token resolution
+ * @returns CSS @keyframes rule as string
+ *
+ * @example
+ * generateKeyframes('fade-in', { '0%': { opacity: 0 }, '100%': { opacity: 1 } })
+ * // => '@keyframes fade-in {\n  0% { opacity: 0; }\n  100% { opacity: 1; }\n}'
+ */
+export function generateKeyframes(
+  name: string,
+  keyframes: Record<string, unknown>,
+  theme?: Theme
+): string {
+  const keyframeSteps = Object.entries(keyframes)
+    .map(([step, props]) => {
+      const propsStr =
+        typeof props === 'object' && props !== undefined
+          ? Object.entries(props as Record<string, unknown>)
+              .map(([prop, val]) => {
+                const resolvedValue = resolveTokenReference(val, theme)
+                return `${prop}: ${resolvedValue};`
+              })
+              .join(' ')
+          : ''
+      return `  ${step} { ${propsStr} }`
+    })
+    .join('\n')
+
+  return `@keyframes ${name} {\n${keyframeSteps}\n}`
+}
+
+/**
+ * Generate animation shorthand CSS
+ *
+ * @param name - Animation name
+ * @param duration - Optional duration (default: '300ms')
+ * @param easing - Optional easing function (default: 'ease')
+ * @param delay - Optional delay (default: '0ms')
+ * @returns CSS animation class as string
+ *
+ * @example
+ * generateAnimationClass('fade-in', '500ms', 'ease-in-out')
+ * // => '.animate-fade-in { animation: fade-in 500ms ease-in-out 0ms; }'
+ */
+export function generateAnimationClass(
+  name: string,
+  duration?: string,
+  easing?: string,
+  delay?: string
+): string {
+  const dur = duration || '300ms'
+  const ease = easing || 'ease'
+  const del = delay || '0ms'
+  return `.animate-${name} { animation: ${name} ${dur} ${ease} ${del}; }`
+}
+
+/**
+ * Check if animation name is a reserved design token property
+ *
+ * @param name - Property name to check
+ * @returns True if reserved, false otherwise
+ */
+export function isReservedAnimationProperty(name: string): boolean {
+  return name === 'duration' || name === 'easing' || name === 'keyframes'
+}
+
+/**
+ * Process animation config object
+ * Returns array of CSS strings (keyframes + optional animation class)
+ *
+ * @param name - Animation name
+ * @param animConfig - Animation configuration object
+ * @param theme - Optional theme for token resolution
+ * @returns Array of CSS rules (keyframes and optional animation class)
+ */
+export function processAnimationConfigObject(
+  name: string,
+  animConfig: AnimationConfigObject,
+  theme?: Theme
+): readonly string[] {
+  if (!animConfig.keyframes) return []
+
+  const keyframesCSS = generateKeyframes(name, animConfig.keyframes, theme)
+
+  if (animConfig.enabled === false) {
+    return [keyframesCSS]
+  }
+
+  const animationClass = generateAnimationClass(
+    name,
+    animConfig.duration,
+    animConfig.easing,
+    animConfig.delay
+  )
+
+  return [keyframesCSS, animationClass]
+}
+
+/**
+ * Process a single legacy animation config entry
+ * Returns array of CSS strings (keyframes + optional animation class)
+ *
+ * @param name - Animation name
+ * @param config - Animation configuration (can be boolean, string, or object)
+ * @param theme - Optional theme for token resolution
+ * @returns Array of CSS rules
+ */
+export function processLegacyAnimationEntry(
+  name: string,
+  config: unknown,
+  theme?: Theme
+): readonly string[] {
+  if (isReservedAnimationProperty(name)) return []
+  if (typeof config === 'boolean' && !config) return []
+  if (typeof config === 'string') return []
+  if (typeof config === 'object' && config !== undefined) {
+    return processAnimationConfigObject(name, config as AnimationConfigObject, theme)
+  }
+  return []
+}
+
+/**
+ * Generate @keyframes and animation CSS from domain animations config
+ * Supports both nested design tokens and legacy flat animations
+ *
+ * @param animations - Animations configuration from theme
+ * @param theme - Optional theme for token resolution
+ * @returns Complete animation CSS as string
+ *
+ * @example
+ * generateAnimationStyles(theme.animations, theme)
+ * // => '@keyframes fade-in { ... }\n.animate-fade-in { ... }'
+ */
+export function generateAnimationStyles(animations?: AnimationsConfig, theme?: Theme): string {
+  if (!animations || Object.keys(animations).length === 0) return ''
+
+  // Extract nested design tokens if present
+  const keyframesTokens = animations.keyframes as
+    | Record<string, Record<string, unknown>>
+    | undefined
+
+  // Generate keyframes from nested design tokens (immutable)
+  const nestedKeyframesCSS =
+    keyframesTokens && typeof keyframesTokens === 'object'
+      ? Object.entries(keyframesTokens).flatMap(([name, keyframes]) =>
+          keyframes && typeof keyframes === 'object'
+            ? [generateKeyframes(name, keyframes, theme)]
+            : []
+        )
+      : []
+
+  // Process legacy flat animations (backwards compatibility, immutable)
+  const legacyAnimationsCSS = Object.entries(animations).flatMap(([name, config]) =>
+    processLegacyAnimationEntry(name, config, theme)
+  )
+
+  // Combine all CSS (immutable)
+  const animationCSS: readonly string[] = [...nestedKeyframesCSS, ...legacyAnimationsCSS]
+
+  return animationCSS.join('\n')
+}

package/src/infrastructure/css/styles/click-animations.ts

@@ -0,0 +1,147 @@
+/**
+ * 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.
+ */
+
+/**
+ * Click interaction animations
+ *
+ * Provides CSS animations for click interactions (pulse, ripple, bounce, etc.)
+ * These animations are separate from entrance/exit animations provided by tw-animate-css
+ *
+ * Architecture: Infrastructure Layer (CSS generation)
+ * - Supports click interaction schema (animation: pulse, ripple, bounce, shake, flash, none)
+ * - Generates @keyframes and utility classes for click feedback
+ */
+
+/**
+ * Pulse animation CSS - subtle scale pulse
+ */
+const PULSE_ANIMATION_CSS = `
+@keyframes pulse {
+  0%, 100% {
+    transform: scale(1);
+    opacity: 1;
+  }
+  50% {
+    transform: scale(1.05);
+    opacity: 0.9;
+  }
+}
+
+.animate-pulse {
+  animation: pulse 300ms ease-in-out;
+}`
+
+/**
+ * Bounce animation CSS - playful bounce effect
+ */
+const BOUNCE_ANIMATION_CSS = `
+@keyframes bounce {
+  0%, 100% {
+    transform: translateY(0);
+  }
+  25% {
+    transform: translateY(-8px);
+  }
+  50% {
+    transform: translateY(-4px);
+  }
+  75% {
+    transform: translateY(-2px);
+  }
+}
+
+.animate-bounce {
+  animation: bounce 300ms ease-out;
+}`
+
+/**
+ * Shake animation CSS - horizontal shake
+ */
+const SHAKE_ANIMATION_CSS = `
+@keyframes shake {
+  0%, 100% {
+    transform: translateX(0);
+  }
+  10%, 30%, 50%, 70%, 90% {
+    transform: translateX(-4px);
+  }
+  20%, 40%, 60%, 80% {
+    transform: translateX(4px);
+  }
+}
+
+.animate-shake {
+  animation: shake 300ms ease-in-out;
+}`
+
+/**
+ * Flash animation CSS - quick opacity flash
+ */
+const FLASH_ANIMATION_CSS = `
+@keyframes flash {
+  0%, 100% {
+    opacity: 1;
+  }
+  25%, 75% {
+    opacity: 0.4;
+  }
+  50% {
+    opacity: 1;
+  }
+}
+
+.animate-flash {
+  animation: flash 300ms ease-in-out;
+}`
+
+/**
+ * Ripple animation CSS - Material Design ripple
+ */
+const RIPPLE_ANIMATION_CSS = `
+@keyframes ripple {
+  0% {
+    transform: scale(0);
+    opacity: 1;
+  }
+  100% {
+    transform: scale(4);
+    opacity: 0;
+  }
+}
+
+.animate-ripple {
+  position: relative;
+  overflow: hidden;
+}
+
+.animate-ripple::after {
+  content: '';
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 100px;
+  height: 100px;
+  background: rgba(255, 255, 255, 0.5);
+  border-radius: 50%;
+  transform: translate(-50%, -50%) scale(0);
+  animation: ripple 600ms ease-out;
+}`
+
+/**
+ * Generate CSS for click interaction animations
+ *
+ * Returns CSS string with @keyframes and .animate-* utility classes
+ * for all click interaction animation types
+ */
+export function generateClickAnimationCSS(): string {
+  return `/* Click interaction animations */
+${PULSE_ANIMATION_CSS}
+${BOUNCE_ANIMATION_CSS}
+${SHAKE_ANIMATION_CSS}
+${FLASH_ANIMATION_CSS}
+${RIPPLE_ANIMATION_CSS}`
+}