sovrium 0.0.2

package/src/domain/models/app/page/common/interactions/hover-interaction.ts

@@ -0,0 +1,144 @@
+/**
+ * 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'
+
+/**
+ * Transition easing function types
+ *
+ * Standard CSS easing functions for smooth transitions:
+ * - linear: Constant speed
+ * - ease: Slow start, fast middle, slow end (default)
+ * - ease-in: Slow start, fast end
+ * - ease-out: Fast start, slow end
+ * - ease-in-out: Slow start and end, fast middle
+ * - cubic-bezier(): Custom cubic bezier function (e.g., cubic-bezier(0.4, 0, 0.2, 1))
+ * - steps(): Step function for discrete animations (e.g., steps(40, end) for typewriter effect)
+ */
+export const EasingFunctionSchema = Schema.Union(
+  Schema.Literal('linear', 'ease', 'ease-in', 'ease-out', 'ease-in-out'),
+  Schema.String.pipe(
+    Schema.pattern(
+      /^cubic-bezier\(\s*-?[\d.]+\s*,\s*-?[\d.]+\s*,\s*-?[\d.]+\s*,\s*-?[\d.]+\s*\)$/,
+      {
+        message: () =>
+          'Custom easing must be a cubic-bezier function with exactly 4 numeric values (e.g., cubic-bezier(0.4, 0, 0.2, 1))',
+      }
+    )
+  ),
+  Schema.String.pipe(
+    Schema.pattern(
+      /^steps\(\s*\d+\s*,\s*(start|end|jump-start|jump-end|jump-none|jump-both)\s*\)$/,
+      {
+        message: () =>
+          'Steps function must have a number of steps and a position (e.g., steps(40, end))',
+      }
+    )
+  )
+).annotations({
+  description: 'Transition timing function',
+})
+
+/**
+ * CSS duration pattern (ms or s)
+ *
+ * Must be a number (integer or decimal) followed by 'ms' (milliseconds) or 's' (seconds).
+ *
+ * @example
+ * ```typescript
+ * const durations = ['200ms', '0.5s', '1s', '1500ms']
+ * ```
+ */
+export const DurationSchema = Schema.String.pipe(
+  Schema.pattern(/^[0-9]+(\.[0-9]+)?(ms|s)$/, {
+    message: () => 'Duration must be a number followed by ms or s (e.g., 200ms, 0.5s)',
+  })
+)
+
+/**
+ * Visual changes when user hovers over component
+ *
+ * Supports CSS properties for hover effects (all optional):
+ * - scale: Scale factor (e.g., 1.05 for 5% larger) - shorthand for transform: scale(X)
+ * - transform: CSS transforms (scale, rotate, translate)
+ * - opacity: Opacity value (0-1)
+ * - backgroundColor: Background color
+ * - color: Text color
+ * - borderColor: Border color
+ * - shadow: Box shadow
+ * - duration: Transition duration (default: 200ms)
+ * - easing: Transition easing (default: ease-out)
+ *
+ * All properties are animated smoothly using CSS transitions.
+ *
+ * @example
+ * ```typescript
+ * const hoverEffect = {
+ *   scale: 1.05,
+ *   shadow: '0 10px 25px rgba(0,0,0,0.15)',
+ *   duration: '200ms',
+ *   easing: 'ease-out'
+ * }
+ *
+ * const colorChange = {
+ *   opacity: 0.8,
+ *   backgroundColor: '#007bff',
+ *   color: '#ffffff'
+ * }
+ * ```
+ *
+ * @see specs/app/pages/common/interactions/hover-interaction.schema.json
+ */
+export const HoverInteractionSchema = Schema.Struct({
+  scale: Schema.optional(
+    Schema.Number.annotations({
+      description: 'Scale factor (e.g., 1.05 for 5% larger)',
+      examples: [1.05, 1.1, 0.95],
+    })
+  ),
+  transform: Schema.optional(
+    Schema.String.annotations({
+      description: 'CSS transform (scale, rotate, translate)',
+      examples: ['scale(1.05)', 'translateY(-4px)', 'rotate(5deg)'],
+    })
+  ),
+  opacity: Schema.optional(
+    Schema.Number.pipe(Schema.between(0, 1)).annotations({
+      description: 'Opacity value (0-1)',
+    })
+  ),
+  backgroundColor: Schema.optional(
+    Schema.String.annotations({
+      description: 'Background color on hover',
+    })
+  ),
+  color: Schema.optional(
+    Schema.String.annotations({
+      description: 'Text color on hover',
+    })
+  ),
+  borderColor: Schema.optional(
+    Schema.String.annotations({
+      description: 'Border color on hover',
+    })
+  ),
+  shadow: Schema.optional(
+    Schema.String.annotations({
+      description: 'Box shadow on hover',
+      examples: ['0 10px 25px rgba(0,0,0,0.1)'],
+    })
+  ),
+  duration: Schema.optional(DurationSchema),
+  easing: Schema.optional(EasingFunctionSchema),
+}).annotations({
+  title: 'Hover Interaction',
+  description: 'Visual changes when user hovers over component',
+})
+
+export type EasingFunction = Schema.Schema.Type<typeof EasingFunctionSchema>
+export type Duration = Schema.Schema.Type<typeof DurationSchema>
+export type HoverInteraction = Schema.Schema.Type<typeof HoverInteractionSchema>

