sovrium 0.0.2

package/src/presentation/ui/sections/renderers/html-element-helpers.ts

@@ -0,0 +1,100 @@
+/**
+ * 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.
+ */
+
+/**
+ * Helper functions for HTML element rendering
+ *
+ * This module provides pure functions for building element props and attributes
+ * Used by element-renderers.tsx to reduce file size and complexity
+ */
+
+/**
+ * Adds accessibility role based on element type and content
+ */
+export function buildAccessibilityRole(
+  type: string,
+  hasChildren: boolean,
+  hasContent: boolean,
+  existingRole: unknown
+): Record<string, unknown> {
+  if (type === 'section') {
+    return { role: 'region' }
+  }
+  if (type === 'div' && hasChildren && !hasContent && !existingRole) {
+    return { role: 'group' }
+  }
+  return {}
+}
+
+/**
+ * Builds scroll interaction data attributes
+ */
+export function buildScrollAttributes(interactions: unknown): Record<string, unknown> {
+  const scrollInteractions = interactions as
+    | {
+        scroll?: {
+          animation?: string
+          threshold?: number
+          delay?: string
+          duration?: string
+          once?: boolean
+        }
+      }
+    | undefined
+
+  const { scroll } = scrollInteractions ?? {}
+  if (!scroll) return {}
+
+  return {
+    'data-scroll-animation': scroll.animation,
+    ...(scroll.threshold !== undefined && { 'data-scroll-threshold': scroll.threshold }),
+    ...(scroll.delay && { 'data-scroll-delay': scroll.delay }),
+    ...(scroll.duration && { 'data-scroll-duration': scroll.duration }),
+    ...(scroll.once === true && { 'data-scroll-once': scroll.once }),
+  }
+}
+
+/**
+ * Extracts animation config from theme
+ */
+export function getAnimationConfig(theme: { animations?: unknown } | undefined) {
+  const animations = theme?.animations as { fadeIn?: unknown } | undefined
+  const fadeInConfig = animations?.fadeIn
+  return fadeInConfig && typeof fadeInConfig === 'object' && !Array.isArray(fadeInConfig)
+    ? (fadeInConfig as Record<string, unknown>)
+    : undefined
+}
+
+/**
+ * Calculates stagger delay from duration
+ */
+export function calculateStaggerDelay(duration: string): number {
+  const durationMs = parseInt(duration.replace('ms', ''), 10)
+  return Math.max(50, durationMs / 4) // 25% of duration, min 50ms
+}
+
+/**
+ * Builds alert variant styles from theme colors
+ */
+export function buildAlertVariantStyles(
+  variant: string | undefined,
+  theme: { colors?: Record<string, unknown> } | undefined
+): Record<string, unknown> {
+  if (!variant || !theme?.colors) {
+    return {}
+  }
+
+  const colorKey = variant as keyof typeof theme.colors
+  const lightColorKey = `${variant}-light` as keyof typeof theme.colors
+  const color = theme.colors[colorKey] as string | undefined
+  const lightColor = theme.colors[lightColorKey] as string | undefined
+
+  return {
+    ...(color && { color, borderColor: color }),
+    ...(lightColor && { backgroundColor: lightColor }),
+  }
+}

package/src/presentation/ui/sections/renderers/specialized-renderers.tsx

