sovrium 0.0.2

package/src/presentation/ui/metadata/twitter-card-meta.tsx

@@ -0,0 +1,80 @@
+/**
+ * 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 { renderMetaTags } from './meta-utils'
+import type { Page } from '@/domain/models/app/pages'
+
+/**
+ * Twitter Card field mapping configuration
+ */
+const twitterCardFieldMapping = [
+  { key: 'card', getter: (tc: NonNullable<Page['meta']>['twitter']) => tc?.card },
+  { key: 'title', getter: (tc: NonNullable<Page['meta']>['twitter']) => tc?.title },
+  { key: 'description', getter: (tc: NonNullable<Page['meta']>['twitter']) => tc?.description },
+  { key: 'image', getter: (tc: NonNullable<Page['meta']>['twitter']) => tc?.image },
+  { key: 'image:alt', getter: (tc: NonNullable<Page['meta']>['twitter']) => tc?.imageAlt },
+  { key: 'site', getter: (tc: NonNullable<Page['meta']>['twitter']) => tc?.site },
+  { key: 'creator', getter: (tc: NonNullable<Page['meta']>['twitter']) => tc?.creator },
+  { key: 'player', getter: (tc: NonNullable<Page['meta']>['twitter']) => tc?.player },
+  { key: 'player:width', getter: (tc: NonNullable<Page['meta']>['twitter']) => tc?.playerWidth },
+  { key: 'player:height', getter: (tc: NonNullable<Page['meta']>['twitter']) => tc?.playerHeight },
+  {
+    key: 'app:name:iphone',
+    getter: (tc: NonNullable<Page['meta']>['twitter']) => tc?.appName?.iPhone,
+  },
+  { key: 'app:name:ipad', getter: (tc: NonNullable<Page['meta']>['twitter']) => tc?.appName?.iPad },
+  {
+    key: 'app:name:googleplay',
+    getter: (tc: NonNullable<Page['meta']>['twitter']) => tc?.appName?.googlePlay,
+  },
+  { key: 'app:id:iphone', getter: (tc: NonNullable<Page['meta']>['twitter']) => tc?.appId?.iPhone },
+  { key: 'app:id:ipad', getter: (tc: NonNullable<Page['meta']>['twitter']) => tc?.appId?.iPad },
+  {
+    key: 'app:id:googleplay',
+    getter: (tc: NonNullable<Page['meta']>['twitter']) => tc?.appId?.googlePlay,
+  },
+] as const
+
+/**
+ * Build Twitter Card field array from twitter card configuration
+ * Extracts all fields including app metadata for Twitter/X sharing
+ *
+ * @param twitterCard - Twitter card configuration
+ * @returns Array of field key-value pairs
+ */
+function buildTwitterCardFields(
+  twitterCard: NonNullable<Page['meta']>['twitter']
+): ReadonlyArray<{ readonly key: string; readonly value?: string | number }> {
+  return twitterCardFieldMapping.map(({ key, getter }) => ({
+    key,
+    value: getter(twitterCard),
+  }))
+}
+
+/**
+ * Render Twitter Card metadata tags
+ * Generates <meta name="twitter:*"> tags for Twitter/X sharing
+ * Supports both 'twitter' and 'twitterCard' field names for compatibility
+ *
+ * @param page - Page configuration
+ * @returns React fragment with Twitter meta tags
+ */
+export function TwitterCardMeta({
+  page,
+}: {
+  readonly page: Page
+}): Readonly<ReactElement | undefined> {
+  // Support both 'twitter' (canonical) and 'twitterCard' (test alias)
+  const twitterCard = page.meta?.twitter ?? page.meta?.twitterCard
+  if (!twitterCard) {
+    return undefined
+  }
+
+  const fields = buildTwitterCardFields(twitterCard)
+  return renderMetaTags({ fields, prefix: 'twitter', attributeType: 'name' })
+}

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

