sovrium 0.0.2

package/src/presentation/ui/sections/renderers/element-renderers/html-element-renderer.tsx

@@ -0,0 +1,124 @@
+/**
+ * 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 ReactElement } from 'react'
+import { buildAccessibilityRole, buildScrollAttributes } from '../html-element-helpers'
+
+/**
+ * Common props for all rendered elements
+ */
+export interface ElementProps {
+  readonly [key: string]: unknown
+  readonly className?: string
+  readonly 'data-component'?: string
+}
+
+/**
+ * Configuration for renderHTMLElement
+ */
+export type HTMLElementConfig = {
+  readonly type:
+    | 'div'
+    | 'span'
+    | 'section'
+    | 'header'
+    | 'footer'
+    | 'main'
+    | 'article'
+    | 'aside'
+    | 'nav'
+  readonly props: ElementProps
+  readonly content: string | undefined
+  readonly children: readonly React.ReactNode[]
+  readonly interactions?: unknown
+}
+
+/**
+ * Renders HTML structural elements (div, span, section, and HTML5 semantic elements)
+ *
+ * If content starts with '<', it's treated as HTML and rendered via dangerouslySetInnerHTML.
+ * Otherwise, content is rendered as plain text.
+ *
+ * SECURITY NOTE - Trusted Schema Content:
+ * HTML content is rendered without sanitization since it comes from trusted
+ * schema configuration. For user-generated content, use renderCustomHTML instead.
+ *
+ * SECURITY: Safe use of dangerouslySetInnerHTML
+ * - Content: Schema-defined HTML from page configuration
+ * - Source: Validated Page schema (section.content property)
+ * - Risk: Low - content is from server configuration, not user input
+ * - Validation: Content validated at build/runtime via schema
+ * - Purpose: Render rich HTML content in structural elements
+ * - XSS Protection: Use renderCustomHTML with DOMPurify for user-generated content
+ * - Condition: Only used when content starts with '<' character
+ *
+ * For section elements, automatically adds role="region" for accessibility best practices,
+ * ensuring sections are properly identified in the accessibility tree.
+ *
+ * Supports scroll interactions via data attributes for IntersectionObserver.
+ */
+export function renderHTMLElement(config: HTMLElementConfig): ReactElement {
+  const { type, props, content, children, interactions } = config
+  const Element = type
+
+  // Build element props immutably
+  const accessibilityRole = buildAccessibilityRole(type, children.length > 0, !!content, props.role)
+  const scrollAttributes = buildScrollAttributes(interactions)
+  const elementProps = { ...props, ...accessibilityRole, ...scrollAttributes }
+
+  // If content looks like HTML (starts with '<'), render as HTML
+  // This is safe for schema-defined content but should NOT be used for user input
+  if (content?.trim().startsWith('<')) {
+    return (
+      <Element
+        {...elementProps}
+        dangerouslySetInnerHTML={{ __html: content }}
+      />
+    )
+  }
+
+  return <Element {...elementProps}>{content || children}</Element>
+}
+
+/**
+ * Renders heading elements (h1-h6)
+ */
+export function renderHeading(
+  level: 1 | 2 | 3 | 4 | 5 | 6,
+  props: ElementProps,
+  content: string | undefined,
+  children: readonly React.ReactNode[]
+): ReactElement {
+  const HeadingTag = `h${level}` as 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
+  return <HeadingTag {...props}>{content || children}</HeadingTag>
+}
+
+/**
+ * Renders text element with dynamic level
+ *
+ * The text element supports a 'level' prop to determine the HTML tag.
+ * If level is h1-h6, renders as heading.
+ * If level is p, renders as paragraph.
+ * If level is label, renders as label.
+ * Otherwise renders as span to ensure proper ARIA generic role.
+ */
+export function renderTextElement(props: ElementProps, content: string | undefined): ReactElement {
+  const { level } = props
+
+  if (level === 'h1') return <h1 {...props}>{content}</h1>
+  if (level === 'h2') return <h2 {...props}>{content}</h2>
+  if (level === 'h3') return <h3 {...props}>{content}</h3>
+  if (level === 'h4') return <h4 {...props}>{content}</h4>
+  if (level === 'h5') return <h5 {...props}>{content}</h5>
+  if (level === 'h6') return <h6 {...props}>{content}</h6>
+  if (level === 'p') return <p {...props}>{content}</p>
+  if (level === 'label') return <label {...props}>{content}</label>
+
+  // Default to span for inline text to ensure proper ARIA generic role
+  // span elements with text content maintain generic role in ARIA tree
+  return <span {...props}>{content}</span>
+}

