sovrium 0.0.2

package/src/presentation/styling/theme-colors.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.
+ */
+
+/**
+ * Default theme color palette
+ *
+ * Provides a minimal set of predefined theme colors for quick prototyping.
+ * These colors are used when a component references a color by name (e.g., color="orange")
+ * but no theme configuration is provided in the schema.
+ *
+ * NOTE: This is a simplified implementation. In a full theme system, colors should
+ * come from the app's theme configuration (src/domain/models/app/theme/colors.ts).
+ * Future enhancement: Integrate with theme context to support custom colors.
+ *
+ * @see src/domain/models/app/theme/colors.ts - For proper theme color configuration
+ * @see src/presentation/ui/sections/utils/theme-tokens.ts - For theme token substitution
+ */
+export const DEFAULT_THEME_COLORS = {
+  orange: '#F97316',
+  blue: '#3B82F6',
+  green: '#10B981',
+  red: '#EF4444',
+} as const
+
+/**
+ * Supported theme color names
+ *
+ * Type-safe color names that can be used in components.
+ */
+export type ThemeColorName = keyof typeof DEFAULT_THEME_COLORS
+
+/**
+ * Resolves a color name to its hex value
+ *
+ * @param color - Color name from DEFAULT_THEME_COLORS
+ * @returns Hex color value, or undefined if color not found
+ *
+ * @example
+ * ```typescript
+ * resolveThemeColor('orange') // '#F97316'
+ * resolveThemeColor('invalid') // undefined
+ * ```
+ */
+export function resolveThemeColor(color: string | undefined): string | undefined {
+  if (!color) {
+    return undefined
+  }
+  return DEFAULT_THEME_COLORS[color as ThemeColorName]
+}

package/src/presentation/translations/component-utils.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 type {
+  ComponentReference,
+  SimpleComponentReference,
+} from '@/domain/models/app/component/common/component-reference'
+import type { Component } from '@/domain/models/app/page/sections'
+
+/**
+ * Get component information for a section
+ *
+ * Determines if a section is a component reference and calculates its instance index
+ * when multiple instances of the same component exist.
+ *
+ * @param section - Section to analyze (Component, SimpleComponentReference, or ComponentReference)
+ * @param index - Position of this section in the sections array
+ * @param sections - Complete array of sections for counting occurrences
+ * @returns Component info with name and optional instanceIndex, or undefined if not a component reference
+ */
+export function getComponentInfo(
+  section: Component | SimpleComponentReference | ComponentReference,
+  index: number,
+  sections: ReadonlyArray<Component | SimpleComponentReference | ComponentReference>
+): { name: string; instanceIndex?: number } | undefined {
+  if (!('component' in section || '$ref' in section)) {
+    return undefined
+  }
+
+  const componentName = 'component' in section ? section.component : section.$ref
+
+  // Count total occurrences of this component name in all sections
+  const totalOccurrences = sections.filter((s) => {
+    const sName = 'component' in s ? s.component : '$ref' in s ? s.$ref : undefined
+    return sName === componentName
+  }).length
+
+  // Only set instanceIndex if there are multiple instances
+  if (totalOccurrences <= 1) {
+    return { name: componentName }
+  }
+
+  // Count previous occurrences of the same component name
+  const previousOccurrences = sections.slice(0, index).filter((s) => {
+    const sName = 'component' in s ? s.component : '$ref' in s ? s.$ref : undefined
+    return sName === componentName
+  })
+
+  return { name: componentName, instanceIndex: previousOccurrences.length }
+}

package/src/presentation/translations/index.ts

@@ -0,0 +1,16 @@
+/**
+ * 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.
+ */
+
+// Component utilities
+export { getComponentInfo } from './component-utils'
+
+// Translation resolution
+export {
+  resolveTranslation,
+  resolveTranslationPattern,
+  collectTranslationsForKey,
+} from './translation-resolver'

