sovrium 0.0.2

package/src/presentation/ui/pages/PageLangResolver.ts

@@ -0,0 +1,58 @@
+/**
+ * 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 { Page } from '@/domain/models/app/pages'
+
+/**
+ * Page language configuration
+ */
+export type PageLangConfig = {
+  readonly lang: string
+  readonly direction: 'ltr' | 'rtl'
+  readonly directionStyles: string
+}
+
+/**
+ * Resolves language configuration for a page
+ *
+ * Priority: page.meta.lang > detectedLanguage > languages.default > 'en-US'
+ *
+ * @param page - Page configuration
+ * @param languages - Languages configuration
+ * @param detectedLanguage - Detected language from browser/URL
+ * @returns Language configuration with direction and styles
+ */
+export function resolvePageLanguage(
+  page: Page,
+  languages: Languages | undefined,
+  detectedLanguage: string | undefined
+): PageLangConfig {
+  // Priority: page.meta.lang (EXPLICIT) > detectedLanguage > languages.default > fallback
+  // NOTE: Using explicit check to ensure page.meta.lang is always preferred when present
+  const lang =
+    page.meta && page.meta.lang
+      ? page.meta.lang
+      : detectedLanguage
+        ? detectedLanguage
+        : languages?.default
+          ? languages.default
+          : 'en-US'
+
+  // Determine text direction from language configuration
+  // Match by code (en) or locale (en-US)
+  const langConfig = languages?.supported.find((l) => l.code === lang || l.locale === lang)
+  const direction = langConfig?.direction || 'ltr'
+
+  // Generate CSS for body direction to ensure RTL/LTR is applied as CSS property
+  const directionStyles = `
+    html[lang="${lang}"] { direction: ${direction}; }
+    html[lang="${lang}"] body { direction: ${direction}; }
+  `
+
+  return { lang, direction, directionStyles }
+}

package/src/presentation/ui/pages/PageMain.tsx

@@ -0,0 +1,58 @@
+/**
+ * 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 { SectionRenderer } from '@/presentation/ui/pages/SectionRenderer'
+import { toSlug } from '@/presentation/utils/string-utils'
+import type {
+  ComponentReference,
+  SimpleComponentReference,
+} from '@/domain/models/app/component/common/component-reference'
+import type { Components } from '@/domain/models/app/components'
+import type { Languages } from '@/domain/models/app/languages'
+import type { Component } from '@/domain/models/app/page/sections'
+import type { Page } from '@/domain/models/app/pages'
+import type { Theme } from '@/domain/models/app/theme'
+
+type PageMainProps = {
+  readonly page: Page
+  readonly sections: ReadonlyArray<Component | SimpleComponentReference | ComponentReference>
+  readonly theme?: Theme
+  readonly components?: Components
+  readonly languages?: Languages
+  readonly currentLang: string
+}
+
+/**
+ * Renders the main content area with page sections
+ */
+export function PageMain({
+  page,
+  sections,
+  theme,
+  components,
+  languages,
+  currentLang,
+}: PageMainProps): Readonly<ReactElement> {
+  return (
+    <main
+      data-testid={`page-${toSlug(page.name ?? page.path)}`}
+      data-page-name={page.name}
+      data-page-id={page.id}
+      style={{ minHeight: '1px' }}
+    >
+      <SectionRenderer
+        sections={sections}
+        pageVars={page.vars}
+        theme={theme}
+        components={components}
+        languages={languages}
+        currentLang={currentLang}
+      />
+    </main>
+  )
+}

package/src/presentation/ui/pages/PageMetadata.ts