package/src/presentation/ui/sections/renderers/element-renderers/index.ts

@@ -0,0 +1,59 @@
+/**
+ * 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.
+ */
+
+/**
+ * Element renderers barrel export
+ *
+ * This module exports all element renderer functions organized by category:
+ * - HTML element renderers (structural elements, headings, text)
+ * - Text content renderers (paragraph, code, pre)
+ * - Media renderers (image, video, audio, iframe)
+ * - Interactive renderers (button, link, form, input, icon)
+ * - Specialized renderers (alert, list, language-switcher)
+ */
+
+// HTML element renderers
+export {
+  renderHTMLElement,
+  renderHeading,
+  renderTextElement,
+  type ElementProps,
+  type HTMLElementConfig,
+} from './html-element-renderer'
+
+// Text content renderers
+export { renderParagraph, renderCode, renderPre } from './text-content-renderers'
+
+// Media renderers
+export {
+  renderImage,
+  renderAvatar,
+  renderThumbnail,
+  renderHeroImage,
+  renderVideo,
+  renderAudio,
+  renderIframe,
+} from './media-renderers'
+
+// Interactive renderers
+export {
+  renderButton,
+  renderLink,
+  renderForm,
+  renderInput,
+  renderIcon,
+  renderCustomHTML,
+} from './interactive-renderers'
+
+// Re-export specialized renderers for backward compatibility
+export {
+  renderLanguageSwitcher,
+  renderAlert,
+  renderList,
+  renderUnorderedList,
+  renderListItem,
+} from '../specialized-renderers'

package/src/presentation/ui/sections/renderers/element-renderers/interactive-renderers.tsx

