sovrium 0.0.2

package/src/domain/models/app/page/scripts/features.ts

@@ -0,0 +1,135 @@
+/**
+ * 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'
+
+/**
+ * Feature configuration with enabled flag and custom config
+ *
+ * Complex feature definition with:
+ * - enabled: Boolean toggle for the feature
+ * - config: Flexible configuration object (additionalProperties: true)
+ *
+ * Use this when a feature requires additional configuration beyond a simple boolean.
+ *
+ * @example
+ * ```typescript
+ * const animations = {
+ *   enabled: true,
+ *   config: {
+ *     duration: 300,
+ *     easing: 'ease-in-out'
+ *   }
+ * }
+ * ```
+ */
+export const FeatureConfigSchema = Schema.Struct({
+  enabled: Schema.optional(
+    Schema.Boolean.annotations({
+      description: 'Whether the feature is enabled',
+    })
+  ),
+  config: Schema.optional(
+    Schema.Record({
+      key: Schema.String,
+      value: Schema.Unknown,
+    }).annotations({
+      description: 'Feature-specific configuration data',
+    })
+  ),
+}).annotations({
+  description: 'Feature configuration with enabled flag and custom config',
+})
+
+/**
+ * Feature value - either a boolean flag or a configuration object
+ *
+ * Supports two patterns:
+ * 1. Simple boolean: true/false for basic feature toggles
+ * 2. Configuration object: { enabled, config } for features requiring settings
+ *
+ * @example
+ * ```typescript
+ * const features = {
+ *   darkMode: true,  // Simple boolean
+ *   liveChat: {      // Complex configuration
+ *     enabled: true,
+ *     config: {
+ *       provider: 'intercom',
+ *       appId: 'abc123'
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export const FeatureValueSchema = Schema.Union(
+  Schema.Boolean.annotations({
+    description: 'Simple feature flag',
+  }),
+  FeatureConfigSchema
+).annotations({
+  description: 'Feature value - either a boolean flag or a configuration object',
+})
+
+/**
+ * Client-side feature toggles
+ *
+ * Record of feature flags controlling client-side behavior.
+ * Each feature can be either a simple boolean or a complex configuration object.
+ *
+ * Common use cases:
+ * - darkMode: Enable dark theme
+ * - animations: Control UI animations
+ * - analytics: Toggle tracking
+ * - cookieConsent: GDPR compliance
+ * - liveChat: Customer support widget
+ *
+ * Features are:
+ * - Accessible in client JavaScript as window.FEATURES
+ * - Stored in data-* attributes for CSS/JS access
+ * - Persisted in localStorage for user preferences
+ *
+ * @example
+ * ```typescript
+ * const features = {
+ *   darkMode: true,
+ *   animations: {
+ *     enabled: true,
+ *     config: {
+ *       duration: 300,
+ *       easing: 'ease-in-out'
+ *     }
+ *   },
+ *   cookieConsent: false,
+ *   liveChat: {
+ *     enabled: true,
+ *     config: {
+ *       provider: 'intercom',
+ *       appId: 'abc123'
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @see specs/app/pages/scripts/features/features.schema.json
+ */
+export const FeaturesSchema = Schema.Record({
+  key: Schema.String.pipe(
+    Schema.pattern(/^[a-zA-Z][a-zA-Z0-9]*$/, {
+      message: () =>
+        'Feature name must be camelCase starting with a letter (e.g., darkMode, liveChat, cookieConsent)',
+    })
+  ),
+  value: FeatureValueSchema,
+}).annotations({
+  title: 'Feature Flags',
+  description: 'Client-side feature toggles',
+})
+
+export type FeatureConfig = Schema.Schema.Type<typeof FeatureConfigSchema>
+export type FeatureValue = Schema.Schema.Type<typeof FeatureValueSchema>
+export type Features = Schema.Schema.Type<typeof FeaturesSchema>

package/src/domain/models/app/page/scripts/inline-scripts.ts

