sovrium 0.0.2

package/src/presentation/ui/metadata/extract-component-meta.ts

@@ -0,0 +1,108 @@
+/**
+ * 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 { ComponentMeta } from './structured-data-from-component'
+import type {
+  ComponentReference,
+  SimpleComponentReference,
+} from '@/domain/models/app/component/common/component-reference'
+import type { Components } from '@/domain/models/app/components'
+import type { OpenGraph } from '@/domain/models/app/page/meta/open-graph'
+import type { Component } from '@/domain/models/app/page/sections'
+
+/**
+ * Substitutes variables in a string value
+ *
+ * @param value - String value with potential $variable placeholders
+ * @param vars - Variables map
+ * @returns String with variables substituted
+ */
+function substituteMetaVariables(
+  value: string | undefined,
+  vars: Record<string, string | number | boolean> | undefined
+): string | undefined {
+  if (!value || !vars) return value
+
+  // Use reduce for functional approach instead of loop with mutation
+  return Object.entries(vars).reduce(
+    (result, [key, varValue]) => result.replace(new RegExp(`\\$${key}`, 'g'), String(varValue)),
+    value
+  )
+}
+
+/**
+ * Extracts Open Graph meta from a component's meta configuration
+ *
+ * @param meta - Component meta configuration
+ * @param vars - Variables for substitution
+ * @returns Partial Open Graph configuration
+ */
+function extractOpenGraphFromComponentMeta(
+  meta: ComponentMeta | undefined,
+  vars: Record<string, string | number | boolean> | undefined
+): Partial<OpenGraph> | undefined {
+  if (!meta) return undefined
+
+  // Build immutably without mutation
+  const withImage = meta.image ? { image: substituteMetaVariables(meta.image, vars) } : {}
+
+  const withTitle = meta.title ? { title: substituteMetaVariables(meta.title, vars) } : {}
+
+  const withDescription = meta.description
+    ? { description: substituteMetaVariables(meta.description, vars) }
+    : {}
+
+  const openGraph = {
+    ...withImage,
+    ...withTitle,
+    ...withDescription,
+  }
+
+  return Object.keys(openGraph).length > 0 ? openGraph : undefined
+}
+
+/**
+ * Extracts component meta from page sections
+ *
+ * Processes all sections to find component references, resolves them, and extracts
+ * meta information that should be included in the page's Open Graph meta tags.
+ *
+ * @param sections - Page sections
+ * @param components - Available component templates
+ * @returns Merged Open Graph configuration from all components
+ */
+export function extractComponentMetaFromSections(
+  sections: ReadonlyArray<Component | SimpleComponentReference | ComponentReference>,
+  components?: Components
+): Partial<OpenGraph> | undefined {
+  if (!sections || !components) return undefined
+
+  // Use functional map/filter instead of loop with mutation
+  const openGraphParts = sections
+    .filter(
+      (section): section is SimpleComponentReference | ComponentReference =>
+        'component' in section || '$ref' in section
+    )
+    .map((section) => {
+      const componentName = 'component' in section ? section.component : section.$ref
+      const vars = 'vars' in section ? section.vars : undefined
+
+      // Find the component template definition
+      const template = components.find((b) => b.name === componentName)
+      if (!template?.props?.meta) return undefined
+
+      // Extract Open Graph meta from component meta
+      const meta = template.props.meta as ComponentMeta | undefined
+      return extractOpenGraphFromComponentMeta(meta, vars)
+    })
+    .filter((og): og is Partial<OpenGraph> => og !== undefined)
+
+  if (openGraphParts.length === 0) return undefined
+
+  // Merge all Open Graph parts (last one wins for duplicate keys)
+  return openGraphParts.reduce((acc, part) => ({ ...acc, ...part }), {})
+}

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