@@ -0,0 +1,231 @@
+/**
+ * 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 * as LucideIcons from 'lucide-react'
+import { type ReactElement } from 'react'
+import type { ElementProps } from './html-element-renderer'
+
+/**
+ * Build data attributes for click interactions
+ */
+function buildClickDataAttributes(clickInteraction: {
+  animation?: string
+  navigate?: string
+  openUrl?: string
+  openInNewTab?: boolean
+  scrollTo?: string
+  toggleElement?: string
+  submitForm?: string
+}): Record<string, string> {
+  return {
+    ...(clickInteraction.animation && { 'data-click-animation': clickInteraction.animation }),
+    ...(clickInteraction.navigate && { 'data-click-navigate': clickInteraction.navigate }),
+    ...(clickInteraction.openUrl && { 'data-click-open-url': clickInteraction.openUrl }),
+    ...(clickInteraction.openInNewTab !== undefined && {
+      'data-click-open-in-new-tab': String(clickInteraction.openInNewTab),
+    }),
+    ...(clickInteraction.scrollTo && { 'data-click-scroll-to': clickInteraction.scrollTo }),
+    ...(clickInteraction.toggleElement && {
+      'data-click-toggle-element': clickInteraction.toggleElement,
+    }),
+    ...(clickInteraction.submitForm && {
+      'data-click-submit-form': clickInteraction.submitForm,
+    }),
+  }
+}
+
+/**
+ * Renders button element with click interactions
+ */
+export function renderButton(
+  props: ElementProps,
+  content: string | undefined,
+  children: readonly React.ReactNode[],
+  interactions?: unknown
+): ReactElement {
+  const interactionsTyped = interactions as
+    | {
+        click?: {
+          animation?: string
+          navigate?: string
+          openUrl?: string
+          openInNewTab?: boolean
+          scrollTo?: string
+          toggleElement?: string
+          submitForm?: string
+        }
+      }
+    | undefined
+  const clickInteraction = interactionsTyped?.click
+
+  // Store interaction data in data attributes for client-side JavaScript handler
+  const buttonProps = clickInteraction
+    ? { ...props, ...buildClickDataAttributes(clickInteraction) }
+    : props
+
+  return <button {...buttonProps}>{content || children}</button>
+}
+
+/**
+ * Renders link (anchor) element
+ */
+export function renderLink(
+  props: ElementProps,
+  content: string | undefined,
+  children: readonly React.ReactNode[]
+): ReactElement {
+  return <a {...props}>{content || children}</a>
+}
+
+/**
+ * Renders form element
+ */
+export function renderForm(
+  props: ElementProps,
+  children: readonly React.ReactNode[]
+): ReactElement {
+  return <form {...props}>{children}</form>
+}
+
+/**
+ * Renders input element
+ */
+export function renderInput(props: ElementProps): ReactElement {
+  return <input {...props} />
+}
+
+/**
+ * Converts a kebab-case icon name to PascalCase for Lucide lookup
+ * Example: 'check-circle' -> 'CheckCircle', 'arrow-right' -> 'ArrowRight'
+ */
+function kebabToPascalCase(name: string): string {
+  return name
+    .split('-')
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join('')
+}
+
+/**
+ * Resolves a Lucide icon component by kebab-case name.
+ * Returns undefined if no matching component is found.
+ *
+ * Lucide icons use forwardRef, so they are objects (typeof === 'object') in the Bun runtime,
+ * not plain functions. We treat both as valid React components.
+ */
+function resolveLucideIcon(
+  iconName: string | undefined
+): React.ComponentType<Record<string, unknown>> | undefined {
+  if (!iconName) return undefined
+  const component = (LucideIcons as Record<string, unknown>)[kebabToPascalCase(iconName)]
+  // Accept both function components and forwardRef objects (which are typeof 'object')
+  if (typeof component === 'function')
+    return component as React.ComponentType<Record<string, unknown>>
+  if (typeof component === 'object' && component !== null)
+    return component as React.ComponentType<Record<string, unknown>>
+  return undefined
+}
+
+/**
+ * Renders icon using Lucide React icons
+ *
+ * Props extracted from elementProps:
+ * - name: kebab-case Lucide icon name (e.g. 'check-circle', 'arrow-right')
+ * - color: SVG stroke color (default: 'currentColor')
+ * - size: SVG width/height in pixels (default: 24)
+ * - strokeWidth: SVG stroke-width (default: 2)
+ * - ariaLabel: accessible label; if provided, sets role="img" instead of aria-hidden
+ * - className: CSS classes forwarded to the SVG
+ *
+ * Falls back to an empty SVG with data-testid for unknown icon names.
+ */
+export function renderIcon(
+  props: ElementProps,
+  _children: readonly React.ReactNode[]
+): ReactElement {
+  const iconName = props.name as string | undefined
+  const iconColor = props.color as string | undefined
+  const iconSize = props.size as number | undefined
+  const iconStrokeWidth = props.strokeWidth as number | undefined
+  const ariaLabel = props.ariaLabel as string | undefined
+
+  // Build props to forward to the SVG — strip out icon-specific props and their data-* conversions
+  const {
+    name: _name,
+    color: _color,
+    size: _size,
+    strokeWidth: _strokeWidth,
+    ariaLabel: _ariaLabel,
+    'data-color': _dataColor,
+    'data-size': _dataSize,
+    'data-stroke-width': _dataStrokeWidth,
+    'data-aria-label': _dataAriaLabel,
+    ...restProps
+  } = props as Record<string, unknown>
+
+  const testId = iconName ? `icon-${iconName}` : 'icon'
+  const colorProps = iconColor !== undefined ? { 'data-color': iconColor } : {}
+  const a11yProps = ariaLabel
+    ? { role: 'img' as const, 'aria-label': ariaLabel }
+    : { 'aria-hidden': 'true' as const }
+
+  const LucideIcon = resolveLucideIcon(iconName)
+
+  if (LucideIcon) {
+    return (
+      <LucideIcon
+        {...restProps}
+        {...a11yProps}
+        {...colorProps}
+        size={iconSize ?? 24}
+        color={iconColor ?? 'currentColor'}
+        strokeWidth={iconStrokeWidth ?? 2}
+        data-testid={testId}
+      />
+    ) as ReactElement
+  }
+
+  // Fallback: render empty SVG placeholder for unknown icons
+  return (
+    <svg
+      {...(restProps as React.SVGProps<SVGSVGElement>)}
+      {...a11yProps}
+      {...colorProps}
+      data-testid={testId}
+      xmlns="http://www.w3.org/2000/svg"
+      width={iconSize ?? 24}
+      height={iconSize ?? 24}
+    />
+  )
+}
+
+/**
+ * Renders custom HTML with DOMPurify sanitization
+ *
+ * SECURITY: This function sanitizes HTML to prevent XSS attacks.
+ * DOMPurify removes malicious scripts, event handlers, and dangerous attributes.
+ * Critical for user-generated content or external HTML sources.
+ *
+ * SECURITY: Safe use of dangerouslySetInnerHTML (after sanitization)
+ * - Content: User-provided or external HTML (props.html)
+ * - Source: Potentially untrusted - user input or external sources
+ * - Risk: None (after sanitization) - XSS prevented by DOMPurify
+ * - Validation: DOMPurify removes all malicious content
+ * - Purpose: Render custom HTML blocks safely
+ * - XSS Protection: DOMPurify sanitization removes scripts, event handlers, dangerous tags
+ * - Best Practice: This is the ONLY way to render user-generated HTML safely
+ */
+export function renderCustomHTML(props: ElementProps): ReactElement {
+  const sanitizedHTML = DOMPurify.sanitize((props.html as string | undefined) || '')
+  return (
+    <div
+      {...props}
+      // Safe to use dangerouslySetInnerHTML after DOMPurify sanitization
+      dangerouslySetInnerHTML={{ __html: sanitizedHTML }}
+    />
+  )
+}