@@ -0,0 +1,114 @@
+/**
+ * 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 { ScriptPositionSchema } from './external-scripts'
+
+/**
+ * Inline JavaScript code snippet
+ *
+ * Defines an inline script tag with JavaScript code.
+ *
+ * Required properties:
+ * - code: JavaScript code to execute (raw JS, no <script> tags)
+ *
+ * Optional properties:
+ * - position: Where to insert script (head, body-start, body-end)
+ * - async: Wrap code in async IIFE (async function)
+ *
+ * Use cases:
+ * - Global config: window.APP_CONFIG initialization
+ * - Theme restoration: Apply saved theme before paint (avoid FOUC)
+ * - Analytics: Tracking code initialization
+ * - Feature detection: Check browser capabilities
+ *
+ * Performance considerations:
+ * - Pros: No network request, executes immediately
+ * - Cons: Not cached, repeated on every page load
+ * - Recommendation: Keep inline scripts < 1KB, use external for larger code
+ *
+ * Security (CSP):
+ * - Inline scripts require 'unsafe-inline' or nonce/hash in CSP header
+ * - Use nonce: <script nonce="random123">...</script>
+ * - Or hash: CSP header script-src 'sha256-{hash}'
+ *
+ * @example
+ * ```typescript
+ * const configScript = {
+ *   code: "window.config = { apiUrl: 'https://api.example.com' };",
+ *   position: 'head'
+ * }
+ *
+ * const analyticsScript = {
+ *   code: "console.log('Page loaded');",
+ *   position: 'body-end'
+ * }
+ * ```
+ *
+ * @see specs/app/pages/scripts/inline-scripts/inline-scripts.schema.json
+ */
+export const InlineScriptSchema = Schema.Struct({
+  code: Schema.String.annotations({
+    description: 'JavaScript code to execute',
+  }),
+  position: Schema.optional(ScriptPositionSchema),
+  async: Schema.optional(
+    Schema.Boolean.annotations({
+      description: 'Wrap in async IIFE',
+      default: false,
+    })
+  ),
+}).annotations({
+  description: 'Inline JavaScript code snippet',
+})
+
+/**
+ * Inline JavaScript code snippets
+ *
+ * Array of inline scripts injected into the HTML document.
+ * Scripts execute in order (synchronous by default).
+ *
+ * Common use cases:
+ * - Configuration: window.APP_CONFIG = {...}
+ * - Theme restoration: Apply dark mode before paint
+ * - Analytics initialization: gtag(), Plausible tracking
+ * - Event listeners: DOMContentLoaded handlers
+ *
+ * Best practices:
+ * - Keep scripts small (< 1KB) - larger code should be external
+ * - Use for critical initialization only (theme, config)
+ * - Position head scripts for pre-render logic
+ * - Position body-end scripts for post-render logic
+ *
+ * Security:
+ * - Inline scripts require CSP nonce or hash
+ * - Escape user input to prevent XSS
+ * - Never inject untrusted code
+ *
+ * @example
+ * ```typescript
+ * const inlineScripts = [
+ *   {
+ *     code: "window.config = { apiUrl: 'https://api.example.com' };",
+ *     position: 'head'
+ *   },
+ *   {
+ *     code: "console.log('Page loaded');",
+ *     position: 'body-end'
+ *   }
+ * ]
+ * ```
+ *
+ * @see specs/app/pages/scripts/inline-scripts/inline-scripts.schema.json
+ */
+export const InlineScriptsSchema = Schema.Array(InlineScriptSchema).annotations({
+  title: 'Inline Scripts',
+  description: 'Inline JavaScript code snippets',
+})
+
+export type InlineScript = Schema.Schema.Type<typeof InlineScriptSchema>
+export type InlineScripts = Schema.Schema.Type<typeof InlineScriptsSchema>

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