package/src/presentation/translations/translation-resolver.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 translation resolver functions from domain layer
+ *
+ * These pure functions were moved to the domain layer to respect layer boundaries.
+ * This file re-exports them for backward compatibility with existing presentation
+ * layer code. Application layer code should import directly from domain.
+ *
+ * @see src/domain/utils/translation-resolver.ts for implementation
+ */
+export {
+  normalizeLanguageCode,
+  resolveTranslation,
+  resolveTranslationPattern,
+  collectTranslationsForKey,
+} from '@/domain/utils/translation-resolver'

package/src/presentation/ui/languages/language-switcher.tsx

@@ -0,0 +1,119 @@
+/**
+ * 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 { Languages } from '@/domain/models/app/languages'
+
+/**
+ * Helper to check if flag is an image path (starts with /)
+ */
+const isImageFlag = (flag: string | undefined): boolean => Boolean(flag?.startsWith('/'))
+
+/**
+ * Helper to determine if flag should be shown (emoji flags only, not image paths)
+ */
+const shouldShowFlag = (flag: string | undefined): boolean => Boolean(flag && !isImageFlag(flag))
+
+/**
+ * Language switcher button component
+ */
+function LanguageSwitcherButton({
+  defaultLanguage,
+  defaultCode,
+}: {
+  readonly defaultLanguage: Languages['supported'][number] | undefined
+  readonly defaultCode: string
+}): ReactElement {
+  return (
+    <button
+      data-testid="language-switcher-button"
+      type="button"
+    >
+      {shouldShowFlag(defaultLanguage?.flag) && (
+        <span data-testid="language-flag">{defaultLanguage!.flag} </span>
+      )}
+      <span
+        data-testid="language-code"
+        aria-hidden="true"
+        style={{ display: 'none' }}
+      />
+      <span
+        data-testid="current-language"
+        data-code={defaultCode}
+      >
+        {defaultLanguage?.label || defaultCode}
+      </span>
+    </button>
+  )
+}
+
+/**
+ * LanguageSwitcher component - Server-side rendered language switcher
+ *
+ * This component renders the static HTML structure for the language switcher.
+ * All client-side interactivity (click handlers, language detection, localStorage)
+ * is handled by the vanilla JavaScript file: language-switcher.js
+ *
+ * Architecture:
+ * - React component = SSR only (renders HTML structure)
+ * - Vanilla JS = Client-side progressive enhancement (handles interactivity)
+ *
+ * This separation ensures:
+ * - No duplicate logic between React and vanilla JS
+ * - Works without React hydration (pure progressive enhancement)
+ * - Clear separation of concerns (SSR vs client-side)
+ *
+ * @param props - Component props
+ * @param props.languages - Languages configuration from AppSchema
+ * @param props.variant - Display variant (dropdown, inline, tabs) - defaults to dropdown
+ * @param props.showFlags - Whether to show flag emojis - defaults to false
+ * @returns React element with language switcher HTML structure
+ */
+export function LanguageSwitcher({
+  languages,
+  variant = 'dropdown',
+  showFlags = false,
+}: {
+  readonly languages: Languages
+  readonly variant?: string
+  readonly showFlags?: boolean
+}): Readonly<ReactElement> {
+  const defaultLanguage = languages.supported.find((lang) => lang.code === languages.default)
+
+  return (
+    <div
+      data-testid="language-switcher"
+      className="relative"
+      data-variant={variant}
+    >
+      <LanguageSwitcherButton
+        defaultLanguage={defaultLanguage}
+        defaultCode={languages.default}
+      />
+
+      {/* Dropdown menu - vanilla JS will handle show/hide */}
+      <div
+        data-language-dropdown
+        className="absolute top-full left-0 z-10"
+        aria-hidden="true"
+        style={{ display: 'none' }}
+        data-supported-languages={JSON.stringify(languages.supported)}
+        data-show-flags={showFlags}
+      />
+
+      {/* Fallback indicator - shows when fallback is configured */}
+      {languages.fallback && (
+        <div
+          data-testid="fallback-handled"
+          aria-label={`Fallback language: ${languages.fallback}`}
+        >
+          Fallback: {languages.fallback}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/presentation/ui/metadata/analytics-builders.tsx

@@ -0,0 +1,174 @@
+/**
+ * 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 { renderScriptTag } from '@/presentation/scripts/script-renderers'
+import type { Analytics } from '@/domain/models/app/page/meta/analytics'
+
+/**
+ * Build DNS prefetch link for analytics provider
+ */
+export function buildDnsPrefetchLink(
+  provider: Analytics['providers'][number],
+  providerIndex: number,
+  hidden: boolean
+): ReactElement | undefined {
+  if (!provider.dnsPrefetch) return undefined
+
+  const styleAttr = hidden ? { style: { display: 'none' } } : {}
+
+  return (
+    <link
+      key={`dns-${providerIndex}`}
+      rel="dns-prefetch"
+      href={provider.dnsPrefetch}
+      {...styleAttr}
+    />
+  )
+}
+
+/**
+ * Build external scripts for analytics provider
+ */
+export function buildExternalScripts(
+  provider: Analytics['providers'][number],
+  providerIndex: number,
+  hidden: boolean
+): readonly ReactElement[] {
+  if (!provider.scripts || provider.scripts.length === 0) return []
+
+  return provider.scripts.map((script, scriptIndex) =>
+    renderScriptTag({
+      src: script.src,
+      async: script.async,
+      defer: script.defer,
+      dataTestId: `analytics-${provider.name}`,
+      reactKey: `script-${providerIndex}-${scriptIndex}`,
+      hidden,
+    })
+  )
+}
+
+/**
+ * Build initialization script for analytics provider
+ *
+ * SECURITY: Safe use of dangerouslySetInnerHTML
+ * - Content: Analytics provider initialization code from configuration
+ * - Source: Validated Analytics schema (page.meta.analytics.providers[].initScript)
+ * - Risk: Low - content is from server configuration, not user input
+ * - Validation: Schema validation ensures string type
+ * - Purpose: Execute analytics provider setup (e.g., Google Analytics, Plausible)
+ * - CSP: Inline script - consider using nonce for stricter CSP
+ * - Best Practice: Use external scripts with SRI when possible
+ */
+export function buildInitScript(
+  provider: Analytics['providers'][number],
+  providerIndex: number,
+  hidden: boolean
+): ReactElement | undefined {
+  if (!provider.initScript) return undefined
+
+  const styleAttr = hidden ? { style: { display: 'none' } } : {}
+
+  return (
+    <script
+      key={`init-${providerIndex}`}
+      data-testid={`analytics-${provider.name}`}
+      dangerouslySetInnerHTML={{
+        __html: provider.initScript,
+      }}
+      {...styleAttr}
+    />
+  )
+}
+
+/**
+ * Build marker script for analytics provider (when no scripts exist)
+ *
+ * SECURITY: Safe use of dangerouslySetInnerHTML
+ * - Content: Static comment marker with provider name
+ * - Source: provider.name from validated Analytics schema
+ * - Risk: None - contains only static comment text
+ * - Validation: provider.name is validated as string by schema
+ * - Purpose: Testing/debugging marker when provider has no actual scripts
+ * - XSS Protection: Comment syntax prevents code execution
+ */
+export function buildMarkerScript(
+  provider: Analytics['providers'][number],
+  providerIndex: number,
+  hidden: boolean
+): ReactElement | undefined {
+  const hasNoScripts = (!provider.scripts || provider.scripts.length === 0) && !provider.initScript
+
+  if (!hasNoScripts) return undefined
+
+  const styleAttr = hidden ? { style: { display: 'none' } } : {}
+
+  return (
+    <script
+      key={`marker-${providerIndex}`}
+      data-testid={`analytics-${provider.name}`}
+      dangerouslySetInnerHTML={{
+        __html: `/* ${provider.name} analytics marker */`,
+      }}
+      {...styleAttr}
+    />
+  )
+}
+
+/**
+ * Build config data script for analytics provider
+ *
+ * SECURITY: Safe use of dangerouslySetInnerHTML
+ * - Content: JSON configuration data (JSON.stringify)
+ * - Source: provider.config from validated Analytics schema
+ * - Risk: None - JSON data cannot execute as code
+ * - Validation: Schema validation ensures object type
+ * - Purpose: Store analytics configuration as JSON for client-side access
+ * - XSS Protection: type="application/json" prevents script execution
+ * - Format: Safe serialization via JSON.stringify
+ */
+export function buildConfigScript(
+  provider: Analytics['providers'][number],
+  providerIndex: number,
+  hidden: boolean
+): ReactElement | undefined {
+  if (!provider.config) return undefined
+
+  const styleAttr = hidden ? { style: { display: 'none' } } : {}
+
+  return (
+    <script
+      key={`config-${providerIndex}`}
+      data-testid={`analytics-${provider.name}-config`}
+      type="application/json"
+      dangerouslySetInnerHTML={{
+        __html: JSON.stringify(provider.config),
+      }}
+      {...styleAttr}
+    />
+  )
+}
+
+/**
+ * Build all elements for a single analytics provider
+ */
+export function buildProviderElements(
+  provider: Analytics['providers'][number],
+  providerIndex: number
+): readonly ReactElement[] {
+  const isEnabled = provider.enabled !== false
+  const hidden = !isEnabled
+
+  return [
+    buildDnsPrefetchLink(provider, providerIndex, hidden),
+    ...buildExternalScripts(provider, providerIndex, hidden),
+    buildInitScript(provider, providerIndex, hidden),
+    buildMarkerScript(provider, providerIndex, hidden),
+    buildConfigScript(provider, providerIndex, hidden),
+  ].filter((el): el is ReactElement => el !== undefined)
+}

package/src/presentation/ui/metadata/analytics-head.tsx

@@ -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 { type ReactElement } from 'react'
+import { buildProviderElements } from './analytics-builders'
+import type { Analytics } from '@/domain/models/app/page/meta/analytics'
+
+/**
+ * Render analytics provider scripts and configuration in HEAD section
+ * Generates DNS prefetch, external scripts with data-testid, and initialization scripts
+ *
+ * @param analytics - Analytics configuration from page.meta (union type)
+ * @returns React fragment with head elements
+ */
+export function AnalyticsHead({
+  analytics,
+}: {
+  readonly analytics?: Analytics | { readonly [x: string]: unknown }
+}): Readonly<ReactElement | undefined> {
+  // Type guard: ensure analytics has providers array (not generic record)
+  if (
+    !analytics ||
+    !('providers' in analytics) ||
+    !Array.isArray(analytics.providers) ||
+    analytics.providers.length === 0
+  ) {
+    return undefined
+  }
+
+  // Type assertion: after type guard, we know analytics has providers array
+  const analyticsConfig = analytics as Analytics
+
+  // Render all providers using builder pattern
+  return <>{analyticsConfig.providers.flatMap(buildProviderElements)}</>
+}

package/src/presentation/ui/metadata/custom-elements-builders.tsx

@@ -0,0 +1,157 @@
+/**
+ * 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 { CustomElements } from '@/domain/models/app/page/meta/custom-elements'
+
+/**
+ * Build meta element
+ */
+export function buildMetaElement(element: CustomElements[number], key: string): ReactElement {
+  return (
+    <meta
+      key={key}
+      {...element.attrs}
+    />
+  )
+}
+
+/**
+ * Build link element
+ */
+export function buildLinkElement(element: CustomElements[number], key: string): ReactElement {
+  return (
+    <link
+      key={key}
+      {...element.attrs}
+    />
+  )
+}
+
+/**
+ * Process boolean HTML attributes for script elements
+ * Converts string 'true'/'false' to boolean/undefined
+ */
+function processBooleanAttributes(
+  attrs: Record<string, unknown> | undefined
+): Record<string, unknown> {
+  if (!attrs) return {}
+
+  const booleanAttrs = ['async', 'defer', 'noModule'] as const
+
+  // First, copy all non-boolean attributes
+  const result = Object.entries(attrs).reduce<Record<string, unknown>>((acc, [key, value]) => {
+    if (!booleanAttrs.includes(key as (typeof booleanAttrs)[number])) {
+      return { ...acc, [key]: value }
+    }
+    return acc
+  }, {})
+
+  // Then process boolean attributes
+  return booleanAttrs.reduce<Record<string, unknown>>((acc, attr) => {
+    if (!(attr in attrs)) return acc
+
+    const value = attrs[attr]
+    if (value === 'true') {
+      return { ...acc, [attr]: true }
+    }
+    // Remove false/empty values (omit from result)
+    return acc
+  }, result)
+}
+
+/**
+ * Build script element
+ * Handles boolean attributes (async, defer) - converts string 'true'/'false' to boolean
+ *
+ * SECURITY: Safe use of dangerouslySetInnerHTML
+ * - Content: Custom script code from page configuration
+ * - Source: Validated CustomElements schema (page.meta.customElements[].content)
+ * - Risk: Low - content is from server configuration, not user input
+ * - Validation: Schema validation ensures string type
+ * - Purpose: Render custom inline scripts for analytics, tracking, etc.
+ * - CSP: Inline script - consider using nonce for stricter CSP
+ * - Best Practice: Prefer external scripts with SRI when possible
+ */
+export function buildScriptElement(element: CustomElements[number], key: string): ReactElement {
+  const processedAttrs = processBooleanAttributes(element.attrs)
+
+  if (element.content) {
+    return (
+      <script
+        key={key}
+        {...processedAttrs}
+        dangerouslySetInnerHTML={{ __html: element.content }}
+      />
+    )
+  }
+  return (
+    <script
+      key={key}
+      {...processedAttrs}
+    />
+  )
+}
+
+/**
+ * Build style element
+ *
+ * SECURITY: Safe use of dangerouslySetInnerHTML
+ * - Content: Custom CSS code from page configuration
+ * - Source: Validated CustomElements schema (page.meta.customElements[].content)
+ * - Risk: Low - CSS cannot execute JavaScript
+ * - Validation: Schema validation ensures string type
+ * - Purpose: Render custom inline styles for page-specific styling
+ * - XSS Protection: CSS syntax prevents script execution
+ * - CSP: style-src 'unsafe-inline' required (consider nonce for stricter CSP)
+ */
+export function buildStyleElement(element: CustomElements[number], key: string): ReactElement {
+  return (
+    <style
+      key={key}
+      {...element.attrs}
+      dangerouslySetInnerHTML={{ __html: element.content || '' }}
+    />
+  )
+}
+
+/**
+ * Build base element
+ */
+export function buildBaseElement(element: CustomElements[number], key: string): ReactElement {
+  return (
+    <base
+      key={key}
+      {...element.attrs}
+    />
+  )
+}
+
+/**
+ * Build custom element based on type
+ */
+export function buildCustomElement(
+  element: CustomElements[number],
+  index: number
+): ReactElement | undefined {
+  const key = `custom-${element.type}-${index}`
+
+  switch (element.type) {
+    case 'meta':
+      return buildMetaElement(element, key)
+    case 'link':
+      return buildLinkElement(element, key)
+    case 'script':
+      return buildScriptElement(element, key)
+    case 'style':
+      return buildStyleElement(element, key)
+    case 'base':
+      return buildBaseElement(element, key)
+    default:
+      return undefined
+  }
+}