sovrium 0.0.2

package/src/domain/models/app/language/language-config.ts

@@ -0,0 +1,200 @@
+/**
+ * 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'
+
+/**
+ * Short language code (ISO 639-1, used for URLs/routing)
+ *
+ * 2 lowercase letters only (no country code)
+ * Used for URL paths like /en/, /fr/, /es/
+ *
+ * @example
+ * ```typescript
+ * const code1 = 'en'  // English
+ * const code2 = 'fr'  // French
+ * const code3 = 'ar'  // Arabic
+ * ```
+ *
+ * @see specs/app/languages/language-config.schema.json#/properties/code
+ */
+export const LanguageCodeSchema = Schema.String.pipe(
+  Schema.pattern(/^[a-z]{2}$/, {
+    message: () => 'Language code must be ISO 639-1 format (2 lowercase letters, e.g., "en", "fr")',
+  }),
+  Schema.annotations({
+    title: 'Language Code',
+    description: 'Short language code used for URLs and routing (ISO 639-1, 2 letters)',
+    examples: ['en', 'fr', 'es', 'de', 'ar', 'he'],
+  })
+)
+
+/**
+ * Full locale code (ISO 639-1 + ISO 3166-1, used for HTML lang attribute)
+ *
+ * Format: language-COUNTRY (e.g., 'en-US', 'fr-FR')
+ * Used for HTML lang attribute and locale-specific formatting
+ *
+ * @example
+ * ```typescript
+ * const locale1 = 'en-US'  // English (United States)
+ * const locale2 = 'fr-FR'  // French (France)
+ * const locale3 = 'ar-SA'  // Arabic (Saudi Arabia)
+ * ```
+ *
+ * @see specs/app/languages/language-config.schema.json#/properties/locale
+ */
+export const LanguageLocaleSchema = Schema.String.pipe(
+  Schema.pattern(/^[a-z]{2}-[A-Z]{2}$/, {
+    message: () => 'Locale must be ISO 639-1 + ISO 3166-1 format (e.g., "en-US", "fr-FR")',
+  }),
+  Schema.annotations({
+    title: 'Language Locale',
+    description: 'Full locale code used for HTML lang attribute and locale-specific formatting',
+    examples: ['en-US', 'fr-FR', 'es-ES', 'de-DE', 'ar-SA', 'he-IL'],
+  })
+)
+
+/**
+ * Human-readable language name
+ *
+ * Should use the language's native name for better UX
+ * (e.g., "Français" instead of "French", "العربية" instead of "Arabic")
+ *
+ * @example
+ * ```typescript
+ * const label1 = 'English'
+ * const label2 = 'Français'  // French in French
+ * const label3 = 'العربية'    // Arabic in Arabic
+ * ```
+ *
+ * @see specs/app/languages/language-config.schema.json#/properties/label
+ */
+export const LanguageLabelSchema = Schema.String.pipe(
+  Schema.annotations({
+    title: 'Language Label',
+    description: 'Human-readable language name',
+    examples: ['English', 'Français', 'Español', 'العربية'],
+  })
+)
+
+/**
+ * Text direction (left-to-right or right-to-left)
+ *
+ * Controls the base text flow direction:
+ * - 'ltr': Left-to-right (default for most languages)
+ * - 'rtl': Right-to-left (for Arabic, Hebrew, etc.)
+ *
+ * @example
+ * ```typescript
+ * const ltr = 'ltr'  // English, French, Spanish
+ * const rtl = 'rtl'  // Arabic, Hebrew, Persian
+ * ```
+ *
+ * @see specs/app/languages/language-config.schema.json#/properties/direction
+ */
+export const LanguageDirectionSchema = Schema.Literal('ltr', 'rtl').pipe(
+  Schema.annotations({
+    title: 'Text Direction',
+    description: 'Text direction (left-to-right or right-to-left)',
+  })
+)
+
+/**
+ * Flag emoji or icon path
+ *
+ * Can be either:
+ * - Unicode emoji: '🇺🇸', '🇫🇷', '🇪🇸' (instant, no loading)
+ * - File path: '/flags/us.svg' (custom design, consistent styling)
+ *
+ * @example
+ * ```typescript
+ * const emoji = '🇺🇸'          // Unicode flag emoji
+ * const path = '/flags/us.svg'  // Custom SVG flag
+ * ```
+ *
+ * @see specs/app/languages/language-config.schema.json#/properties/flag
+ */
+export const LanguageFlagSchema = Schema.String.pipe(
+  Schema.annotations({
+    title: 'Language Flag',
+    description: 'Flag emoji or icon path',
+    examples: ['🇺🇸', '🇫🇷', '🇪🇸', '/flags/us.svg'],
+  })
+)
+
+/**
+ * Configuration for a single supported language
+ *
+ * Defines a language option in the language switcher with:
+ * - Short code for URLs (en, fr) - used for routing
+ * - Full locale for HTML (en-US, fr-FR) - used for lang attribute
+ * - Native language name for better UX
+ * - Text direction for RTL language support
+ * - Optional flag emoji or icon
+ *
+ * Key behaviors:
+ * - Code, locale, and label are required properties
+ * - Code (short) is used for URL paths: /en/, /fr/
+ * - Locale (full) is used for HTML lang attribute: lang="en-US"
+ * - Direction defaults to 'ltr' when omitted
+ * - Flag is optional for minimal configuration
+ *
+ * @example
+ * ```typescript
+ * // English (US) with all properties
+ * const enUS = {
+ *   code: 'en',
+ *   locale: 'en-US',
+ *   label: 'English',
+ *   direction: 'ltr',
+ *   flag: '🇺🇸'
+ * }
+ *
+ * // Arabic with RTL support
+ * const arSA = {
+ *   code: 'ar',
+ *   locale: 'ar-SA',
+ *   label: 'العربية',
+ *   direction: 'rtl',
+ *   flag: '🇸🇦'
+ * }
+ *
+ * // Minimal configuration
+ * const deDE = {
+ *   code: 'de',
+ *   locale: 'de-DE',
+ *   label: 'Deutsch'
+ *   // direction defaults to 'ltr'
+ *   // flag omitted
+ * }
+ * ```
+ *
+ * @see specs/app/languages/language-config.schema.json
+ */
+export const LanguageConfigSchema = Schema.Struct({
+  code: LanguageCodeSchema,
+  locale: Schema.optional(LanguageLocaleSchema).annotations({
+    description:
+      'Full locale code (optional - defaults to short code if not specified). Used for HTML lang attribute and hreflang links.',
+  }),
+  label: LanguageLabelSchema,
+  direction: Schema.optional(LanguageDirectionSchema),
+  flag: Schema.optional(LanguageFlagSchema),
+}).pipe(
+  Schema.annotations({
+    title: 'Language Configuration',
+    description: 'Configuration for a single supported language',
+  })
+)
+
+export type LanguageCode = Schema.Schema.Type<typeof LanguageCodeSchema>
+export type LanguageLocale = Schema.Schema.Type<typeof LanguageLocaleSchema>
+export type LanguageLabel = Schema.Schema.Type<typeof LanguageLabelSchema>
+export type LanguageDirection = Schema.Schema.Type<typeof LanguageDirectionSchema>
+export type LanguageFlag = Schema.Schema.Type<typeof LanguageFlagSchema>
+export type LanguageConfig = Schema.Schema.Type<typeof LanguageConfigSchema>

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