package/src/domain/models/app/page/common/interactions/interactions.ts

@@ -0,0 +1,64 @@
+/**
+ * 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 { ClickInteractionSchema } from './click-interaction'
+import { EntranceAnimationSchema } from './entrance-animation'
+import { HoverInteractionSchema } from './hover-interaction'
+import { ScrollInteractionSchema } from './scroll-interaction'
+
+/**
+ * Interactive behaviors triggered by user actions or page events
+ *
+ * Orchestrates four types of interactions (all optional):
+ * - hover: Visual changes on mouse hover
+ * - click: Actions triggered on click
+ * - scroll: Animations when entering viewport
+ * - entrance: Animations on page load
+ *
+ * Multiple interaction types can be combined on the same component.
+ * Each interaction type works independently and doesn't interfere with others.
+ *
+ * @example
+ * ```typescript
+ * const interactions = {
+ *   hover: {
+ *     transform: 'scale(1.05)',
+ *     duration: '200ms',
+ *     easing: 'ease-out'
+ *   },
+ *   click: {
+ *     animation: 'pulse',
+ *     navigate: '/contact'
+ *   },
+ *   entrance: {
+ *     animation: 'fadeInUp',
+ *     delay: '100ms'
+ *   }
+ * }
+ *
+ * const hoverOnly = {
+ *   hover: {
+ *     backgroundColor: '#007bff',
+ *     color: '#ffffff'
+ *   }
+ * }
+ * ```
+ *
+ * @see specs/app/pages/common/interactions/interactions.schema.json
+ */
+export const InteractionsSchema = Schema.Struct({
+  hover: Schema.optional(HoverInteractionSchema),
+  click: Schema.optional(ClickInteractionSchema),
+  scroll: Schema.optional(ScrollInteractionSchema),
+  entrance: Schema.optional(EntranceAnimationSchema),
+}).annotations({
+  title: 'Component Interactions',
+  description: 'Interactive behaviors triggered by user actions or page events',
+})
+
+export type Interactions = Schema.Schema.Type<typeof InteractionsSchema>

package/src/domain/models/app/page/common/interactions/scroll-interaction.ts

@@ -0,0 +1,93 @@
+/**
+ * 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 { DurationSchema } from './hover-interaction'
+
+/**
+ * Scroll-triggered animation types
+ *
+ * Animations played when component enters viewport:
+ * - fadeIn: Fade in smoothly
+ * - fadeInUp: Fade in while moving up from below
+ * - fadeInDown: Fade in while moving down from above
+ * - fadeInLeft: Fade in while sliding from the left
+ * - fadeInRight: Fade in while sliding from the right
+ * - zoomIn: Zoom in from small to normal size
+ * - slideInUp: Slide up into position
+ * - slideInDown: Slide down into position
+ */
+export const ScrollAnimationSchema = Schema.Literal(
+  'fadeIn',
+  'fadeInUp',
+  'fadeInDown',
+  'fadeInLeft',
+  'fadeInRight',
+  'zoomIn',
+  'slideInUp',
+  'slideInDown'
+).annotations({
+  description: 'Animation type triggered on scroll',
+})
+
+/**
+ * Animations triggered when component enters viewport
+ *
+ * Uses Intersection Observer API to detect when component becomes visible.
+ *
+ * Configuration options:
+ * - animation: Animation type (required)
+ * - threshold: Percentage of element visible before triggering (0-1, default: 0.1)
+ * - delay: Delay before animation starts (e.g., '100ms', '0.5s')
+ * - duration: Animation duration (default: '600ms')
+ * - once: Trigger animation only once (default: true)
+ *
+ * @example
+ * ```typescript
+ * const scrollAnimation = {
+ *   animation: 'fadeInUp',
+ *   threshold: 0.2,
+ *   delay: '100ms',
+ *   duration: '600ms',
+ *   once: true
+ * }
+ *
+ * const repeatAnimation = {
+ *   animation: 'zoomIn',
+ *   threshold: 0.5,
+ *   once: false // Animate every time it enters viewport
+ * }
+ * ```
+ *
+ * @see specs/app/pages/common/interactions/scroll-interaction.schema.json
+ */
+export const ScrollInteractionSchema = Schema.Struct({
+  animation: ScrollAnimationSchema,
+  threshold: Schema.optional(
+    Schema.Number.pipe(Schema.between(0, 1)).annotations({
+      description: 'Percentage of element visible before triggering (0-1)',
+    })
+  ),
+  delay: Schema.optional(
+    DurationSchema.annotations({
+      description: 'Delay before animation starts',
+      examples: ['0ms', '100ms', '0.5s'],
+    })
+  ),
+  duration: Schema.optional(DurationSchema),
+  once: Schema.optional(
+    Schema.Boolean.annotations({
+      description: 'Trigger animation only once',
+    })
+  ),
+}).annotations({
+  title: 'Scroll Interaction',
+  description: 'Animations triggered when component enters viewport',
+})
+
+export type ScrollAnimation = Schema.Schema.Type<typeof ScrollAnimationSchema>
+export type ScrollInteraction = Schema.Schema.Type<typeof ScrollInteractionSchema>