@@ -0,0 +1,102 @@
+/**
+ * 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 { ExternalScriptsSchema } from './external-scripts'
+import { FeaturesSchema } from './features'
+import { InlineScriptsSchema } from './inline-scripts'
+
+/**
+ * Client scripts configuration
+ *
+ * Orchestrates all client-side scripts, features, and configuration.
+ *
+ * Properties (all optional):
+ * - features: Client-side feature toggles (boolean flags or config objects)
+ * - externalScripts: External JavaScript dependencies from CDN
+ * - inlineScripts: Inline JavaScript code snippets
+ * - config: Client-side configuration data (flexible schema)
+ *
+ * Use cases:
+ * - SPA initialization: Load framework (Alpine.js, htmx) + inline config
+ * - Analytics: External script (Google Analytics) + inline tracking code
+ * - Feature flags: Toggle features based on environment or user preferences
+ * - Third-party services: Auth0, Sentry, Intercom configuration
+ *
+ * Loading order:
+ * 1. External scripts (async/defer respected)
+ * 2. Inline scripts (execute after external scripts load)
+ * 3. Config available as window.APP_CONFIG
+ *
+ * Performance:
+ * - Load scripts only where needed (per-page customization)
+ * - Use async for non-dependent scripts (analytics, ads)
+ * - Use defer for frameworks (preserve order, non-blocking)
+ * - Keep inline scripts < 1KB (larger code should be external)
+ *
+ * Security:
+ * - Config is public (sent to client), NO SECRETS
+ * - Never include API keys, passwords, private tokens in config
+ * - Use HTTPS for external scripts (no http://)
+ * - Add integrity hashes for CDN scripts
+ * - Inline scripts require CSP nonce or hash
+ *
+ * @example
+ * ```typescript
+ * const scripts = {
+ *   features: {
+ *     darkMode: true,
+ *     animations: {
+ *       enabled: true,
+ *       config: {
+ *         duration: 300,
+ *         easing: 'ease-in-out'
+ *       }
+ *     },
+ *     analytics: false
+ *   },
+ *   externalScripts: [
+ *     {
+ *       src: 'https://cdn.example.com/script.js',
+ *       async: true
+ *     }
+ *   ],
+ *   inlineScripts: [
+ *     {
+ *       code: "console.log('Page loaded');",
+ *       position: 'body-end'
+ *     }
+ *   ],
+ *   config: {
+ *     apiUrl: 'https://api.example.com',
+ *     environment: 'production'
+ *   }
+ * }
+ * ```
+ *
+ * @see specs/app/pages/scripts/scripts.schema.json
+ */
+export const ScriptsSchema = Schema.Struct({
+  features: Schema.optional(FeaturesSchema),
+  externalScripts: Schema.optional(ExternalScriptsSchema),
+  // Support 'external' as an alias for 'externalScripts' (test shorthand)
+  external: Schema.optional(ExternalScriptsSchema),
+  inlineScripts: Schema.optional(InlineScriptsSchema),
+  config: Schema.optional(
+    Schema.Record({
+      key: Schema.String,
+      value: Schema.Unknown,
+    }).annotations({
+      description: 'Client-side configuration data',
+    })
+  ),
+}).annotations({
+  title: 'Client Scripts Configuration',
+  description: 'Client-side scripts, features, and external dependencies',
+})
+
+export type Scripts = Schema.Schema.Type<typeof ScriptsSchema>

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