@@ -0,0 +1,205 @@
+/**
+ * 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 { LanguageConfigSchema } from './language/language-config'
+
+/**
+ * Short language code for URLs and routing
+ *
+ * Format: ll (two lowercase letters)
+ * - ll: ISO 639-1 language code
+ *
+ * Used for:
+ * - URL paths (e.g., /en/, /fr/, /es/)
+ * - Translation dictionary keys
+ * - Default language setting
+ *
+ * @example
+ * ```typescript
+ * const codes = ['en', 'fr', 'es', 'de', 'ar', 'he']
+ * ```
+ *
+ * @see specs/app/languages/languages.schema.json
+ */
+export const LanguageCodeSchema = Schema.String.pipe(
+  Schema.pattern(/^[a-z]{2}$/, {
+    message: () => 'Language code must be 2 lowercase letters (ISO 639-1 format, e.g., en, fr, es)',
+  }),
+  Schema.annotations({
+    title: 'Language Code',
+    description: 'Short language code (2 letters) for URLs and routing',
+    examples: ['en', 'fr', 'es', 'de', 'ar', 'he'],
+  })
+)
+
+/**
+ * Translation key for centralized translations dictionary
+ *
+ * Format: Alphanumeric with dots, hyphens, and underscores
+ * Convention: Use namespaces for organization (e.g., common.save, nav.home, homepage.hero.title)
+ *
+ * @example
+ * ```typescript
+ * const keys = ['common.save', 'nav.home', 'homepage.hero.title', 'errors.404']
+ * ```
+ */
+export const TranslationKeySchema = Schema.String.pipe(
+  Schema.pattern(/^[a-zA-Z0-9._-]+$/, {
+    message: () =>
+      'Translation key must contain only alphanumeric characters, dots, hyphens, and underscores',
+  }),
+  Schema.annotations({
+    title: 'Translation Key',
+    description: 'Key for centralized translations dictionary',
+    examples: ['common.save', 'nav.home', 'homepage.hero.title', 'errors.404'],
+  })
+)
+
+/**
+ * Translation dictionary for a single language
+ *
+ * Maps translation keys to localized strings.
+ * Use semantic keys that describe meaning, not location.
+ * Organize by feature/page for better maintainability.
+ *
+ * @example
+ * ```typescript
+ * const translations = {
+ *   'common.save': 'Save',
+ *   'common.cancel': 'Cancel',
+ *   'nav.home': 'Home',
+ *   'homepage.hero.title': 'Welcome to Sovrium'
+ * }
+ * ```
+ */
+export const TranslationDictionarySchema = Schema.Record({
+  key: TranslationKeySchema,
+  value: Schema.String,
+}).pipe(
+  Schema.annotations({
+    title: 'Translation Dictionary',
+    description: 'Maps translation keys to localized strings for a single language',
+  })
+)
+
+/**
+ * Centralized translations for all supported languages
+ *
+ * Outer Record key: Short language code (2 letters, e.g., en, fr, es)
+ * Outer Record value: Translation dictionary for that language
+ *
+ * This is the PRIMARY i18n pattern. Use $t:key syntax in ANY string property
+ * to reference translations: children arrays, component props, meta properties, etc.
+ *
+ * @example
+ * ```typescript
+ * const translations = {
+ *   'en': {
+ *     'common.save': 'Save',
+ *     'nav.home': 'Home'
+ *   },
+ *   'fr': {
+ *     'common.save': 'Enregistrer',
+ *     'nav.home': 'Accueil'
+ *   }
+ * }
+ * ```
+ */
+export const TranslationsSchema = Schema.Record({
+  key: LanguageCodeSchema,
+  value: TranslationDictionarySchema,
+}).pipe(
+  Schema.annotations({
+    title: 'Centralized Translations',
+    description:
+      'Translation dictionaries for all supported languages (keyed by short codes: en, fr, es). Use $t:key syntax to reference translations.',
+  })
+)
+
+/**
+ * Multi-language support configuration for the entire application
+ *
+ * Provides:
+ * - default: Default language short code (required, e.g., 'en', 'fr')
+ * - supported: Array of supported languages with metadata (required)
+ * - fallback: Language to use when translation is missing (optional, defaults to default language)
+ * - detectBrowser: Auto-detect language from browser (optional, defaults to true)
+ * - persistSelection: Remember user's language choice in localStorage (optional, defaults to true)
+ * - translations: Centralized translation dictionaries (optional, keyed by short codes)
+ *
+ * Language codes follow a dual pattern:
+ * - code: Short code (en, fr) for URLs and translation keys
+ * - locale: Full locale (en-US, fr-FR) for HTML lang attribute
+ *
+ * @example
+ * ```typescript
+ * const languages = {
+ *   default: 'en',
+ *   supported: [
+ *     { code: 'en', locale: 'en-US', label: 'English', direction: 'ltr' },
+ *     { code: 'fr', locale: 'fr-FR', label: 'Français', direction: 'ltr' }
+ *   ],
+ *   detectBrowser: true,
+ *   persistSelection: true,
+ *   translations: {
+ *     'en': { 'common.save': 'Save' },
+ *     'fr': { 'common.save': 'Enregistrer' }
+ *   }
+ * }
+ * ```
+ *
+ * @see specs/app/languages/languages.schema.json
+ */
+export const LanguagesSchema = Schema.Struct({
+  default: LanguageCodeSchema,
+  supported: Schema.Array(LanguageConfigSchema).pipe(
+    Schema.minItems(1),
+    Schema.annotations({
+      description: 'List of supported languages',
+    })
+  ),
+  fallback: Schema.optional(LanguageCodeSchema),
+  detectBrowser: Schema.optional(Schema.Boolean),
+  persistSelection: Schema.optional(Schema.Boolean),
+  translations: Schema.optional(TranslationsSchema),
+}).pipe(
+  Schema.filter((input) => {
+    const supportedCodes = new Set(input.supported.map((lang) => lang.code))
+
+    // Default language must be in supported array
+    if (!supportedCodes.has(input.default)) {
+      return 'default language must be in supported array'
+    }
+
+    // Fallback language must be in supported array (if specified)
+    if (input.fallback && !supportedCodes.has(input.fallback)) {
+      return 'fallback language must be in supported array'
+    }
+
+    // If translations are provided, validate they only contain supported languages
+    if (input.translations) {
+      const translationCodes = Object.keys(input.translations)
+      const unsupportedCodes = translationCodes.filter((code) => !supportedCodes.has(code))
+      if (unsupportedCodes.length > 0) {
+        return `translations contain unsupported language codes: ${unsupportedCodes.join(', ')}. Only these are supported: ${[...supportedCodes].join(', ')}`
+      }
+    }
+
+    return undefined
+  }),
+  Schema.annotations({
+    title: 'Languages Configuration',
+    description: 'Multi-language support configuration for the entire application',
+  })
+)
+
+export type LanguageCode = Schema.Schema.Type<typeof LanguageCodeSchema>
+export type TranslationKey = Schema.Schema.Type<typeof TranslationKeySchema>
+export type TranslationDictionary = Schema.Schema.Type<typeof TranslationDictionarySchema>
+export type Translations = Schema.Schema.Type<typeof TranslationsSchema>
+export type Languages = Schema.Schema.Type<typeof LanguagesSchema>

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