package/src/presentation/ui/sections/renderers/element-renderers/media-renderers.tsx

@@ -0,0 +1,102 @@
+/**
+ * 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 ReactElement } from 'react'
+import type { ElementProps } from './html-element-renderer'
+
+/**
+ * Renders image element
+ */
+export function renderImage(props: ElementProps): ReactElement {
+  return (
+    <img
+      {...props}
+      alt={(props.alt as string | undefined) || ''}
+    />
+  )
+}
+
+/**
+ * Renders avatar image with circular border-radius
+ * Includes default dimensions to ensure visibility even when image fails to load
+ */
+export function renderAvatar(props: ElementProps): ReactElement {
+  const style = {
+    ...((props.style as Record<string, unknown> | undefined) || {}),
+    minWidth: '48px',
+    minHeight: '48px',
+    width: '48px',
+    height: '48px',
+  }
+
+  return (
+    <img
+      {...props}
+      style={style}
+      alt={(props.alt as string | undefined) || ''}
+      className={[props.className, 'rounded-full'].filter(Boolean).join(' ')}
+    />
+  )
+}
+
+/**
+ * Renders thumbnail image with moderate border-radius
+ * Applies md radius (0.375rem) for soft corners while preserving aspect ratio
+ */
+export function renderThumbnail(props: ElementProps): ReactElement {
+  return (
+    <img
+      {...props}
+      alt={(props.alt as string | undefined) || ''}
+      className={[props.className, 'rounded-md'].filter(Boolean).join(' ')}
+    />
+  )
+}
+
+/**
+ * Renders hero image with top-only border-radius
+ * Applies lg radius to top corners only for integration with card layout
+ */
+export function renderHeroImage(props: ElementProps): ReactElement {
+  return (
+    <img
+      {...props}
+      alt={(props.alt as string | undefined) || ''}
+      className={[props.className, 'rounded-t-lg'].filter(Boolean).join(' ')}
+    />
+  )
+}
+
+/**
+ * Renders video element
+ */
+export function renderVideo(
+  props: ElementProps,
+  children: readonly React.ReactNode[]
+): ReactElement {
+  return <video {...props}>{children}</video>
+}
+
+/**
+ * Renders audio element
+ */
+export function renderAudio(
+  props: ElementProps,
+  children: readonly React.ReactNode[]
+): ReactElement {
+  return <audio {...props}>{children}</audio>
+}
+
+/**
+ * Renders iframe element
+ */
+export function renderIframe(
+  props: ElementProps,
+  children: readonly React.ReactNode[]
+): ReactElement {
+  return <iframe {...props}>{children}</iframe>
+}