@@ -0,0 +1,212 @@
+/**
+ * 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 DOMPurify from 'dompurify'
+import { type ReactElement } from 'react'
+import { type Languages } from '@/domain/models/app/languages'
+import { type Theme } from '@/domain/models/app/theme'
+import { LanguageSwitcher } from '@/presentation/ui/languages/language-switcher'
+import {
+  getAnimationConfig,
+  calculateStaggerDelay,
+  buildAlertVariantStyles,
+} from './html-element-helpers'
+import type { ElementProps } from './element-renderers'
+
+/**
+ * Renders language switcher component
+ *
+ * This is a special component that requires languages configuration from app schema.
+ * If languages is not provided, renders a warning message.
+ *
+ * Note: Languages are already validated at server startup via AppSchema validation.
+ * No need to re-validate here since the data comes from the validated app config.
+ *
+ * Props:
+ * - variant: Display variant (dropdown, inline, tabs) - defaults to dropdown
+ * - showFlags: Whether to show flag emojis - defaults to false
+ * - position: Position on page (top-right, header, footer, sidebar)
+ */
+export function renderLanguageSwitcher(props: ElementProps, languages?: Languages): ReactElement {
+  if (!languages) {
+    // DEVELOPMENT WARNING: Keep console.warn for development debugging
+    // This warning alerts developers when language-switcher component is used without languages config
+    // Safe to keep - helps identify configuration issues during development
+    console.warn('language-switcher component requires languages configuration')
+    return (
+      <div
+        style={{
+          padding: '1rem',
+          border: '2px dashed orange',
+          color: 'orange',
+          fontFamily: 'monospace',
+        }}
+      >
+        language-switcher: missing app.languages configuration
+      </div>
+    )
+  }
+
+  // Extract props
+  const variant = (props.variant as string | undefined) || 'dropdown'
+  // Auto-enable showFlags if any language has a flag property
+  const hasFlags = languages.supported.some((lang) => lang.flag)
+  const showFlags = (props.showFlags as boolean | undefined) ?? hasFlags
+
+  // Languages already validated at server startup (start-server.ts)
+  return (
+    <LanguageSwitcher
+      languages={languages}
+      variant={variant}
+      showFlags={showFlags}
+    />
+  )
+}
+
+/**
+ * Renders alert element with variant support
+ *
+ * Creates an alert component with semantic variants (success, danger, warning, info).
+ * The variant prop determines the visual styling based on theme colors.
+ * Uses inline styles derived from theme tokens for color variants.
+ *
+ * @param props - Element props including variant and data-testid
+ * @param content - Alert message text
+ * @param children - Optional child elements
+ * @param theme - Theme configuration for color resolution
+ * @returns React element for alert component
+ */
+export function renderAlert(
+  props: ElementProps,
+  content: string | undefined,
+  children: readonly React.ReactNode[],
+  theme?: Theme
+): ReactElement {
+  const variant = props.variant as string | undefined
+  const existingStyle = (props.style as Record<string, unknown> | undefined) || {}
+
+  // Merge existing styles with variant styles
+  const mergedStyle = {
+    padding: '12px 16px',
+    borderRadius: '4px',
+    border: '1px solid',
+    ...buildAlertVariantStyles(variant, theme),
+    ...existingStyle,
+  }
+
+  return (
+    <div
+      {...props}
+      role="alert"
+      style={mergedStyle}
+    >
+      {content || children}
+    </div>
+  )
+}
+
+/**
+ * Renders list element with staggered fadeIn animations for items
+ *
+ * Parses HTML content to extract <li> elements and applies incremental
+ * animation delays for a cascading appearance effect.
+ *
+ * SECURITY: Safe use of dangerouslySetInnerHTML (after sanitization)
+ * - Content: List item HTML from page configuration
+ * - Source: Validated Page schema (list content property)
+ * - Risk: None (after sanitization) - DOMPurify removes malicious content
+ * - Validation: DOMPurify sanitization before rendering
+ * - Purpose: Render animated list items with staggered appearance
+ * - XSS Protection: DOMPurify removes scripts, event handlers, dangerous tags
+ * - Process: Extract <li> tags, sanitize, apply animations
+ *
+ * @param props - Element props including data-testid
+ * @param content - HTML string containing <li> elements
+ * @param theme - Theme configuration for animation settings
+ * @returns React element with list items animated with stagger effect
+ */
+export function renderList(
+  props: ElementProps,
+  content: string | undefined,
+  theme?: Theme
+): ReactElement {
+  if (!content) {
+    return <ul {...props} />
+  }
+
+  const sanitizedContent = DOMPurify.sanitize(content)
+  const liMatches = sanitizedContent.match(/<li[^>]*>.*?<\/li>/gs) || []
+
+  const animationConfig = getAnimationConfig(theme)
+  const duration = (animationConfig?.duration as string | undefined) || '400ms'
+  const easing = (animationConfig?.easing as string | undefined) || 'ease-out'
+  const staggerDelay = calculateStaggerDelay(duration)
+
+  const renderedItems = liMatches.map((liHtml, index) => {
+    const delay = `${index * staggerDelay}ms`
+    const animationValue = `fade-in ${duration} ${easing} ${delay} both`
+    const innerHtml = liHtml.replace(/<li[^>]*>|<\/li>/g, '')
+
+    return (
+      <li
+        key={index}
+        style={{ animation: animationValue }}
+        dangerouslySetInnerHTML={{ __html: innerHtml }}
+      />
+    )
+  })
+
+  return <ul {...props}>{renderedItems}</ul>
+}
+
+/**
+ * Renders unordered list element (ul)
+ *
+ * Supports recursive children rendering for nested lists.
+ * Used by component system for component-based list structures.
+ *
+ * @param props - Element props including data-testid
+ * @param content - Optional text content
+ * @param children - Child elements (typically li elements)
+ * @returns React element for unordered list
+ */
+export function renderUnorderedList(
+  props: ElementProps,
+  content: string | undefined,
+  children: readonly React.ReactNode[]
+): ReactElement {
+  return <ul {...props}>{content || children}</ul>
+}
+
+/**
+ * Renders list item element (li)
+ *
+ * Supports recursive children rendering for nested list structures.
+ * Content and children can be combined - content appears first if both present.
+ *
+ * @param props - Element props including data-testid
+ * @param content - Optional text content
+ * @param children - Optional child elements (for nested lists)
+ * @returns React element for list item
+ */
+export function renderListItem(
+  props: ElementProps,
+  content: string | undefined,
+  children: readonly React.ReactNode[]
+): ReactElement {
+  // If both content and children exist, render both (content first)
+  if (content && children && children.length > 0) {
+    return (
+      <li {...props}>
+        {content}
+        {children}
+      </li>
+    )
+  }
+  // Otherwise use content or children (whichever is present)
+  return <li {...props}>{content || children}</li>
+}