@@ -0,0 +1,298 @@
+/**
+ * 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 { ComponentPropsSchema } from '../component/common/component-props'
+import { ComponentReferenceSchema } from '../component/common/component-reference'
+import { InteractionsSchema } from './common/interactions/interactions'
+import { ResponsiveSchema } from './common/responsive'
+
+/**
+ * Component type enum for page sections
+ *
+ * Comprehensive set of component types for building pages:
+ * - Layout: section, container, flex, grid, div, modal, sidebar, hero, navigation, header, footer, main, article, aside, nav
+ * - Content: text, single-line-text, heading, paragraph, h1, h2, h3, h4, h5, h6, icon, image, avatar, thumbnail, hero-image, customHTML, span, p, code, pre
+ * - Interactive: button, link, a, accordion, dropdown
+ * - Grouping: card, badge, timeline, list-item, speech-bubble, card-with-header, card-header, card-body, card-footer
+ * - Media: video, audio, iframe
+ * - Forms: form, input
+ * - Feedback: toast, spinner, alert
+ * - UI Elements: fab (floating action button), list
+ */
+export const ComponentTypeSchema = Schema.Literal(
+  'section',
+  'container',
+  'flex',
+  'grid',
+  'card',
+  'card-with-header',
+  'card-header',
+  'card-body',
+  'card-footer',
+  'text',
+  'single-line-text',
+  'heading',
+  'paragraph',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'icon',
+  'image',
+  'img',
+  'avatar',
+  'thumbnail',
+  'hero-image',
+  'button',
+  'link',
+  'a',
+  'timeline',
+  'accordion',
+  'badge',
+  'speech-bubble',
+  'customHTML',
+  'video',
+  'audio',
+  'iframe',
+  'form',
+  'input',
+  'div',
+  'span',
+  'modal',
+  'sidebar',
+  'toast',
+  'hero',
+  'hero-section',
+  'fab',
+  'spinner',
+  'list',
+  'list-item',
+  'dropdown',
+  'navigation',
+  'alert',
+  'p',
+  'code',
+  'pre',
+  'header',
+  'footer',
+  'main',
+  'article',
+  'aside',
+  'nav',
+  'responsive-grid'
+).annotations({
+  description: 'Component type for page building',
+})
+
+/**
+ * Direct component definition for page sections
+ *
+ * A component can be either inline (direct definition) or referenced (component template).
+ * Direct components allow full customization without creating a reusable component template.
+ *
+ * Required properties:
+ * - type: Component type (17 options)
+ *
+ * Optional properties:
+ * - props: Component properties (className, id, style, etc.)
+ * - children: Nested child components (recursive, unlimited depth)
+ * - content: Text content (for text components)
+ * - interactions: Interactive behaviors (hover, click, scroll, entrance)
+ * - responsive: Breakpoint-specific overrides for responsive design
+ *
+ * @example
+ * ```typescript
+ * const component = {
+ *   type: 'section',
+ *   props: {
+ *     id: 'hero',
+ *     className: 'min-h-screen bg-gradient'
+ *   },
+ *   children: [
+ *     {
+ *       type: 'text',
+ *       props: { level: 'h1' },
+ *       content: 'Welcome'
+ *     }
+ *   ],
+ *   interactions: {
+ *     entrance: { animation: 'fadeIn' }
+ *   },
+ *   responsive: {
+ *     md: {
+ *       props: { className: 'min-h-screen bg-gradient-2xl' }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @see specs/app/pages/sections/sections.schema.json
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- Recursive schema with suspended types requires any for circular reference resolution
+export const ComponentSchema: Schema.Schema<any, any, never> = Schema.Struct({
+  type: ComponentTypeSchema,
+  props: Schema.optional(ComponentPropsSchema),
+  children: Schema.optional(
+    Schema.Array(
+      Schema.Union(
+        Schema.suspend(() => SectionItemSchema).pipe(
+          Schema.annotations({
+            identifier: 'SectionItem',
+          })
+        ),
+        Schema.String
+      )
+    ).pipe(
+      Schema.annotations({
+        identifier: 'Children',
+        description: 'Array of child components or text strings',
+      })
+    )
+  ),
+  content: Schema.optional(
+    Schema.Union(
+      Schema.String,
+      Schema.Record({ key: Schema.String, value: Schema.Unknown })
+    ).annotations({
+      description:
+        'Text content for text components, or structured content object (e.g., { button: { text, animation } })',
+    })
+  ),
+  interactions: Schema.optional(InteractionsSchema),
+  responsive: Schema.optional(ResponsiveSchema),
+  i18n: Schema.optional(
+    Schema.Record({
+      key: Schema.String.pipe(
+        Schema.pattern(/^[a-z]{2}(-[A-Z]{2})?$/, {
+          message: () => 'Language code must be ISO 639-1 format (e.g., en-US, fr-FR)',
+        })
+      ),
+      value: Schema.Struct({
+        content: Schema.optional(
+          Schema.String.annotations({
+            description: 'Translated content text',
+          })
+        ),
+        props: Schema.optional(ComponentPropsSchema),
+      }),
+    }).annotations({
+      description: 'Localized translations per language for this component',
+    })
+  ),
+}).annotations({
+  description: 'Direct component definition',
+})
+
+/**
+ * Section item - either a direct component or a component reference
+ *
+ * Sections support three patterns:
+ * 1. Direct component: Inline definition with type, props, children, etc.
+ * 2. Simple component reference: Reference by name with { component: 'name' }
+ * 3. Component reference with vars: Reference with variable substitution { $ref: 'name', vars: {} }
+ *
+ * This hybrid approach enables:
+ * - Quick prototyping with inline components
+ * - Reusability through component references
+ * - Flexibility to mix all patterns
+ *
+ * @example
+ * ```typescript
+ * const sections = [
+ *   // Direct component
+ *   {
+ *     type: 'section',
+ *     props: { id: 'hero' },
+ *     children: [
+ *       { type: 'text', content: 'Welcome' }
+ *     ]
+ *   },
+ *   // Simple component reference
+ *   {
+ *     component: 'shared-component'
+ *   },
+ *   // Component reference with variables
+ *   {
+ *     $ref: 'section-header',
+ *     vars: {
+ *       title: 'Our Features',
+ *       subtitle: 'Everything you need'
+ *     }
+ *   }
+ * ]
+ * ```
+ */
+export const SectionItemSchema = Schema.Union(
+  ComponentSchema,
+  ComponentReferenceSchema
+).annotations({
+  description:
+    'A page section that can be either a component or component reference (with optional variables)',
+})
+
+/**
+ * Array of page content sections
+ *
+ * The main content structure for pages, consisting of stacked sections.
+ * Each section can be nested arbitrarily deep through the children array.
+ *
+ * Sections enable:
+ * - Component composition (nest components to build layouts)
+ * - Reusability (reference components with $ref)
+ * - Responsive design (override props per breakpoint)
+ * - Interactivity (add hover, click, scroll, entrance behaviors)
+ *
+ * @example
+ * ```typescript
+ * const sections = [
+ *   {
+ *     type: 'section',
+ *     props: {
+ *       id: 'hero',
+ *       className: 'min-h-screen bg-gradient'
+ *     },
+ *     children: [
+ *       {
+ *         type: 'container',
+ *         props: { maxWidth: 'max-w-7xl' },
+ *         children: [
+ *           {
+ *             type: 'text',
+ *             props: {
+ *               level: 'h1',
+ *               className: 'text-6xl font-bold'
+ *             },
+ *             content: 'Welcome to Our Platform'
+ *           }
+ *         ]
+ *       }
+ *     ]
+ *   },
+ *   {
+ *     $ref: 'section-header',
+ *     vars: {
+ *       title: 'Our Features',
+ *       subtitle: 'Everything you need to succeed'
+ *     }
+ *   }
+ * ]
+ * ```
+ *
+ * @see specs/app/pages/sections/sections.schema.json
+ */
+export const SectionsSchema = Schema.Array(SectionItemSchema).annotations({
+  title: 'Page Sections',
+  description: 'Array of page content sections',
+})
+
+export type ComponentType = Schema.Schema.Type<typeof ComponentTypeSchema>
+export type Component = Schema.Schema.Type<typeof ComponentSchema>
+export type SectionItem = Schema.Schema.Type<typeof SectionItemSchema>
+export type Sections = Schema.Schema.Type<typeof SectionsSchema>

