sovrium 0.0.2

package/src/domain/models/app/page/index.ts

@@ -0,0 +1,270 @@
+/**
+ * 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 { Schema } from 'effect'
+import { PageIdSchema } from './id'
+import { MetaSchema } from './meta'
+import { PageNameSchema } from './name'
+import { PagePathSchema } from './path'
+import { ScriptsSchema } from './scripts/scripts'
+import { SectionsSchema } from './sections'
+
+/**
+ * Page Schema
+ *
+ * Represents a complete page configuration with metadata, layout, sections, and scripts.
+ *
+ * Marketing and content pages with server-side rendering support. Pages use a component-based
+ * layout system with reusable component templates for building landing pages, about pages, pricing
+ * pages, and other public-facing content.
+ *
+ * ## Key Features
+ *
+ * - **Component-Based Layout**: Compose pages from reusable component templates defined at app level
+ * - **Theme Integration**: Pages use app.theme{} tokens via className utilities
+ * - **i18n Support**: Multi-language pages with $t: translation references
+ * - **Responsive Design**: Single page adapts to all viewports (mobile, tablet, desktop)
+ * - **SEO Optimization**: Comprehensive metadata, structured data, social sharing
+ *
+ * ## Architecture Notes
+ *
+ * - **Theme**: Defined at app level (app.theme{}), NOT in individual pages
+ * - **Components**: Defined at app level (app.components[]), NOT in individual pages
+ * - **Sections**: Reference component templates using $ref syntax with $vars substitution
+ * - **Styling**: Pages use className with theme tokens, not page-level theme
+ *
+ * ## Component References
+ *
+ * Sections can reference component templates defined at app level using $ref syntax:
+ *
+ * ```typescript
+ * {
+ *   sections: [
+ *     {
+ *       : '#/components/hero',
+ *       $vars: {
+ *         title: 'Welcome to Our Platform',
+ *         ctaLabel: 'Get Started'
+ *       }
+ *     }
+ *   ]
+ * }
+ * ```
+ *
+ * The component template is resolved and variables ($title, $ctaLabel) are substituted
+ * at runtime.
+ *
+ * ## Translation References
+ *
+ * Pages support internationalization via $t: translation references:
+ *
+ * ```typescript
+ * {
+ *   meta: {
+ *     lang: 'en',
+ *     title: '$t:hero.title'
+ *   },
+ *   sections: [
+ *     {
+ *       type: 'h1',
+ *       children: ['$t:hero.title']
+ *     }
+ *   ]
+ * }
+ * ```
+ *
+ * Translation keys resolve based on meta.lang from app.languages{} configuration.
+ *
+ * ## Responsive Design
+ *
+ * Pages adapt to different viewports using responsive className utilities:
+ *
+ * ```typescript
+ * {
+ *   type: 'section',
+ *   props: {
+ *     className: 'py-12 md:py-20 lg:py-32'
+ *   }
+ * }
+ * ```
+ *
+ * Mobile-first approach: base styles for mobile, breakpoints for larger screens.
+ *
+ * @example
+ * ```typescript
+ * // Minimal page with required properties
+ * const minimalPage: Page = {
+ *   name: 'Home',
+ *   path: '/',
+ *   meta: {
+ *     lang: 'en-US',
+ *     title: 'Welcome',
+ *     description: 'Welcome to our platform'
+ *   },
+ *   sections: []
+ * }
+ *
+ * // Complete page with all properties
+ * const completePage: Page = {
+ *   id: 'homepage',
+ *   name: 'Home',
+ *   path: '/',
+ *   meta: {
+ *     lang: 'en-US',
+ *     title: 'Welcome',
+ *     description: 'Welcome to our platform',
+ *     openGraph: {
+ *       title: 'Welcome to Our Platform',
+ *       type: 'website',
+ *       url: 'https://example.com',
+ *       image: 'https://example.com/og-image.jpg'
+ *     }
+ *   },
+ *   sections: [
+ *     {
+ *       : '#/components/hero',
+ *       $vars: {
+ *         title: 'Welcome',
+ *         ctaLabel: 'Get Started'
+ *       }
+ *     }
+ *   ],
+ *   scripts: {
+ *     features: {
+ *       analytics: true
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link https://schema.org Schema.org} for structured data
+ * @see {@link MetaSchema} for metadata configuration
+ * @see {@link SectionsSchema} for sections configuration
+ * @see {@link ScriptsSchema} for scripts configuration
+ */
+export const PageSchema = Schema.Struct({
+  /**
+   * Optional unique identifier for the page
+   *
+   * Used for internal references and tracking
+   */
+  id: Schema.optional(PageIdSchema),
+
+  /**
+   * Human-readable name for the page
+   *
+   * Used for identification in admin interfaces and as internal identifier.
+   * Required field that serves as a unique identifier separate from the URL path.
+   *
+   * @example "home"
+   * @example "about"
+   */
+  name: PageNameSchema,
+
+  /**
+   * URL path where the page is accessible
+   *
+   * - Root path: `/` (homepage)
+   * - Nested paths: `/about`, `/products/pricing`
+   *
+   * @example "/"
+   * @example "/about"
+   * @example "/products/pricing"
+   */
+  path: PagePathSchema,
+
+  /**
+   * Page metadata for SEO, social sharing, and analytics
+   *
+   * Optional - if not provided, uses default metadata based on page name/path
+   *
+   * Includes:
+   * - Basic SEO (title, description, keywords)
+   * - Social media (Open Graph, Twitter Card)
+   * - Structured data (Schema.org)
+   * - Performance hints (preload, DNS prefetch)
+   * - Analytics configuration
+   */
+  meta: Schema.optional(MetaSchema),
+
+  /**
+   * Page sections containing content
+   *
+   * Sections can be:
+   * - Direct components: { type, props, children }
+   * - Component references: { $ref, $vars }
+   *
+   * Component references resolve to app.components[] with variable substitution
+   */
+  sections: SectionsSchema,
+
+  /**
+   * Optional client-side scripts and features
+   *
+   * Manages:
+   * - Feature flags (analytics, chat widget)
+   * - External scripts (CDN resources)
+   * - Inline scripts (custom JavaScript)
+   * - Client configuration
+   */
+  scripts: Schema.optional(ScriptsSchema),
+
+  /**
+   * Optional page-level variables for substitution in sections
+   *
+   * Variables can be referenced in section content, props, and children using
+   * $variableName syntax. These variables are substituted at runtime.
+   *
+   * Page-level variables provide values for sections without component references.
+   * They complement component-level vars (from $ref with $vars) for direct sections.
+   *
+   * @example
+   * ```typescript
+   * {
+   *   vars: {
+   *     siteName: 'Sovrium',
+   *     primaryColor: 'blue'
+   *   },
+   *   sections: [
+   *     {
+   *       type: 'heading',
+   *       content: 'Welcome to $siteName'  // → 'Welcome to Sovrium'
+   *     },
+   *     {
+   *       type: 'button',
+   *       props: {
+   *         className: 'bg-$primaryColor'  // → 'bg-blue'
+   *       }
+   *     }
+   *   ]
+   * }
+   * ```
+   */
+  vars: Schema.optional(
+    Schema.Record({
+      key: Schema.String,
+      value: Schema.Union(Schema.String, Schema.Number, Schema.Boolean),
+    })
+  ),
+}).pipe(
+  Schema.annotations({
+    identifier: 'Page',
+    title: 'Page',
+    description:
+      'Complete page configuration with metadata, layout, sections, and scripts. Pages use a component-based layout system with reusable component templates.',
+  })
+)
+
+/**
+ * TypeScript type for a Page
+ */
+export type Page = typeof PageSchema.Type
+
+/**
+ * TypeScript type for an encoded Page (before validation)
+ */
+export type PageEncoded = typeof PageSchema.Encoded