@@ -0,0 +1,168 @@
+/**
+ * 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 { resolveTranslationPattern } from '@/presentation/translations/translation-resolver'
+import type { Languages } from '@/domain/models/app/languages'
+import type { Page } from '@/domain/models/app/pages'
+import type { Theme } from '@/domain/models/app/theme'
+
+/**
+ * Metadata derived from page configuration
+ */
+export type PageMetadata = {
+  readonly lang: string
+  readonly direction: 'ltr' | 'rtl'
+  readonly title: string
+  readonly description: string
+  readonly keywords?: string
+  readonly canonical?: string
+  readonly bodyStyle:
+    | {
+        readonly fontFamily?: string
+        readonly fontSize?: string
+        readonly lineHeight?: string
+        readonly fontStyle?: 'normal' | 'italic' | 'oblique'
+        readonly letterSpacing?: string
+        readonly textTransform?: 'none' | 'uppercase' | 'lowercase' | 'capitalize'
+      }
+    | undefined
+}
+
+/**
+ * Build font-family string with fallback
+ */
+function buildFontFamily(family?: string, fallback?: string): string | undefined {
+  if (!family) {
+    return undefined
+  }
+  return fallback ? `${family}, ${fallback}` : family
+}
+
+/**
+ * Build body style object from theme fonts configuration
+ */
+function buildBodyStyle(theme: Theme | undefined): PageMetadata['bodyStyle'] {
+  if (!theme?.fonts?.body) {
+    return undefined
+  }
+
+  const { body } = theme.fonts
+  const fontFamily = buildFontFamily(body.family, body.fallback)
+
+  return {
+    ...(fontFamily && { fontFamily }),
+    ...(body.size && { fontSize: body.size }),
+    ...(body.lineHeight && { lineHeight: body.lineHeight }),
+    ...(body.style && { fontStyle: body.style as 'normal' | 'italic' | 'oblique' }),
+    ...(body.letterSpacing && { letterSpacing: body.letterSpacing }),
+    ...(body.transform && {
+      textTransform: body.transform as 'none' | 'uppercase' | 'lowercase' | 'capitalize',
+    }),
+  }
+}
+
+/**
+ * Determine language code (priority: page.meta.lang > detectedLanguage > default)
+ */
+function determineLanguage(
+  page: Page,
+  languages: Languages | undefined,
+  detectedLanguage: string | undefined
+): string {
+  return page.meta?.lang || detectedLanguage || languages?.default || 'en-US'
+}
+
+/**
+ * Determine text direction from language configuration
+ */
+function determineDirection(languages: Languages | undefined, lang: string): 'ltr' | 'rtl' {
+  const langConfig = languages?.supported.find((l) => l.code === lang)
+  return langConfig?.direction || 'ltr'
+}
+
+/**
+ * Determine page title with translation resolution
+ * Priority: meta.i18n[lang].title > meta.title (with $t: pattern) > page.name > page.path
+ */
+function determineTitle(page: Page, lang: string, languages: Languages | undefined): string {
+  // Check if page has i18n translations for this language
+  if (page.meta?.i18n?.[lang]?.title) {
+    return page.meta.i18n[lang].title
+  }
+
+  // Fall back to base title with translation pattern resolution
+  const rawTitle = page.meta?.title || page.name || page.path
+  return resolveTranslationPattern(rawTitle, lang, languages)
+}
+
+/**
+ * Determine page description with translation resolution
+ * Priority: meta.i18n[lang].description > meta.description (with $t: pattern)
+ */
+function determineDescription(page: Page, lang: string, languages: Languages | undefined): string {
+  // Check if page has i18n translations for this language
+  if (page.meta?.i18n?.[lang]?.description) {
+    return page.meta.i18n[lang].description
+  }
+
+  // Fall back to base description with translation pattern resolution
+  const rawDescription = page.meta?.description || ''
+  return resolveTranslationPattern(rawDescription, lang, languages)
+}
+
+/**
+ * Determine page keywords with translation resolution
+ * Resolves $t: patterns in keywords
+ */
+function determineKeywords(
+  page: Page,
+  lang: string,
+  languages: Languages | undefined
+): string | undefined {
+  if (!page.meta?.keywords) {
+    return undefined
+  }
+
+  return resolveTranslationPattern(page.meta.keywords, lang, languages)
+}
+
+/**
+ * Extracts and computes metadata from page configuration
+ *
+ * Determines language (page.meta.lang > detectedLanguage > default),
+ * text direction from language config, title/description, and body styles from theme.
+ *
+ * @param page - Page configuration
+ * @param theme - Optional theme configuration
+ * @param languages - Optional languages configuration
+ * @param detectedLanguage - Optional detected language from browser or URL
+ * @returns Computed page metadata
+ */
+export function extractPageMetadata(
+  page: Page,
+  theme: Theme | undefined,
+  languages: Languages | undefined,
+  detectedLanguage: string | undefined
+): Readonly<PageMetadata> {
+  const lang = determineLanguage(page, languages, detectedLanguage)
+  const direction = determineDirection(languages, lang)
+  const title = determineTitle(page, lang, languages)
+  const description = determineDescription(page, lang, languages)
+  const keywords = determineKeywords(page, lang, languages)
+  const canonical = page.meta?.canonical
+  const bodyStyle = buildBodyStyle(theme)
+
+  return {
+    lang,
+    direction,
+    title,
+    description,
+    keywords,
+    canonical,
+    bodyStyle,
+  }
+}

package/src/presentation/ui/pages/PageMetadataI18n.ts