@@ -0,0 +1,164 @@
+/**
+ * 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 { buildCustomElement } from './custom-elements-builders'
+import type { CustomElements } from '@/domain/models/app/page/meta/custom-elements'
+import type { FaviconSet } from '@/domain/models/app/page/meta/favicon-set'
+import type { Preload } from '@/domain/models/app/page/meta/preload'
+
+/**
+ * Render DNS prefetch link tags
+ * Generates <link rel="dns-prefetch" href="..."> tags for external domains
+ *
+ * @param dnsPrefetch - DNS prefetch configuration from page.meta
+ * @returns React fragment with DNS prefetch link tags
+ */
+export function DnsPrefetchLinks({
+  dnsPrefetch,
+}: {
+  readonly dnsPrefetch?: ReadonlyArray<string>
+}): Readonly<ReactElement | undefined> {
+  if (!dnsPrefetch || dnsPrefetch.length === 0) {
+    return undefined
+  }
+
+  return (
+    <>
+      {dnsPrefetch.map((domain) => (
+        <link
+          key={domain}
+          rel="dns-prefetch"
+          href={domain}
+        />
+      ))}
+    </>
+  )
+}
+
+/**
+ * Render custom head elements
+ * Generates arbitrary HTML elements (meta, link, script, style, base) in <head>
+ *
+ * @param customElements - Custom elements configuration from page.meta
+ * @returns React fragment with custom head elements
+ */
+export function CustomElementsHead({
+  customElements,
+}: {
+  readonly customElements?: CustomElements
+}): Readonly<ReactElement | undefined> {
+  if (!customElements || customElements.length === 0) {
+    return undefined
+  }
+
+  return <>{customElements.map(buildCustomElement)}</>
+}
+
+/**
+ * Render single favicon link tag
+ * Generates simple <link rel="icon" href="..."> tag for default favicon
+ *
+ * @param favicon - Favicon path from page.meta.favicon
+ * @returns React element with favicon link tag or undefined
+ */
+export function FaviconLink({
+  favicon,
+}: {
+  readonly favicon?: string
+}): Readonly<ReactElement | undefined> {
+  if (!favicon) {
+    return undefined
+  }
+
+  return (
+    <link
+      rel="icon"
+      href={favicon}
+    />
+  )
+}
+
+/**
+ * Render favicon set link tags
+ * Generates <link rel="..."> tags for multi-device favicon support
+ *
+ * Supports:
+ * - icon: Standard browser favicon (16x16, 32x32)
+ * - apple-touch-icon: iOS home screen icon (180x180)
+ * - manifest: PWA manifest file reference
+ * - mask-icon: Safari pinned tab icon (monochrome SVG with color)
+ *
+ * @param favicons - Favicon set configuration from page.meta
+ * @returns React fragment with favicon link tags
+ */
+export function FaviconSetLinks({
+  favicons,
+}: {
+  readonly favicons?: FaviconSet
+}): Readonly<ReactElement | undefined> {
+  if (!favicons || favicons.length === 0) {
+    return undefined
+  }
+
+  return (
+    <>
+      {favicons.map((favicon, index) => {
+        // Convert relative path (./favicon.png) to absolute path (/favicon.png)
+        // Remove the leading ./ to make it an absolute path from the root
+        const href = favicon.href.replace(/^\.\//, '/')
+
+        return (
+          <link
+            key={index}
+            rel={favicon.rel}
+            href={href}
+            {...(favicon.type && { type: favicon.type })}
+            {...(favicon.sizes && { sizes: favicon.sizes })}
+            {...(favicon.color && { color: favicon.color })}
+          />
+        )
+      })}
+    </>
+  )
+}
+
+/**
+ * Render preload link tags
+ * Generates <link rel="preload" ...> tags for critical resources
+ *
+ * @param preload - Preload configuration from page.meta
+ * @returns React fragment with preload link tags
+ */
+export function PreloadLinks({
+  preload,
+}: {
+  readonly preload?: Preload
+}): Readonly<ReactElement | undefined> {
+  if (!preload || preload.length === 0) {
+    return undefined
+  }
+
+  return (
+    <>
+      {preload.map((item, index) => (
+        <link
+          key={index}
+          rel="preload"
+          href={item.href}
+          as={item.as}
+          {...(item.type && { type: item.type })}
+          {...(item.crossorigin !== undefined &&
+            (typeof item.crossorigin === 'boolean'
+              ? item.crossorigin && { crossOrigin: '' }
+              : { crossOrigin: item.crossorigin }))}
+          {...(item.media && { media: item.media })}
+        />
+      ))}
+    </>
+  )
+}

package/src/presentation/ui/metadata/index.tsx

@@ -0,0 +1,35 @@
+/**
+ * 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.
+ */
+
+/**
+ * Metadata components barrel export
+ *
+ * This module exports all metadata rendering components:
+ * - OpenGraphMeta: Facebook/LinkedIn Open Graph tags
+ * - TwitterCardMeta: Twitter/X card tags
+ * - StructuredDataScript: Schema.org JSON-LD
+ * - AnalyticsHead: Analytics provider scripts
+ * - DnsPrefetchLinks: DNS prefetch link tags
+ * - CustomElementsHead: Custom head elements
+ * - FaviconLink: Simple favicon link
+ * - FaviconSetLinks: Multi-device favicon set
+ * - PreloadLinks: Resource preload hints
+ *
+ * @see Individual component files for detailed documentation
+ */
+
+export { OpenGraphMeta } from './open-graph-meta'
+export { TwitterCardMeta } from './twitter-card-meta'
+export { StructuredDataScript } from './structured-data'
+export { AnalyticsHead } from './analytics-head'
+export {
+  DnsPrefetchLinks,
+  CustomElementsHead,
+  FaviconLink,
+  FaviconSetLinks,
+  PreloadLinks,
+} from './head-elements'

package/src/presentation/ui/metadata/meta-utils.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'
+
+/**
+ * Shared helper to render meta tags with configurable attribute type
+ * Eliminates duplication between OpenGraph and Twitter Card rendering
+ *
+ * @param fields - Array of key-value pairs to render as meta tags
+ * @param prefix - Prefix for meta tag name/property (e.g., 'og', 'twitter')
+ * @param attributeType - HTML attribute to use ('property' for OG, 'name' for Twitter)
+ * @returns React fragment with meta tags
+ */
+export function renderMetaTags({
+  fields,
+  prefix,
+  attributeType,
+}: {
+  readonly fields: ReadonlyArray<{ readonly key: string; readonly value?: string | number }>
+  readonly prefix: string
+  readonly attributeType: 'property' | 'name'
+}): ReactElement {
+  return (
+    <>
+      {fields.map(
+        ({ key, value }) =>
+          value !== undefined && (
+            <meta
+              key={key}
+              {...{ [attributeType]: `${prefix}:${key}` }}
+              content={String(value)}
+            />
+          )
+      )}
+    </>
+  )
+}

package/src/presentation/ui/metadata/open-graph-meta.tsx

@@ -0,0 +1,57 @@
+/**
+ * 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 { resolveTranslationPattern } from '@/presentation/translations/translation-resolver'
+import { renderMetaTags } from './meta-utils'
+import type { Languages } from '@/domain/models/app/languages'
+import type { OpenGraph } from '@/domain/models/app/page/meta/open-graph'
+
+/**
+ * Render Open Graph metadata tags
+ * Generates <meta property="og:*"> tags for Facebook/LinkedIn sharing
+ *
+ * @param openGraph - Open Graph configuration from page.meta
+ * @param lang - Current language code for translation resolution
+ * @param languages - Languages configuration for translation resolution
+ * @returns React fragment with OG meta tags
+ */
+export function OpenGraphMeta({
+  openGraph,
+  lang,
+  languages,
+}: {
+  readonly openGraph?: OpenGraph
+  readonly lang?: string
+  readonly languages?: Languages
+}): Readonly<ReactElement | undefined> {
+  if (!openGraph) {
+    return undefined
+  }
+
+  // Resolve translation patterns in OpenGraph fields
+  const resolveValue = (value: string | undefined): string | undefined => {
+    if (!value || !lang) return value
+    return resolveTranslationPattern(value, lang, languages)
+  }
+
+  const fields: ReadonlyArray<{ readonly key: string; readonly value?: string }> = [
+    { key: 'title', value: resolveValue(openGraph.title) },
+    { key: 'description', value: resolveValue(openGraph.description) },
+    { key: 'image', value: openGraph.image },
+    { key: 'image:alt', value: resolveValue(openGraph.imageAlt) },
+    { key: 'url', value: openGraph.url },
+    { key: 'type', value: openGraph.type },
+    { key: 'site_name', value: resolveValue(openGraph.siteName) },
+    { key: 'locale', value: openGraph.locale },
+    { key: 'determiner', value: openGraph.determiner },
+    { key: 'video', value: openGraph.video },
+    { key: 'audio', value: openGraph.audio },
+  ]
+
+  return renderMetaTags({ fields, prefix: 'og', attributeType: 'property' })
+}

package/src/presentation/ui/metadata/structured-data-from-component.tsx

@@ -0,0 +1,134 @@
+/**
+ * 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'
+
+/**
+ * Component meta property type for structured data
+ */
+export type ComponentMeta = {
+  readonly title?: string
+  readonly description?: string
+  readonly image?: string
+  readonly price?: string
+  readonly currency?: string
+  readonly structuredData?: {
+    readonly type: string
+    readonly fields: readonly string[]
+  }
+}
+
+/**
+ * Creates an offers object for Schema.org
+ *
+ * @param price - Product price
+ * @param currency - Currency code
+ * @returns Offers object or empty object
+ */
+function createOffer(price?: string, currency?: string): Record<string, unknown> {
+  return price && currency
+    ? {
+        offers: {
+          '@type': 'Offer',
+          price,
+          priceCurrency: currency,
+        },
+      }
+    : {}
+}
+
+/**
+ * Maps component meta field to Schema.org property
+ *
+ * @param fieldName - Schema.org field name
+ * @param meta - Component meta configuration
+ * @param fields - Enabled fields list
+ * @returns Field object or empty object
+ */
+function mapMetaField(
+  fieldName: string,
+  meta: ComponentMeta,
+  fields: readonly string[]
+): Record<string, unknown> {
+  if (!fields.includes(fieldName)) return {}
+
+  const { title, description, image, price, currency } = meta
+
+  if (fieldName === 'name' && title) return { name: title }
+  if (fieldName === 'description' && description) return { description }
+  if (fieldName === 'image' && image) return { image }
+  if (fieldName === 'offers') return createOffer(price, currency)
+
+  return {}
+}
+
+/**
+ * Generates Schema.org structured data JSON-LD from component meta
+ *
+ * @param meta - Component meta configuration
+ * @returns JSON-LD object following Schema.org format
+ */
+function generateStructuredData(meta: ComponentMeta): Record<string, unknown> {
+  const { structuredData } = meta
+
+  if (!structuredData) {
+    return {}
+  }
+
+  // Build JSON-LD immutably using functional composition
+  const baseJsonLd = {
+    '@context': 'https://schema.org',
+    '@type': structuredData.type,
+  }
+
+  const mappedFields = ['name', 'description', 'image', 'offers'].map((field) =>
+    mapMetaField(field, meta, structuredData.fields)
+  )
+
+  return mappedFields.reduce((acc, field) => ({ ...acc, ...field }), baseJsonLd)
+}
+
+/**
+ * Renders structured data script from component meta
+ *
+ * SECURITY: Safe use of dangerouslySetInnerHTML
+ * - Content: Schema.org JSON-LD from component metadata (JSON.stringify)
+ * - Source: Validated component meta configuration (component.meta.structuredData)
+ * - Risk: None - JSON data cannot execute as code
+ * - Validation: Schema validation ensures correct structure
+ * - Purpose: Generate rich search results from component content (SEO)
+ * - XSS Protection: type="application/ld+json" prevents script execution
+ * - Format: Safe serialization via JSON.stringify with formatting
+ *
+ * @param props - Component props
+ * @param props.meta - Component meta configuration
+ * @returns Script element with JSON-LD structured data, or null if no structured data
+ */
+export function StructuredDataFromComponent({
+  meta,
+}: {
+  readonly meta: ComponentMeta | undefined
+}): ReactElement | undefined {
+  if (!meta?.structuredData) {
+    return undefined
+  }
+
+  const jsonLd = generateStructuredData(meta)
+
+  if (Object.keys(jsonLd).length === 0) {
+    return undefined
+  }
+
+  return (
+    <script
+      type="application/ld+json"
+      dangerouslySetInnerHTML={{
+        __html: JSON.stringify(jsonLd, undefined, 2),
+      }}
+    />
+  )
+}

package/src/presentation/ui/metadata/structured-data.tsx

@@ -0,0 +1,88 @@
+/**
+ * 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 { Page } from '@/domain/models/app/pages'
+
+/**
+ * Render structured data as JSON-LD script tags
+ * Generates Schema.org structured data for rich search results
+ * Supports both 'schema' (canonical) and 'structuredData' (test alias)
+ *
+ * Handles two formats:
+ * 1. Direct Schema.org object: { "@context": "...", "@type": "...", ... }
+ * 2. Orchestrator schema: { organization: {...}, faqPage: {...}, ... }
+ *
+ * Each structured data type is rendered as a separate <script type="application/ld+json">
+ * tag for proper Schema.org validation
+ *
+ * SECURITY: Safe use of dangerouslySetInnerHTML
+ * - Content: Schema.org structured data (JSON.stringify)
+ * - Source: Validated Page schema (page.meta.schema or page.meta.structuredData)
+ * - Risk: None - JSON data cannot execute as code
+ * - Validation: Schema validation ensures correct structure
+ * - Purpose: Generate rich search results (SEO)
+ * - XSS Protection: type="application/ld+json" prevents script execution
+ * - Format: Safe serialization via JSON.stringify
+ *
+ * @param page - Page configuration
+ * @returns React fragment with script tags or undefined
+ */
+export function StructuredDataScript({
+  page,
+}: {
+  readonly page: Page
+}): Readonly<ReactElement | undefined> {
+  // Support both 'schema' (canonical) and 'structuredData' (test alias)
+  const structuredData = page.meta?.schema ?? page.meta?.structuredData
+  if (!structuredData) {
+    return undefined
+  }
+
+  // Type guard: ensure structuredData is an object
+  if (typeof structuredData !== 'object' || structuredData === null) {
+    return undefined
+  }
+
+  // Check if this is a direct Schema.org object (has @context and @type)
+  const isDirectSchemaObject = '@context' in structuredData && '@type' in structuredData
+
+  // Handle direct Schema.org object format
+  if (isDirectSchemaObject) {
+    return (
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{
+          __html: JSON.stringify(structuredData),
+        }}
+      />
+    )
+  }
+
+  // Handle orchestrator schema format (organization, faqPage, etc.)
+  const structuredDataTypes = Object.entries(structuredData).filter(
+    ([, value]) => value !== undefined && value !== null
+  )
+
+  if (structuredDataTypes.length === 0) {
+    return undefined
+  }
+
+  return (
+    <>
+      {structuredDataTypes.map(([key, value]) => (
+        <script
+          key={key}
+          type="application/ld+json"
+          dangerouslySetInnerHTML={{
+            __html: JSON.stringify(value),
+          }}
+        />
+      ))}
+    </>
+  )
+}