package/src/presentation/ui/sections/renderers/element-renderers/text-content-renderers.tsx

@@ -0,0 +1,42 @@
+/**
+ * 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 ReactElement } from 'react'
+import type { ElementProps } from './html-element-renderer'
+
+/**
+ * Renders paragraph element
+ */
+export function renderParagraph(
+  props: ElementProps,
+  content: string | undefined,
+  children: readonly React.ReactNode[]
+): ReactElement {
+  return <p {...props}>{content || children}</p>
+}
+
+/**
+ * Renders code element (inline code)
+ */
+export function renderCode(
+  props: ElementProps,
+  content: string | undefined,
+  children: readonly React.ReactNode[]
+): ReactElement {
+  return <code {...props}>{content || children}</code>
+}
+
+/**
+ * Renders pre element (preformatted text block)
+ */
+export function renderPre(
+  props: ElementProps,
+  content: string | undefined,
+  children: readonly React.ReactNode[]
+): ReactElement {
+  return <pre {...props}>{content || children}</pre>
+}

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

@@ -0,0 +1,53 @@
+/**
+ * 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.
+ */
+
+/**
+ * Re-export from element-renderers directory
+ *
+ * This file maintains backward compatibility with existing imports.
+ * The actual implementation has been split into:
+ * - html-element-renderer.tsx (renderHTMLElement, renderHeading, renderTextElement)
+ * - text-content-renderers.tsx (renderParagraph, renderCode, renderPre)
+ * - media-renderers.tsx (renderImage, renderVideo, renderAudio, etc.)
+ * - interactive-renderers.tsx (renderButton, renderLink, renderForm, etc.)
+ *
+ * @see src/presentation/ui/sections/renderers/element-renderers/
+ */
+export {
+  // Types
+  type ElementProps,
+  type HTMLElementConfig,
+  // HTML element renderers
+  renderHTMLElement,
+  renderHeading,
+  renderTextElement,
+  // Text content renderers
+  renderParagraph,
+  renderCode,
+  renderPre,
+  // Media renderers
+  renderImage,
+  renderAvatar,
+  renderThumbnail,
+  renderHeroImage,
+  renderVideo,
+  renderAudio,
+  renderIframe,
+  // Interactive renderers
+  renderButton,
+  renderLink,
+  renderForm,
+  renderInput,
+  renderIcon,
+  renderCustomHTML,
+  // Specialized renderers
+  renderLanguageSwitcher,
+  renderAlert,
+  renderList,
+  renderUnorderedList,
+  renderListItem,
+} from './element-renderers/'