@@ -0,0 +1,169 @@
+/**
+ * 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 { resolveTranslationPattern } from '@/presentation/translations/translation-resolver'
+import type { Languages } from '@/domain/models/app/languages'
+import type { Meta } from '@/domain/models/app/page/meta'
+import type { Page } from '@/domain/models/app/pages'
+
+/**
+ * Resolves i18n metadata for a single language
+ */
+function resolveMetaI18n(
+  meta: Meta,
+  langCode: string,
+  languages: Languages
+): { title?: string; description?: string; keywords?: string; 'og:site_name'?: string } {
+  const metaRecord = meta as Record<string, unknown>
+  const ogSiteName = metaRecord['og:site_name']
+
+  return {
+    ...(meta.title && {
+      title: resolveTranslationPattern(meta.title, langCode, languages),
+    }),
+    ...(meta.description && {
+      description: resolveTranslationPattern(meta.description, langCode, languages),
+    }),
+    ...(meta.keywords && {
+      keywords: resolveTranslationPattern(meta.keywords, langCode, languages),
+    }),
+    ...(typeof ogSiteName === 'string' && {
+      'og:site_name': resolveTranslationPattern(ogSiteName, langCode, languages),
+    }),
+    ...(meta.openGraph?.siteName &&
+      typeof ogSiteName !== 'string' && {
+        'og:site_name': resolveTranslationPattern(meta.openGraph.siteName, langCode, languages),
+      }),
+  }
+}
+
+/**
+ * Merges existing i18n with generated i18n
+ */
+function mergeI18n(
+  generatedI18n: Record<
+    string,
+    { title?: string; description?: string; keywords?: string; 'og:site_name'?: string }
+  >,
+  existingI18n:
+    | Record<
+        string,
+        { title?: string; description?: string; keywords?: string; 'og:site_name'?: string }
+      >
+    | undefined
+): typeof generatedI18n {
+  if (!existingI18n) {
+    return generatedI18n
+  }
+
+  return Object.keys(generatedI18n).reduce(
+    (acc, langCode) => ({
+      ...acc,
+      [langCode]: {
+        ...generatedI18n[langCode],
+        ...(existingI18n[langCode] || {}),
+      },
+    }),
+    {} as typeof generatedI18n
+  )
+}
+
+/**
+ * Resolves base meta fields with translation patterns
+ */
+function resolveBaseMeta(meta: Meta, currentLang: string, languages: Languages): Meta {
+  const metaRecord = meta as Record<string, unknown>
+  const ogSiteName = metaRecord['og:site_name']
+
+  const resolvedMeta = {
+    ...meta,
+    ...(meta.title && { title: resolveTranslationPattern(meta.title, currentLang, languages) }),
+    ...(meta.description && {
+      description: resolveTranslationPattern(meta.description, currentLang, languages),
+    }),
+    ...(meta.keywords && {
+      keywords: resolveTranslationPattern(meta.keywords, currentLang, languages),
+    }),
+  }
+
+  // Resolve og:site_name if present (either as direct property or in openGraph object)
+  if (typeof ogSiteName === 'string') {
+    return {
+      ...resolvedMeta,
+      'og:site_name': resolveTranslationPattern(ogSiteName, currentLang, languages),
+    } as Meta
+  }
+
+  if (meta.openGraph?.siteName) {
+    return {
+      ...resolvedMeta,
+      openGraph: {
+        ...meta.openGraph,
+        siteName: resolveTranslationPattern(meta.openGraph.siteName, currentLang, languages),
+      },
+    }
+  }
+
+  return resolvedMeta
+}
+
+/**
+ * Builds i18n metadata structure for client-side language switching
+ *
+ * Resolves translation patterns ($t:...) for all supported languages
+ * and constructs a complete i18n structure that the client can use
+ * to update meta tags when switching languages.
+ *
+ * CRITICAL: All $t: tokens in base meta fields are resolved to ensure
+ * no translation tokens appear in the serialized HTML output.
+ *
+ * @param page - Page configuration
+ * @param languages - Languages configuration
+ * @returns Page meta with i18n structure populated and all $t: tokens resolved
+ */
+export function buildPageMetadataI18n(
+  page: Page,
+  languages: Languages | undefined
+): Meta | Record<string, never> {
+  if (!page.meta || !languages) {
+    return (page.meta || {}) as Meta | Record<string, never>
+  }
+
+  const { meta } = page
+  const currentLang = meta.lang || languages.default
+
+  // Build i18n structure for all supported languages
+  const generatedI18n = languages.supported.reduce(
+    (acc, lang) => ({
+      ...acc,
+      [lang.code]: resolveMetaI18n(meta, lang.code, languages),
+    }),
+    {} as Record<
+      string,
+      { title?: string; description?: string; keywords?: string; 'og:site_name'?: string }
+    >
+  )
+
+  // Merge existing meta.i18n with generated i18n (existing takes precedence)
+  const existingI18n = (meta as Record<string, unknown>).i18n as
+    | Record<
+        string,
+        { title?: string; description?: string; keywords?: string; 'og:site_name'?: string }
+      >
+    | undefined
+
+  const i18n = mergeI18n(generatedI18n, existingI18n)
+
+  // Resolve all $t: tokens in base meta fields for current language
+  const resolvedMeta = resolveBaseMeta(meta, currentLang, languages)
+
+  // Return resolved meta with i18n structure
+  return {
+    ...resolvedMeta,
+    i18n,
+  }
+}