@@ -0,0 +1,43 @@
+/**
+ * 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 { createDefaultHomePageConfig } from '@/presentation/ui/pages/DefaultPageConfigs'
+import { DynamicPage } from '@/presentation/ui/pages/DynamicPage'
+import type { App } from '@/domain/models/app'
+
+/**
+ * DefaultHomePage component - Default home page displaying application information
+ *
+ * This is the fallback home page shown when no custom page configuration is provided.
+ * Displays the app name, optional version badge, and optional description in a centered layout.
+ *
+ * Uses DynamicPage pattern with theme-generated styles for consistency across the application.
+ *
+ * @param props - Component props
+ * @param props.app - Validated application data from AppSchema
+ * @param props.builtInAnalyticsEnabled - Whether built-in analytics should be enabled
+ * @returns React element with app information
+ */
+export function DefaultHomePage({
+  app,
+  builtInAnalyticsEnabled,
+  builtInAnalyticsSessionTimeout,
+}: {
+  readonly app: App
+  readonly builtInAnalyticsEnabled?: boolean
+  readonly builtInAnalyticsSessionTimeout?: number
+}): Readonly<ReactElement> {
+  const pageConfig = createDefaultHomePageConfig(app)
+  return (
+    <DynamicPage
+      page={pageConfig}
+      builtInAnalyticsEnabled={builtInAnalyticsEnabled}
+      builtInAnalyticsSessionTimeout={builtInAnalyticsSessionTimeout}
+    />
+  )
+}

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