package/src/domain/models/app/page/common/responsive.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'
+
+/**
+ * Component properties that can be overridden at specific breakpoints
+ *
+ * Supports overriding:
+ * - props: Component properties (className, style, etc.)
+ * - content: Text content
+ * - visible: Show/hide component
+ * - children: Different child components
+ *
+ * @example
+ * ```typescript
+ * const overrides = {
+ *   props: { className: 'text-2xl text-center' },
+ *   content: 'Welcome!',
+ *   visible: true
+ * }
+ * ```
+ */
+export const VariantOverridesSchema = Schema.Struct({
+  props: Schema.optional(
+    Schema.Record({
+      key: Schema.String.pipe(
+        Schema.pattern(/^[a-zA-Z][a-zA-Z0-9]*$/, {
+          message: () => 'Property key must be camelCase starting with a letter',
+        })
+      ),
+      value: Schema.Union(
+        Schema.String,
+        Schema.Number,
+        Schema.Boolean,
+        Schema.Record({ key: Schema.String, value: Schema.Unknown }),
+        Schema.Array(Schema.Unknown)
+      ),
+    }).annotations({
+      description: 'Props to override',
+    })
+  ),
+  content: Schema.optional(
+    Schema.String.annotations({
+      description: 'Content to display at this breakpoint',
+    })
+  ),
+  visible: Schema.optional(
+    Schema.Boolean.annotations({
+      description: 'Show/hide component at this breakpoint',
+    })
+  ),
+  children: Schema.optional(
+    Schema.Array(Schema.Unknown).annotations({
+      description: 'Different children at this breakpoint',
+    })
+  ),
+}).annotations({
+  description: 'Component properties to override at this breakpoint',
+})
+
+/**
+ * Breakpoint-specific component overrides for responsive design
+ *
+ * Provides responsive variants matching common breakpoints:
+ * - mobile: Base mobile styles
+ * - sm: Small (640px)
+ * - md: Medium (768px)
+ * - lg: Large (1024px)
+ * - xl: Extra large (1280px)
+ * - 2xl: 2x extra large (1536px)
+ *
+ * All breakpoints are optional. Use mobile-first approach: define base
+ * styles at mobile level, then override at larger breakpoints.
+ *
+ * @example
+ * ```typescript
+ * const responsive = {
+ *   mobile: {
+ *     props: { className: 'text-2xl text-center' },
+ *     content: 'Welcome!',
+ *     visible: true
+ *   },
+ *   md: {
+ *     props: { className: 'text-4xl text-left' },
+ *     content: 'Welcome to Our Platform'
+ *   },
+ *   lg: {
+ *     props: { className: 'text-6xl text-left font-bold' },
+ *     content: 'Welcome to Our Amazing Platform'
+ *   }
+ * }
+ * ```
+ *
+ * @see specs/app/pages/common/responsive.schema.json
+ */
+export const ResponsiveSchema = Schema.Struct({
+  mobile: Schema.optional(VariantOverridesSchema),
+  sm: Schema.optional(VariantOverridesSchema),
+  md: Schema.optional(VariantOverridesSchema),
+  lg: Schema.optional(VariantOverridesSchema),
+  xl: Schema.optional(VariantOverridesSchema),
+  '2xl': Schema.optional(VariantOverridesSchema),
+}).annotations({
+  title: 'Responsive Variants',
+  description: 'Breakpoint-specific component overrides for responsive design',
+})
+
+export type VariantOverrides = Schema.Schema.Type<typeof VariantOverridesSchema>
+export type Responsive = Schema.Schema.Type<typeof ResponsiveSchema>