@@ -0,0 +1,66 @@
+/**
+ * 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'
+
+/**
+ * NameSchema defines validation rules for application names.
+ *
+ * Application names must follow npm package naming conventions:
+ * - Lowercase only
+ * - Maximum 214 characters (including scope for scoped packages)
+ * - Cannot start with a dot or underscore
+ * - Cannot contain leading/trailing spaces
+ * - Cannot contain non-URL-safe characters
+ * - Scoped packages: @scope/package-name format allowed
+ * - Can include hyphens and underscores (but not at the start)
+ *
+ * @example
+ * ```typescript
+ * // Valid names
+ * const name1 = 'my-app'
+ * const name2 = 'todo-app'
+ * const name3 = '@myorg/my-app'
+ * const name4 = 'blog-system'
+ * const name5 = 'dashboard-admin'
+ *
+ * // Validate name
+ * const validated = Schema.decodeUnknownSync(NameSchema)(name1)
+ * ```
+ */
+export const NameSchema = Schema.String.pipe(
+  Schema.minLength(1, { message: () => 'Name must not be empty' }),
+  Schema.maxLength(214, { message: () => 'Name must not exceed 214 characters' }),
+  Schema.pattern(/^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/, {
+    message: () =>
+      'Name must be lowercase and follow npm package naming conventions (no leading/trailing spaces, no dots/underscores at start, URL-safe characters only)',
+  }),
+  Schema.annotations({
+    title: 'Application Name',
+    description: 'The name of the application (follows npm package naming conventions)',
+    examples: ['my-app', 'todo-app', '@myorg/my-app', 'blog-system', 'dashboard-admin'],
+  })
+)
+
+/**
+ * TypeScript type inferred from NameSchema.
+ *
+ * Use this type for type-safe access to validated application names.
+ *
+ * @example
+ * ```typescript
+ * const name: Name = 'my-app'
+ * ```
+ */
+export type Name = Schema.Schema.Type<typeof NameSchema>
+
+/**
+ * Encoded type of NameSchema (what goes in).
+ *
+ * In this case, it's the same as Name since we don't use transformations.
+ */
+export type NameEncoded = Schema.Schema.Encoded<typeof NameSchema>

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