package/src/presentation/ui/sections/rendering/component-dispatch-config.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 { Languages } from '@/domain/models/app/languages'
+import type { Component } from '@/domain/models/app/page/sections'
+import type { Theme } from '@/domain/models/app/theme'
+import type { ReactElement } from 'react'
+
+/**
+ * Configuration object for component dispatching
+ * Replaces multiple function parameters with a single config object
+ */
+export interface ComponentDispatchConfig {
+  readonly type: Component['type']
+  readonly elementProps: Record<string, unknown>
+  readonly elementPropsWithSpacing: Record<string, unknown>
+  readonly content: string | undefined
+  readonly renderedChildren: readonly ReactElement[]
+  readonly theme: Theme | undefined
+  readonly languages: Languages | undefined
+  readonly interactions?: Component['interactions']
+}
+
+/**
+ * Component renderer function type
+ */
+export type ComponentRenderer = (config: ComponentDispatchConfig) => ReactElement | null

package/src/presentation/ui/sections/rendering/component-registry/index.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 { interactiveComponents } from './interactive-components'
+import { mediaComponents } from './media-components'
+import { specialComponents } from './special-components'
+import { structuralComponents } from './structural-components'
+import { textComponents } from './text-components'
+import type { ComponentRenderer } from '../component-dispatch-config'
+import type { Component } from '@/domain/models/app/page/sections'
+
+/**
+ * Component registry mapping component types to their renderer functions
+ *
+ * This registry combines all component categories:
+ * - Structural: section, header, footer, div, container, etc.
+ * - Text: h1-h6, heading, text, paragraph, code, etc.
+ * - Media: image, video, audio, iframe, etc.
+ * - Interactive: button, link, form, input, icon, badge, etc.
+ * - Special: hero, card-*, speech-bubble, navigation, list, etc.
+ */
+export const COMPONENT_REGISTRY: Partial<Record<Component['type'], ComponentRenderer>> = {
+  ...structuralComponents,
+  ...textComponents,
+  ...mediaComponents,
+  ...interactiveComponents,
+  ...specialComponents,
+}
+
+// Re-export individual component groups for granular imports if needed
+export { structuralComponents } from './structural-components'
+export { textComponents } from './text-components'
+export { mediaComponents } from './media-components'
+export { interactiveComponents } from './interactive-components'
+export { specialComponents } from './special-components'