package/src/domain/models/app/page/common/url.ts

@@ -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.
+ */
+
+import { Schema } from 'effect'
+
+/**
+ * HTTP/HTTPS URL validation schema
+ *
+ * Validates URLs that start with http:// or https:// protocol.
+ * Used for external resources like images, videos, audio, and API endpoints.
+ *
+ * Validation rules:
+ * - Must start with http:// or https://
+ * - Follows standard URL format with protocol, domain, and optional path
+ * - Format annotated as 'uri' for OpenAPI/JSON Schema compatibility
+ *
+ * @example "https://example.com/image.jpg"
+ * @example "http://api.example.com/endpoint"
+ *
+ * @see specs/app/pages/common/definitions.schema.json - APP-PAGES-DEFINITIONS-006
+ */
+export const HttpUrlSchema = Schema.String.pipe(
+  Schema.pattern(/^https?:\/\//, {
+    message: () => 'URL must start with http:// or https://',
+  })
+).annotations({
+  description: 'HTTP/HTTPS URL',
+  format: 'uri',
+})
+
+export type HttpUrl = Schema.Schema.Type<typeof HttpUrlSchema>

package/src/domain/models/app/page/common/variable-reference.ts

@@ -0,0 +1,53 @@
+/**
+ * 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'
+
+/**
+ * Variable reference pattern for template substitution
+ *
+ * Matches strings containing $variableName syntax for runtime substitution.
+ * Variables are replaced with values from the 'vars' object when component templates are instantiated.
+ *
+ * Variable naming rules:
+ * - Must start with $ followed by a letter
+ * - Can contain only alphanumeric characters after the initial letter
+ * - Multiple variables can appear in the same string
+ *
+ * @example
+ * ```typescript
+ * const refs = [
+ *   '$color',
+ *   '$primaryText',
+ *   'Welcome to $siteName',
+ *   'The $productName costs $price',
+ *   '$icon-$size'
+ * ]
+ * ```
+ *
+ * @see specs/app/pages/common/variable-reference.schema.json
+ */
+export const VariableReferenceSchema = Schema.String.pipe(
+  Schema.pattern(/^.*\$[a-zA-Z][a-zA-Z0-9]*.*$/, {
+    message: () =>
+      'Variable reference must contain $variableName where variableName starts with a letter and contains only alphanumeric characters',
+  }),
+  Schema.annotations({
+    title: 'Variable Reference',
+    description:
+      'Pattern for referencing variables in component templates using $variableName syntax',
+    examples: [
+      '$color',
+      '$primaryText',
+      'Welcome to $siteName',
+      'The $productName costs $price',
+      '$icon-$size',
+    ],
+  })
+)
+
+export type VariableReference = Schema.Schema.Type<typeof VariableReferenceSchema>

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

@@ -0,0 +1,44 @@
+/**
+ * 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'
+
+/**
+ * Page ID (unique identifier for the page)
+ *
+ * Unlike database entity IDs which are auto-incrementing integers, page IDs are
+ * user-defined strings for human-readable identification and routing purposes.
+ *
+ * Valid formats:
+ * - Kebab-case: 'home-page', 'about-us'
+ * - Simple: 'homepage', 'contact'
+ * - UUIDs: '550e8400-e29b-41d4-a716-446655440000'
+ * - Numeric strings: '12345'
+ *
+ * Page IDs must be unique within the pages array.
+ *
+ * @example
+ * ```typescript
+ * const pageId1 = 'homepage'
+ * const pageId2 = 'about-us'
+ * const pageId3 = 'contact-form-123'
+ * const pageId4 = '550e8400-e29b-41d4-a716-446655440000' // UUID
+ * ```
+ *
+ * @see specs/app/pages/id/id.schema.json
+ */
+export const PageIdSchema = Schema.String.pipe(
+  Schema.minLength(1),
+  Schema.annotations({
+    identifier: 'PageId',
+    title: 'Page ID',
+    description: 'Unique identifier for the page',
+    examples: ['homepage', 'about-us', 'contact-form-123', '550e8400-e29b-41d4-a716-446655440000'],
+  })
+)
+
+export type PageId = typeof PageIdSchema.Type