@@ -0,0 +1,116 @@
+/**
+ * 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'
+
+/**
+ * Click animation types
+ *
+ * Animations triggered when component is clicked:
+ * - pulse: Subtle scale pulse
+ * - bounce: Playful bounce effect
+ * - shake: Shake horizontally
+ * - flash: Quick opacity flash
+ * - ripple: Material Design ripple from click point
+ * - none: No animation
+ */
+export const ClickAnimationSchema = Schema.Literal(
+  'pulse',
+  'bounce',
+  'shake',
+  'flash',
+  'ripple',
+  'none'
+).annotations({
+  description: 'Animation to trigger on click',
+})
+
+/**
+ * Element ID selector pattern (#elementId)
+ *
+ * Must start with # followed by a letter, then alphanumeric characters and hyphens.
+ *
+ * @example
+ * ```typescript
+ * const selectors = ['#hero-section', '#pricing', '#contactForm']
+ * ```
+ */
+export const ElementIdSelectorSchema = Schema.String.pipe(
+  Schema.pattern(/^#[a-zA-Z][a-zA-Z0-9-]*$/, {
+    message: () =>
+      'Element ID selector must start with # followed by a letter, then alphanumeric characters and hyphens',
+  })
+)
+
+/**
+ * Actions triggered when component is clicked
+ *
+ * Supports multiple action types (all optional):
+ * - animation: Visual feedback animation
+ * - navigate: Client-side navigation to internal path or anchor
+ * - openUrl: Open external URL
+ * - openInNewTab: Open link in new tab (used with openUrl)
+ * - scrollTo: Smooth scroll to element by ID
+ * - toggleElement: Show/hide element by ID
+ * - submitForm: Submit form by ID
+ *
+ * Multiple actions can be combined (e.g., play animation then navigate).
+ *
+ * @example
+ * ```typescript
+ * const clickInteraction = {
+ *   animation: 'pulse',
+ *   navigate: '/contact'
+ * }
+ *
+ * const externalLink = {
+ *   animation: 'ripple',
+ *   openUrl: 'https://example.com',
+ *   openInNewTab: true
+ * }
+ *
+ * const scrollToSection = {
+ *   animation: 'ripple',
+ *   scrollTo: '#pricing-section'
+ * }
+ * ```
+ *
+ * @see specs/app/pages/common/interactions/click-interaction.schema.json
+ */
+export const ClickInteractionSchema = Schema.Struct({
+  animation: Schema.optional(ClickAnimationSchema),
+  navigate: Schema.optional(
+    Schema.String.annotations({
+      description: 'Path to navigate to',
+      examples: ['/contact', '/pricing', '#section-id'],
+    })
+  ),
+  openUrl: Schema.optional(
+    Schema.String.annotations({
+      description: 'External URL to open',
+    })
+  ),
+  openInNewTab: Schema.optional(Schema.Boolean),
+  scrollTo: Schema.optional(ElementIdSelectorSchema),
+  toggleElement: Schema.optional(
+    ElementIdSelectorSchema.annotations({
+      description: 'Element ID to show/hide',
+    })
+  ),
+  submitForm: Schema.optional(
+    ElementIdSelectorSchema.annotations({
+      description: 'Form ID to submit',
+    })
+  ),
+}).annotations({
+  title: 'Click Interaction',
+  description: 'Actions triggered when component is clicked',
+})
+
+export type ClickAnimation = Schema.Schema.Type<typeof ClickAnimationSchema>
+export type ElementIdSelector = Schema.Schema.Type<typeof ElementIdSelectorSchema>
+export type ClickInteraction = Schema.Schema.Type<typeof ClickInteractionSchema>