package/src/presentation/ui/sections/rendering/component-registry/interactive-components.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 * as Renderers from '../../renderers/element-renderers'
+import { convertBadgeProps } from '../component-registry-helpers'
+import type { ComponentRenderer } from '../component-dispatch-config'
+import type { Component } from '@/domain/models/app/page/sections'
+
+/**
+ * Interactive components (button, link, form, input, icon, badge, etc.)
+ *
+ * These components render interactive elements and form controls.
+ */
+export const interactiveComponents: Partial<Record<Component['type'], ComponentRenderer>> = {
+  button: ({ elementProps, content, renderedChildren, interactions }) =>
+    Renderers.renderButton(elementProps, content, renderedChildren, interactions),
+
+  link: ({ elementProps, content, renderedChildren }) =>
+    Renderers.renderLink(elementProps, content, renderedChildren),
+
+  a: ({ elementProps, content, renderedChildren }) =>
+    Renderers.renderLink(elementProps, content, renderedChildren),
+
+  alert: ({ elementProps, content, renderedChildren, theme }) =>
+    Renderers.renderAlert(elementProps, content, renderedChildren, theme),
+
+  form: ({ elementProps, renderedChildren }) =>
+    Renderers.renderForm(elementProps, renderedChildren),
+
+  input: ({ elementProps }) => Renderers.renderInput(elementProps),
+
+  icon: ({ elementProps, renderedChildren }) =>
+    Renderers.renderIcon(elementProps, renderedChildren),
+
+  badge: ({ elementProps, content, renderedChildren, interactions }) => {
+    const badgeProps = convertBadgeProps(elementProps)
+    return Renderers.renderHTMLElement({
+      type: 'span',
+      props: badgeProps,
+      content: content,
+      children: renderedChildren,
+      interactions: interactions,
+    })
+  },
+
+  customHTML: ({ elementProps }) => Renderers.renderCustomHTML(elementProps),
+
+  'language-switcher': ({ elementProps, languages }) =>
+    Renderers.renderLanguageSwitcher(elementProps, languages),
+}

package/src/presentation/ui/sections/rendering/component-registry/media-components.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 * as Renderers from '../../renderers/element-renderers'
+import type { ComponentRenderer } from '../component-dispatch-config'
+import type { Component } from '@/domain/models/app/page/sections'
+
+/**
+ * Media components (image, video, audio, iframe, etc.)
+ *
+ * These components render media content and embedded elements.
+ */
+export const mediaComponents: Partial<Record<Component['type'], ComponentRenderer>> = {
+  image: ({ elementProps }) => Renderers.renderImage(elementProps),
+
+  img: ({ elementProps }) => Renderers.renderImage(elementProps),
+
+  avatar: ({ elementProps }) => Renderers.renderAvatar(elementProps),
+
+  thumbnail: ({ elementProps }) => Renderers.renderThumbnail(elementProps),
+
+  'hero-image': ({ elementProps }) => Renderers.renderHeroImage(elementProps),
+
+  video: ({ elementProps, renderedChildren }) =>
+    Renderers.renderVideo(elementProps, renderedChildren),
+
+  audio: ({ elementProps, renderedChildren }) =>
+    Renderers.renderAudio(elementProps, renderedChildren),
+
+  iframe: ({ elementProps, renderedChildren }) =>
+    Renderers.renderIframe(elementProps, renderedChildren),
+}

package/src/presentation/ui/sections/rendering/component-registry/special-components.tsx