package/src/domain/models/app/pages.ts

@@ -0,0 +1,61 @@
+/**
+ * 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 { PageSchema } from './page'
+import type { Page, PageEncoded } from './page'
+
+/**
+ * Pages Schema
+ *
+ * Array of page configurations for the application. At least one page is required.
+ *
+ * Typical pages include:
+ * - Homepage (/)
+ * - About (/about)
+ * - Pricing (/pricing)
+ * - Contact (/contact)
+ * - Blog (/blog)
+ *
+ * @example
+ * ```typescript
+ * const pages: Pages = [
+ *   {
+ *     name: 'Home',
+ *     path: '/',
+ *     meta: { lang: 'en-US', title: 'Home', description: 'Welcome' },
+ *     sections: []
+ *   },
+ *   {
+ *     name: 'About',
+ *     path: '/about',
+ *     meta: { lang: 'en-US', title: 'About', description: 'About us' },
+ *     sections: []
+ *   }
+ * ]
+ * ```
+ */
+export const PagesSchema = Schema.Array(PageSchema).pipe(
+  Schema.minItems(1),
+  Schema.annotations({
+    identifier: 'Pages',
+    title: 'Pages',
+    description:
+      '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. Supports comprehensive metadata, theming, and structured data for SEO optimization.',
+  })
+)
+
+/**
+ * TypeScript type for Pages array
+ */
+export type Pages = typeof PagesSchema.Type
+
+/**
+ * Re-export Page schema and types from page module
+ */
+export { PageSchema }
+export type { Page, PageEncoded }