package/src/presentation/ui/pages/PageScripts.ts

@@ -0,0 +1,78 @@
+/**
+ * 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 { Page } from '@/domain/models/app/pages'
+
+/**
+ * External script configuration
+ */
+export type ExternalScript = {
+  readonly src: string
+  readonly position?: 'head' | 'body-start' | 'body-end'
+  readonly async?: boolean
+  readonly defer?: boolean
+  readonly module?: boolean
+  readonly integrity?: string
+  readonly crossorigin?: 'anonymous' | 'use-credentials'
+}
+
+/**
+ * Inline script configuration
+ */
+export type InlineScript = {
+  readonly code: string
+  readonly position?: 'head' | 'body-start' | 'body-end'
+  readonly async?: boolean
+}
+
+/**
+ * Grouped scripts by position
+ */
+export type GroupedScripts = {
+  readonly external: {
+    readonly head: ReadonlyArray<ExternalScript>
+    readonly bodyStart: ReadonlyArray<ExternalScript>
+    readonly bodyEnd: ReadonlyArray<ExternalScript>
+  }
+  readonly inline: {
+    readonly head: ReadonlyArray<InlineScript>
+    readonly bodyStart: ReadonlyArray<InlineScript>
+    readonly bodyEnd: ReadonlyArray<InlineScript>
+  }
+}
+
+/**
+ * Groups external and inline scripts by their position in the document
+ *
+ * Scripts can be positioned in 'head', 'body-start', or 'body-end'.
+ * Scripts without a position default to 'body-end'.
+ *
+ * @param page - Page configuration containing scripts
+ * @returns Scripts grouped by position
+ */
+export function groupScriptsByPosition(page: Page): Readonly<GroupedScripts> {
+  // Extract external scripts (support both test shorthand and canonical property)
+  const externalScripts = page.scripts?.externalScripts || page.scripts?.external || []
+
+  // Extract inline scripts
+  const inlineScripts = page.scripts?.inlineScripts || []
+
+  return {
+    external: {
+      head: externalScripts.filter((script) => script.position === 'head'),
+      bodyStart: externalScripts.filter((script) => script.position === 'body-start'),
+      bodyEnd: externalScripts.filter(
+        (script) => !script.position || script.position === 'body-end'
+      ),
+    },
+    inline: {
+      head: inlineScripts.filter((script) => script.position === 'head'),
+      bodyStart: inlineScripts.filter((script) => script.position === 'body-start'),
+      bodyEnd: inlineScripts.filter((script) => !script.position || script.position === 'body-end'),
+    },
+  }
+}

package/src/presentation/ui/pages/SectionRenderer.tsx

@@ -0,0 +1,67 @@
+/**
+ * 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 { getComponentInfo } from '@/presentation/translations/component-utils'
+import { renderSectionWithSpacing } from '@/presentation/ui/pages/SectionSpacing'
+import { ComponentRenderer } from '@/presentation/ui/sections/component-renderer'
+import type {
+  ComponentReference,
+  SimpleComponentReference,
+} from '@/domain/models/app/component/common/component-reference'
+import type { Components } from '@/domain/models/app/components'
+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'
+
+/**
+ * Props for the SectionRenderer component
+ */
+export interface SectionRendererProps {
+  readonly sections: ReadonlyArray<Component | SimpleComponentReference | ComponentReference>
+  readonly pageVars?: Record<string, string | number | boolean>
+  readonly theme?: Theme
+  readonly components?: Components
+  readonly languages?: Languages
+  readonly currentLang: string
+}
+
+/**
+ * Render sections with theme spacing
+ * Handles section wrapping, container spacing, and component resolution
+ *
+ * @param props - Component props
+ * @returns React element with sections
+ */
+export function SectionRenderer({
+  sections,
+  pageVars,
+  theme,
+  components,
+  languages,
+  currentLang,
+}: SectionRendererProps): Readonly<ReactElement> {
+  const renderedSections = sections.map((section, index) => {
+    const componentInfo = getComponentInfo(section, index, sections)
+
+    return (
+      <ComponentRenderer
+        key={index}
+        component={section}
+        pageVars={pageVars}
+        componentName={componentInfo?.name}
+        componentInstanceIndex={componentInfo?.instanceIndex}
+        components={components}
+        theme={theme}
+        languages={languages}
+        currentLang={currentLang}
+      />
+    )
+  })
+
+  return renderSectionWithSpacing(theme, sections, renderedSections)
+}