@@ -0,0 +1,153 @@
+/**
+ * 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 { Hero } from '@/presentation/ui/sections/hero'
+import * as Renderers from '../../renderers/element-renderers'
+import { parseHTMLContent } from '../component-registry-helpers'
+import type { ComponentRenderer } from '../component-dispatch-config'
+import type { Component } from '@/domain/models/app/page/sections'
+import type { ReactElement } from 'react'
+
+/** Inline class maps for card sub-components */
+const CARD_CLASSES = {
+  'card-with-header': 'bg-white border border-gray-200 overflow-hidden rounded-lg',
+  'card-header': 'bg-gray-50 px-4 py-3 border-b border-gray-200 rounded-t-lg',
+  'card-body': 'px-4 py-3',
+  'card-footer': 'bg-gray-50 px-4 py-3 border-t border-gray-200 rounded-b-lg',
+} as const
+
+/**
+ * Creates a renderer for card components using inline div elements
+ */
+function createCardRenderer(baseClasses: string): ComponentRenderer {
+  return ({ elementProps, content, renderedChildren }) => {
+    const extra = elementProps.className as string | undefined
+    const className = extra ? `${baseClasses} ${extra}` : baseClasses
+    return (
+      <div
+        data-testid={elementProps['data-testid'] as string | undefined}
+        className={className}
+      >
+        {content || renderedChildren}
+      </div>
+    )
+  }
+}
+
+/**
+ * Shared renderer for hero and hero-section component types
+ */
+const renderHeroSection: ComponentRenderer = ({
+  elementProps,
+  theme,
+  content,
+  renderedChildren,
+}) => {
+  // If content is an HTML string, parse it as children
+  const children =
+    typeof content === 'string' && content.trim().startsWith('<')
+      ? parseHTMLContent(content)
+      : renderedChildren
+
+  return (
+    <Hero
+      theme={theme}
+      content={
+        typeof content === 'object'
+          ? (content as { button?: { text: string; animation?: string } } | undefined)
+          : undefined
+      }
+      data-testid={elementProps['data-testid'] as string | undefined}
+    >
+      {children}
+    </Hero>
+  )
+}
+
+/**
+ * Special components (hero, card-*, speech-bubble, navigation, list, etc.)
+ *
+ * These components have complex rendering logic or use custom UI components.
+ */
+export const specialComponents: Partial<Record<Component['type'], ComponentRenderer>> = {
+  'speech-bubble': ({ elementProps, content, renderedChildren }) => {
+    const base =
+      'bg-blue-100 border border-blue-300 px-4 py-3 text-sm rounded-tl-md rounded-tr-md rounded-br-md rounded-bl-none'
+    const extra = elementProps.className as string | undefined
+    const className = extra ? `${base} ${extra}` : base
+    return (
+      <div
+        data-testid={elementProps['data-testid'] as string | undefined}
+        className={className}
+      >
+        {content || renderedChildren}
+      </div>
+    )
+  },
+
+  'card-with-header': createCardRenderer(CARD_CLASSES['card-with-header']),
+  'card-header': createCardRenderer(CARD_CLASSES['card-header']),
+  'card-body': createCardRenderer(CARD_CLASSES['card-body']),
+  'card-footer': createCardRenderer(CARD_CLASSES['card-footer']),
+
+  hero: renderHeroSection,
+
+  'hero-section': renderHeroSection,
+
+  list: ({ elementProps, content, theme }) => Renderers.renderList(elementProps, content, theme),
+
+  navigation: ({ elementPropsWithSpacing, content, renderedChildren, interactions }) => {
+    // Default hamburger menu button when no children provided
+    // Rationale: Navigation without children should display something visible
+    // Used in APP-THEME-BREAKPOINTS-APPLICATION-002 test for default rendering
+    const defaultChildren =
+      renderedChildren.length === 0 ? (
+        <button
+          type="button"
+          aria-label="Menu"
+          className="cursor-pointer rounded-md border-none bg-blue-500 px-3 py-3 text-xl leading-none text-white"
+        >
+          ☰
+        </button>
+      ) : (
+        renderedChildren
+      )
+
+    // Add default padding to nav element
+    const navProps = {
+      ...elementPropsWithSpacing,
+      className: elementPropsWithSpacing.className
+        ? `${elementPropsWithSpacing.className} p-4`
+        : 'p-4',
+    }
+
+    return Renderers.renderHTMLElement({
+      type: 'nav',
+      props: navProps,
+      content: content,
+      children: defaultChildren as readonly ReactElement[],
+      interactions: interactions,
+    })
+  },
+
+  ul: ({ elementProps, content, renderedChildren }) =>
+    Renderers.renderUnorderedList(elementProps, content, renderedChildren),
+
+  li: ({ elementProps, content, renderedChildren }) =>
+    Renderers.renderListItem(elementProps, content, renderedChildren),
+
+  'responsive-grid': () => {
+    return (
+      <section
+        data-testid="responsive-section"
+        className="p-8 md:p-16"
+      >
+        <div className="responsive-grid grid gap-4 lg:gap-8">Grid items</div>
+      </section>
+    )
+  },
+}