package/src/domain/models/app/page/meta/analytics.ts

@@ -0,0 +1,248 @@
+/**
+ * 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 { Schema } from 'effect'
+
+/**
+ * Analytics provider name
+ *
+ * 6 supported analytics platforms:
+ * - google: Google Analytics 4 (most popular, 60% market share)
+ * - plausible: Privacy-focused, GDPR-compliant, no cookies
+ * - matomo: Open-source, self-hosted, privacy-focused
+ * - fathom: Privacy-first, simple, GDPR-compliant
+ * - posthog: Product analytics, session replay, feature flags
+ * - mixpanel: Product analytics, funnel analysis, cohort analysis
+ */
+export const AnalyticsProviderNameSchema = Schema.Literal(
+  'google',
+  'plausible',
+  'matomo',
+  'fathom',
+  'posthog',
+  'mixpanel'
+).annotations({
+  description: 'Analytics provider name',
+})
+
+/**
+ * Analytics script configuration
+ *
+ * External JavaScript file to load for analytics provider.
+ *
+ * Required properties:
+ * - src: Script source URL (CDN or provider-hosted)
+ *
+ * Optional properties:
+ * - async: Load asynchronously (default: true, recommended for analytics)
+ * - defer: Defer execution until DOM loaded
+ */
+export const AnalyticsScriptSchema = Schema.Struct({
+  src: Schema.String.annotations({
+    description: 'Script source URL',
+    format: 'uri',
+  }),
+  async: Schema.optional(
+    Schema.Boolean.annotations({
+      description: 'Load script asynchronously',
+      default: true,
+    })
+  ),
+  defer: Schema.optional(
+    Schema.Boolean.annotations({
+      description: 'Defer script execution',
+    })
+  ),
+}).annotations({
+  description: 'Analytics script',
+})
+
+/**
+ * Analytics provider configuration
+ *
+ * Defines a single analytics provider with scripts, initialization, and settings.
+ *
+ * Required properties:
+ * - name: Provider name (google, plausible, matomo, fathom, posthog, mixpanel)
+ *
+ * Optional properties:
+ * - enabled: Whether provider is active (default: true)
+ * - scripts: Array of external scripts to load
+ * - initScript: Inline JavaScript for provider initialization
+ * - dnsPrefetch: Domain to DNS prefetch (performance optimization)
+ * - config: Provider-specific configuration (tracking IDs, privacy settings, features)
+ *
+ * Common pattern:
+ * 1. Load external script(s) from CDN (scripts array)
+ * 2. Run initialization code (initScript)
+ * 3. Configure with provider settings (config object)
+ *
+ * Performance optimization:
+ * - async: true (default) - non-blocking script load
+ * - dnsPrefetch: Early DNS resolution for faster script load
+ *
+ * @example
+ * ```typescript
+ * const googleAnalytics = {
+ *   name: 'google',
+ *   enabled: true,
+ *   scripts: [
+ *     {
+ *       src: 'https://www.googletagmanager.com/gtag/js?id=G-XXXXX',
+ *       async: true
+ *     }
+ *   ],
+ *   initScript: `
+ *     window.dataLayer = window.dataLayer || [];
+ *     function gtag(){dataLayer.push(arguments);}
+ *     gtag('js', new Date());
+ *     gtag('config', 'G-XXXXX');
+ *   `,
+ *   dnsPrefetch: 'https://www.googletagmanager.com',
+ *   config: {
+ *     trackingId: 'G-XXXXX',
+ *     anonymizeIp: true
+ *   }
+ * }
+ *
+ * const plausible = {
+ *   name: 'plausible',
+ *   enabled: true,
+ *   scripts: [
+ *     {
+ *       src: 'https://plausible.io/js/script.js',
+ *       async: true,
+ *       defer: true
+ *     }
+ *   ],
+ *   dnsPrefetch: 'https://plausible.io',
+ *   config: {
+ *     domain: 'example.com'
+ *   }
+ * }
+ * ```
+ *
+ * @see specs/app/pages/meta/analytics/analytics.schema.json
+ */
+export const AnalyticsProviderSchema = Schema.Struct({
+  name: AnalyticsProviderNameSchema,
+  enabled: Schema.optional(
+    Schema.Boolean.annotations({
+      description: 'Whether this provider is enabled',
+      default: true,
+    })
+  ),
+  scripts: Schema.optional(Schema.Array(AnalyticsScriptSchema)),
+  initScript: Schema.optional(
+    Schema.String.annotations({
+      description: 'Inline JavaScript to initialize the analytics',
+    })
+  ),
+  dnsPrefetch: Schema.optional(
+    Schema.String.annotations({
+      description: 'Domain to DNS prefetch for this provider',
+      format: 'uri',
+    })
+  ),
+  config: Schema.optional(
+    Schema.Record({
+      key: Schema.String,
+      value: Schema.Unknown,
+    }).annotations({
+      description: 'Provider-specific configuration',
+    })
+  ),
+}).annotations({
+  description: 'Analytics provider',
+})
+
+/**
+ * Analytics configuration for multiple providers
+ *
+ * Manages analytics tracking across one or more analytics platforms.
+ * Supports simultaneous tracking with multiple providers for:
+ * - Transition periods (migrating between providers)
+ * - Compliance (privacy-friendly for EU, full-featured for others)
+ * - Comparison (data quality validation)
+ * - Redundancy (backup if one fails)
+ *
+ * Required properties:
+ * - providers: Array of analytics provider configurations
+ *
+ * Provider categories:
+ * 1. **Privacy-focused** (GDPR-compliant, no cookies):
+ *    - plausible: < 1KB, simple dashboards
+ *    - matomo: Open-source, self-hosted
+ *    - fathom: Minimal, privacy-first
+ *
+ * 2. **Full-featured** (detailed analytics):
+ *    - google: Free, most popular, integrates with Ads
+ *    - posthog: Product analytics, session replay, feature flags
+ *    - mixpanel: Funnel analysis, cohorts, retention
+ *
+ * Integration notes:
+ * - All scripts load asynchronously (non-blocking)
+ * - DNS prefetch optimizes external script loading
+ * - Config object flexible (additionalProperties: true)
+ * - Each provider independent (isolated initialization)
+ *
+ * @example
+ * ```typescript
+ * const analytics = {
+ *   providers: [
+ *     // Privacy-friendly for all users
+ *     {
+ *       name: 'plausible',
+ *       enabled: true,
+ *       scripts: [
+ *         {
+ *           src: 'https://plausible.io/js/script.js',
+ *           async: true
+ *         }
+ *       ],
+ *       config: {
+ *         domain: 'example.com'
+ *       }
+ *     },
+ *     // Full-featured for detailed insights
+ *     {
+ *       name: 'google',
+ *       enabled: true,
+ *       scripts: [
+ *         {
+ *           src: 'https://www.googletagmanager.com/gtag/js?id=G-XXXXX',
+ *           async: true
+ *         }
+ *       ],
+ *       initScript: `
+ *         window.dataLayer = window.dataLayer || [];
+ *         function gtag(){dataLayer.push(arguments);}
+ *         gtag('js', new Date());
+ *         gtag('config', 'G-XXXXX');
+ *       `,
+ *       config: {
+ *         trackingId: 'G-XXXXX',
+ *         anonymizeIp: true
+ *       }
+ *     }
+ *   ]
+ * }
+ * ```
+ *
+ * @see specs/app/pages/meta/analytics/analytics.schema.json
+ */
+export const AnalyticsSchema = Schema.Struct({
+  providers: Schema.Array(AnalyticsProviderSchema),
+}).annotations({
+  title: 'Analytics Configuration',
+  description: 'Configuration for analytics providers',
+})
+
+export type AnalyticsProviderName = Schema.Schema.Type<typeof AnalyticsProviderNameSchema>
+export type AnalyticsScript = Schema.Schema.Type<typeof AnalyticsScriptSchema>
+export type AnalyticsProvider = Schema.Schema.Type<typeof AnalyticsProviderSchema>
+export type Analytics = Schema.Schema.Type<typeof AnalyticsSchema>