package/src/domain/models/app/page/common/interactions/entrance-animation.ts

@@ -0,0 +1,84 @@
+/**
+ * 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'
+
+/**
+ * Page load animation types
+ *
+ * Animations played when page loads:
+ * - fadeIn: Fade in smoothly
+ * - fadeInUp: Fade in while moving up from below
+ * - fadeInDown: Fade in while moving down from above
+ * - zoomIn: Zoom in from small to normal size
+ * - slideInUp: Slide up into position
+ * - slideInDown: Slide down into position
+ */
+export const EntranceAnimationTypeSchema = Schema.Literal(
+  'fadeIn',
+  'fadeInUp',
+  'fadeInDown',
+  'zoomIn',
+  'slideInUp',
+  'slideInDown'
+).annotations({
+  description: 'Animation type for page load',
+})
+
+/**
+ * Animation played when page loads
+ *
+ * Provides initial page load animations for components.
+ * Useful for creating engaging entry experiences.
+ *
+ * Configuration options:
+ * - animation: Animation type (required)
+ * - delay: Delay before animation starts (default: '0ms')
+ * - duration: Animation duration (default: '600ms')
+ * - stagger: Delay between sibling animations (e.g., '50ms', '100ms')
+ *
+ * Stagger effect: When multiple sibling components have entrance animations,
+ * stagger adds incremental delay to each sibling, creating a cascading effect.
+ *
+ * @example
+ * ```typescript
+ * const entrance = {
+ *   animation: 'fadeInUp',
+ *   delay: '200ms',
+ *   duration: '800ms'
+ * }
+ *
+ * const staggered = {
+ *   animation: 'fadeIn',
+ *   stagger: '100ms' // Each sibling animates 100ms after the previous
+ * }
+ * ```
+ *
+ * @see specs/app/pages/common/interactions/entrance-animation.schema.json
+ */
+export const EntranceAnimationSchema = Schema.Struct({
+  animation: EntranceAnimationTypeSchema,
+  delay: Schema.optional(
+    DurationSchema.annotations({
+      description: 'Delay before animation starts',
+    })
+  ),
+  duration: Schema.optional(DurationSchema),
+  stagger: Schema.optional(
+    DurationSchema.annotations({
+      description: 'Delay between sibling animations',
+      examples: ['50ms', '100ms'],
+    })
+  ),
+}).annotations({
+  title: 'Entrance Animation',
+  description: 'Animation played when page loads',
+})
+
+export type EntranceAnimationType = Schema.Schema.Type<typeof EntranceAnimationTypeSchema>
+export type EntranceAnimation = Schema.Schema.Type<typeof EntranceAnimationSchema>