@@ -0,0 +1,220 @@
+/**
+ * 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 { App } from '@/domain/models/app'
+import type { Component } from '@/domain/models/app/page/sections'
+import type { Page } from '@/domain/models/app/pages'
+
+/**
+ * Creates version badge component
+ */
+function createVersionBadge(version: string): Component {
+  return {
+    type: 'div',
+    props: {
+      className: 'flex justify-center',
+    },
+    children: [
+      {
+        type: 'span',
+        props: {
+          'data-testid': 'app-version-badge',
+          className:
+            'inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 border-transparent bg-primary text-primary-foreground hover:bg-primary/80',
+        },
+        children: [version],
+      },
+    ],
+  }
+}
+
+/**
+ * Creates app content components (version badge, heading, description)
+ */
+function createHomePageContent(app: App): ReadonlyArray<Component | string> {
+  return [
+    ...(app.version ? [createVersionBadge(app.version)] : []),
+    {
+      type: 'h1',
+      props: {
+        'data-testid': 'app-name-heading',
+        className: 'scroll-m-20 text-4xl font-extrabold tracking-tight lg:text-5xl text-center',
+      },
+      children: [app.name],
+    },
+    ...(app.description
+      ? [
+          {
+            type: 'p',
+            props: {
+              'data-testid': 'app-description',
+              className: 'text-xl text-muted-foreground text-center',
+            },
+            children: [app.description],
+          },
+        ]
+      : []),
+  ]
+}
+
+/**
+ * Creates a Page configuration for the default home page
+ *
+ * Renders:
+ * - Optional version badge
+ * - App name (H1 heading)
+ * - Optional app description
+ *
+ * Layout: Centered vertically and horizontally with max-width constraint
+ *
+ * @param app - Application data containing name, version, and description
+ * @returns Page configuration for DynamicPage rendering
+ */
+export function createDefaultHomePageConfig(app: App): Page {
+  return {
+    name: 'home',
+    path: '/',
+    meta: {
+      lang: 'en-US',
+      title: `${app.name} - Powered by Sovrium`,
+      description: app.description ?? `Welcome to ${app.name}`,
+    },
+    sections: [
+      {
+        type: 'div',
+        props: {
+          className: 'h-screen overflow-hidden bg-gradient-to-br from-gray-50 to-gray-100',
+        },
+        children: [
+          {
+            type: 'div',
+            props: {
+              className: 'container mx-auto px-4 sm:px-6 lg:px-8 h-full',
+            },
+            children: [
+              {
+                type: 'div',
+                props: {
+                  className: 'flex h-full flex-col items-center justify-center',
+                },
+                children: [
+                  {
+                    type: 'div',
+                    props: {
+                      className: 'w-full max-w-2xl space-y-6 text-center',
+                    },
+                    children: createHomePageContent(app),
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  }
+}
+
+/**
+ * Creates error page section with centered layout
+ */
+function createErrorSection(
+  code: string,
+  message: string,
+  codeColor: string = 'text-gray-900'
+): ReadonlyArray<Component> {
+  return [
+    {
+      type: 'div',
+      props: {
+        className: 'flex min-h-screen items-center justify-center bg-gray-50',
+      },
+      children: [
+        {
+          type: 'div',
+          props: {
+            className: 'text-center',
+          },
+          children: [
+            {
+              type: 'h1',
+              props: {
+                className: `mb-4 text-6xl font-bold ${codeColor}`,
+              },
+              children: [code],
+            },
+            {
+              type: 'p',
+              props: {
+                className: 'mb-8 text-xl text-gray-600',
+              },
+              children: [message],
+            },
+            {
+              type: 'link',
+              props: {
+                href: '/',
+                className: 'font-medium text-blue-600 hover:text-blue-700',
+              },
+              children: ['Go back home'],
+            },
+          ],
+        },
+      ],
+    },
+  ]
+}
+
+/**
+ * Creates a Page configuration for 404 Not Found error page
+ *
+ * Renders:
+ * - Large "404" heading
+ * - "Page not found" message
+ * - Link to return home
+ *
+ * Layout: Centered vertically and horizontally
+ *
+ * @returns Page configuration for DynamicPage rendering
+ */
+export function createNotFoundPageConfig(): Page {
+  return {
+    name: 'not_found',
+    path: '/404',
+    meta: {
+      lang: 'en-US',
+      title: '404 - Not Found',
+      description: 'Page not found',
+    },
+    sections: createErrorSection('404', 'Page not found'),
+  }
+}
+
+/**
+ * Creates a Page configuration for 500 Internal Server Error page
+ *
+ * Renders:
+ * - Large "500" heading (red color)
+ * - "Internal Server Error" message
+ * - Link to return home
+ *
+ * Layout: Centered vertically and horizontally
+ *
+ * @returns Page configuration for DynamicPage rendering
+ */
+export function createErrorPageConfig(): Page {
+  return {
+    name: 'error',
+    path: '/500',
+    meta: {
+      lang: 'en-US',
+      title: '500 - Internal Server Error',
+      description: 'Internal Server Error',
+    },
+    sections: createErrorSection('500', 'Internal Server Error', 'text-red-600'),
+  }
+}

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

@@ -0,0 +1,307 @@
+/**
+ * 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 { extractComponentMetaFromSections } from '@/presentation/ui/metadata/extract-component-meta'
+import { PageBodyScripts } from '@/presentation/ui/pages/PageBodyScripts'
+import { PageHead } from '@/presentation/ui/pages/PageHead'
+import { resolvePageLanguage } from '@/presentation/ui/pages/PageLangResolver'
+import { PageMain } from '@/presentation/ui/pages/PageMain'
+import { extractPageMetadata } from '@/presentation/ui/pages/PageMetadata'
+import { groupScriptsByPosition } from '@/presentation/ui/pages/PageScripts'
+import type { Components } from '@/domain/models/app/components'
+import type { Languages } from '@/domain/models/app/languages'
+import type { Page } from '@/domain/models/app/pages'
+import type { Theme } from '@/domain/models/app/theme'
+import type { RouteParams } from '@/domain/utils/route-matcher'
+
+type DynamicPageProps = {
+  readonly page: Page
+  readonly components?: Components
+  readonly theme?: Theme
+  readonly languages?: Languages
+  readonly detectedLanguage?: string
+  readonly routeParams?: RouteParams
+  readonly builtInAnalyticsEnabled?: boolean
+  readonly builtInAnalyticsSessionTimeout?: number
+}
+
+type DynamicPageHeadProps = {
+  readonly mergedPage: Page
+  readonly theme?: Theme
+  readonly directionStyles: string
+  readonly title: string
+  readonly description: string
+  readonly keywords?: string
+  readonly canonical?: string
+  readonly lang: string
+  readonly languages?: Languages
+  readonly scripts: ReturnType<typeof groupScriptsByPosition>
+  readonly builtInAnalyticsEnabled?: boolean
+  readonly builtInAnalyticsSessionTimeout?: number
+}
+
+/**
+ * Merges component metadata with page metadata
+ *
+ * @param page - Page configuration
+ * @param components - Available component templates
+ * @returns Page with merged metadata
+ */
+function mergeComponentMetaIntoPage(page: Page, components?: Components): Page {
+  const componentOpenGraph = extractComponentMetaFromSections(page.sections, components)
+
+  if (!componentOpenGraph || !page.meta) return page
+
+  return {
+    ...page,
+    meta: {
+      ...page.meta,
+      openGraph: {
+        ...page.meta.openGraph,
+        ...componentOpenGraph,
+      },
+    },
+  }
+}
+
+/**
+ * Renders the <head> section of DynamicPage
+ * Extracted to satisfy max-lines-per-function ESLint rule
+ */
+function DynamicPageHead({
+  mergedPage,
+  theme,
+  directionStyles,
+  title,
+  description,
+  keywords,
+  canonical,
+  lang,
+  languages,
+  scripts,
+  builtInAnalyticsEnabled,
+  builtInAnalyticsSessionTimeout,
+}: DynamicPageHeadProps): Readonly<ReactElement> {
+  const sessionTimeout = builtInAnalyticsSessionTimeout ?? 30
+  // Inline analytics script if enabled (contains /api/analytics/collect endpoint)
+  const analyticsScript = builtInAnalyticsEnabled
+    ? `(function(){
+"use strict";
+var E="/api/analytics/collect",A="${mergedPage.name || 'app'}",D=true,sessionTimeout=${sessionTimeout};
+if(D&&navigator.doNotTrack==="1")return;
+var u=function(){
+try{var s=new URLSearchParams(location.search);
+var d={p:location.pathname,t:document.title,r:document.referrer||void 0,
+sw:screen.width,sh:screen.height,
+us:s.get("utm_source")||void 0,um:s.get("utm_medium")||void 0,
+uc:s.get("utm_campaign")||void 0,ux:s.get("utm_content")||void 0,
+ut:s.get("utm_term")||void 0};
+var b=JSON.stringify(d);
+if(navigator.sendBeacon){navigator.sendBeacon(E,new Blob([b],{type:"application/json"}))}
+else{var x=new XMLHttpRequest();x.open("POST",E,true);x.setRequestHeader("Content-Type","application/json");x.send(b)}
+}catch(e){}};
+u();
+var op=history.pushState;
+history.pushState=function(){op.apply(this,arguments);u()};
+window.addEventListener("popstate",u);
+})();`
+    : undefined
+
+  return (
+    <head>
+      <PageHead
+        page={mergedPage}
+        theme={theme}
+        directionStyles={directionStyles}
+        title={title}
+        description={description}
+        keywords={keywords}
+        canonical={canonical}
+        lang={lang}
+        languages={languages}
+        scripts={scripts}
+      />
+      {analyticsScript && <script dangerouslySetInnerHTML={{ __html: analyticsScript }} />}
+    </head>
+  )
+}
+
+type DynamicPageBodyProps = {
+  readonly page: Page
+  readonly components?: Components
+  readonly theme?: Theme
+  readonly languages?: Languages
+  readonly direction: 'ltr' | 'rtl'
+  readonly scripts: ReturnType<typeof groupScriptsByPosition>
+  readonly lang: 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
+  readonly routeParams?: RouteParams
+}
+
+/**
+ * Generic parameter names that require context from path segments
+ * These parameters get prefixed with their context (e.g., product-id, user-key)
+ */
+const GENERIC_PARAM_NAMES = new Set(['id', 'key', 'uid', 'pk'])
+
+/**
+ * Converts route parameters to data attributes for testing
+ * Uses context-aware naming: generic params (id, key) get prefixed, descriptive ones (slug) don't
+ *
+ * @param routeParams - Route parameters extracted from URL
+ * @param path - Page path pattern (e.g., '/blog/:slug')
+ * @returns Data attributes object
+ */
+function buildDataAttributes(
+  routeParams: RouteParams | undefined,
+  path: string | undefined
+): Record<string, string> {
+  if (!routeParams || !path) {
+    return {}
+  }
+
+  const pathSegments = path.split('/').filter(Boolean)
+
+  return Object.entries(routeParams).reduce<Record<string, string>>((acc, [key, value]) => {
+    // Check if parameter name is generic and needs context
+    if (GENERIC_PARAM_NAMES.has(key)) {
+      // Generic parameter - add context from previous path segment
+      // e.g., /products/:id -> data-product-id
+      const paramIndex = pathSegments.findIndex((seg) => seg === `:${key}`)
+      if (paramIndex > 0) {
+        const contextSegment = pathSegments[paramIndex - 1]
+        if (!contextSegment) {
+          return { ...acc, [`data-${key}`]: value }
+        }
+        // Convert plural to singular (e.g., 'products' -> 'product')
+        const singularContext = contextSegment.endsWith('s')
+          ? contextSegment.slice(0, -1)
+          : contextSegment
+        return { ...acc, [`data-${singularContext}-${key}`]: value }
+      }
+      // No context available, use parameter name only
+      return { ...acc, [`data-${key}`]: value }
+    }
+    // Descriptive parameter - use as-is (e.g., /blog/:slug -> data-slug)
+    return { ...acc, [`data-${key}`]: value }
+  }, {})
+}
+
+/**
+ * Renders the <body> section of DynamicPage
+ * Extracted to satisfy max-lines-per-function ESLint rule
+ */
+function DynamicPageBody({
+  page,
+  components,
+  theme,
+  languages,
+  direction,
+  scripts,
+  lang,
+  bodyStyle,
+  routeParams,
+}: DynamicPageBodyProps): Readonly<ReactElement> {
+  const dataAttributes = buildDataAttributes(routeParams, page.path)
+
+  return (
+    <body
+      {...(bodyStyle && { style: bodyStyle })}
+      {...dataAttributes}
+    >
+      <PageBodyScripts
+        page={page}
+        theme={theme}
+        languages={languages}
+        direction={direction}
+        scripts={scripts}
+        position="start"
+      />
+      <PageMain
+        page={page}
+        sections={page.sections}
+        theme={theme}
+        components={components}
+        languages={languages}
+        currentLang={lang}
+      />
+      <PageBodyScripts
+        page={page}
+        theme={theme}
+        languages={languages}
+        direction={direction}
+        scripts={scripts}
+        position="end"
+      />
+    </body>
+  )
+}
+
+/**
+ * Renders a page from configuration as a complete HTML document
+ * Theme CSS is compiled globally at server startup via /assets/output.css
+ * Theme is still passed for font URLs, animation flags, and debugging
+ */
+export function DynamicPage({
+  page,
+  components,
+  theme,
+  languages,
+  detectedLanguage,
+  routeParams,
+  builtInAnalyticsEnabled,
+  builtInAnalyticsSessionTimeout,
+}: DynamicPageProps): Readonly<ReactElement> {
+  const metadata = extractPageMetadata(page, theme, languages, detectedLanguage)
+  const langConfig = resolvePageLanguage(page, languages, detectedLanguage)
+  const scripts = groupScriptsByPosition(page)
+  const pageWithMeta = mergeComponentMetaIntoPage(page, components)
+
+  return (
+    <html
+      lang={langConfig.lang}
+      dir={langConfig.direction}
+      {...(page.scripts && { 'data-features': JSON.stringify(page.scripts.features || {}) })}
+    >
+      <DynamicPageHead
+        mergedPage={pageWithMeta}
+        theme={theme}
+        directionStyles={langConfig.directionStyles}
+        title={metadata.title}
+        description={metadata.description}
+        keywords={metadata.keywords}
+        canonical={metadata.canonical}
+        lang={langConfig.lang}
+        languages={languages}
+        scripts={scripts}
+        builtInAnalyticsEnabled={builtInAnalyticsEnabled}
+        builtInAnalyticsSessionTimeout={builtInAnalyticsSessionTimeout}
+      />
+      <DynamicPageBody
+        page={page}
+        components={components}
+        theme={theme}
+        languages={languages}
+        direction={langConfig.direction}
+        scripts={scripts}
+        lang={langConfig.lang}
+        bodyStyle={metadata.bodyStyle}
+        routeParams={routeParams}
+      />
+    </html>
+  )
+}

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

@@ -0,0 +1,25 @@
+/**
+ * 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 { createErrorPageConfig } from '@/presentation/ui/pages/DefaultPageConfigs'
+import { DynamicPage } from '@/presentation/ui/pages/DynamicPage'
+
+/**
+ * ErrorPage component - 500 internal server error page
+ *
+ * This page is displayed when the server encounters an unexpected error.
+ * It provides a clear message and a link back to the homepage.
+ *
+ * Uses DynamicPage pattern with theme-generated styles for consistency across the application.
+ *
+ * @returns React element for 500 error page
+ */
+export function ErrorPage(): Readonly<ReactElement> {
+  const pageConfig = createErrorPageConfig()
+  return <DynamicPage page={pageConfig} />
+}

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

@@ -0,0 +1,25 @@
+/**
+ * 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 { createNotFoundPageConfig } from '@/presentation/ui/pages/DefaultPageConfigs'
+import { DynamicPage } from '@/presentation/ui/pages/DynamicPage'
+
+/**
+ * NotFoundPage component - 404 error page
+ *
+ * This page is displayed when a user navigates to a route that doesn't exist.
+ * It provides a clear message and a link back to the homepage.
+ *
+ * Uses DynamicPage pattern with theme-generated styles for consistency across the application.
+ *
+ * @returns React element for 404 error page
+ */
+export function NotFoundPage(): Readonly<ReactElement> {
+  const pageConfig = createNotFoundPageConfig()
+  return <DynamicPage page={pageConfig} />
+}