package/src/domain/models/app/page/meta/custom-elements.ts

@@ -0,0 +1,180 @@
+/**
+ * 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 { Schema } from 'effect'
+
+/**
+ * Custom head element type
+ *
+ * 5 HTML elements allowed in <head>:
+ * - meta: Metadata (charset, viewport, theme-color, etc.)
+ * - link: External resources (stylesheets, preconnect, dns-prefetch)
+ * - script: JavaScript files or inline code
+ * - style: Inline CSS styles
+ * - base: Base URL for relative URLs
+ */
+export const CustomElementTypeSchema = Schema.Literal(
+  'meta',
+  'link',
+  'script',
+  'style',
+  'base'
+).annotations({
+  description: 'HTML element type',
+})
+
+/**
+ * Custom head element
+ *
+ * Allows adding arbitrary HTML elements to the page <head> section.
+ * Useful for custom meta tags, third-party integrations, or special configurations.
+ *
+ * Required properties:
+ * - type: HTML element type (meta, link, script, style, base)
+ *
+ * Optional properties:
+ * - attrs: Object of HTML attributes (kebab-case keys, string values)
+ * - content: Inner content for script or style elements
+ *
+ * Common use cases:
+ * - Custom meta tags: theme-color, apple-mobile-web-app-capable
+ * - Preconnect/DNS prefetch: Speed up external resource loading
+ * - Third-party scripts: Analytics, chat widgets not covered by analytics config
+ * - Inline styles: Critical CSS for above-the-fold content
+ *
+ * Attribute naming:
+ * - Keys must be kebab-case (data-theme, http-equiv, charset)
+ * - Values are always strings
+ * - Pattern: ^[a-zA-Z][a-zA-Z0-9-]*$
+ *
+ * @example
+ * ```typescript
+ * const themeColorMeta = {
+ *   type: 'meta',
+ *   attrs: {
+ *     name: 'theme-color',
+ *     content: '#FFAF00'
+ *   }
+ * }
+ *
+ * const viewportMeta = {
+ *   type: 'meta',
+ *   attrs: {
+ *     name: 'viewport',
+ *     content: 'width=device-width, initial-scale=1'
+ *   }
+ * }
+ *
+ * const preconnectLink = {
+ *   type: 'link',
+ *   attrs: {
+ *     rel: 'preconnect',
+ *     href: 'https://fonts.gstatic.com'
+ *   }
+ * }
+ *
+ * const inlineScript = {
+ *   type: 'script',
+ *   content: "console.log('Custom script');"
+ * }
+ *
+ * const criticalCSS = {
+ *   type: 'style',
+ *   content: 'body { margin: 0; padding: 0; }'
+ * }
+ * ```
+ *
+ * @see specs/app/pages/meta/custom-elements/custom-elements.schema.json
+ */
+export const CustomElementSchema = Schema.Struct({
+  type: CustomElementTypeSchema,
+  attrs: Schema.optional(
+    Schema.Record({
+      key: Schema.String.pipe(
+        Schema.pattern(/^[a-zA-Z][a-zA-Z0-9-]*$/, {
+          message: () =>
+            'Attribute name must start with a letter and contain only letters, numbers, and hyphens (kebab-case)',
+        })
+      ),
+      value: Schema.String,
+    }).annotations({
+      description: 'Element attributes',
+    })
+  ),
+  content: Schema.optional(
+    Schema.String.annotations({
+      description: 'Inner content for script or style elements',
+    })
+  ),
+}).annotations({
+  description: 'Custom head element',
+})
+
+/**
+ * Additional custom elements to add to the page head
+ *
+ * Array of custom HTML elements injected into the <head> section.
+ * Provides escape hatch for custom meta tags, scripts, styles not
+ * covered by dedicated schemas (analytics, favicons, social, etc.).
+ *
+ * Common use cases:
+ * - Mobile web app meta tags (apple-mobile-web-app-capable, mobile-web-app-capable)
+ * - Theme customization (theme-color, color-scheme)
+ * - Performance optimization (preconnect, dns-prefetch for custom CDNs)
+ * - Third-party integrations (chat widgets, analytics not in analytics schema)
+ * - Critical CSS (inline styles for above-the-fold content)
+ *
+ * Order matters:
+ * - Meta tags: First (charset, viewport)
+ * - Preconnect/DNS prefetch: Early (before scripts that use those domains)
+ * - Styles: Before visual content
+ * - Scripts: Last (unless critical)
+ *
+ * @example
+ * ```typescript
+ * const customElements = [
+ *   // Mobile web app configuration
+ *   {
+ *     type: 'meta',
+ *     attrs: {
+ *       name: 'apple-mobile-web-app-capable',
+ *       content: 'yes'
+ *     }
+ *   },
+ *   {
+ *     type: 'meta',
+ *     attrs: {
+ *       name: 'theme-color',
+ *       content: '#FFAF00'
+ *     }
+ *   },
+ *   // Performance optimization
+ *   {
+ *     type: 'link',
+ *     attrs: {
+ *       rel: 'preconnect',
+ *       href: 'https://fonts.gstatic.com'
+ *     }
+ *   },
+ *   // Critical CSS
+ *   {
+ *     type: 'style',
+ *     content: 'body{margin:0}*{box-sizing:border-box}'
+ *   }
+ * ]
+ * ```
+ *
+ * @see specs/app/pages/meta/custom-elements/custom-elements.schema.json
+ */
+export const CustomElementsSchema = Schema.Array(CustomElementSchema).annotations({
+  title: 'Custom Head Elements',
+  description: 'Additional custom elements to add to the page head',
+})
+
+export type CustomElementType = Schema.Schema.Type<typeof CustomElementTypeSchema>
+export type CustomElement = Schema.Schema.Type<typeof CustomElementSchema>
+export type CustomElements = Schema.Schema.Type<typeof CustomElementsSchema>