sovrium 0.0.2

package/src/domain/models/app/component/common/component-reference.ts

@@ -0,0 +1,170 @@
+/**
+ * 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 reference name (kebab-case identifier)
+ *
+ * Name of the component to reference (must match a component name in the components array).
+ * Uses kebab-case format for consistency with web standards.
+ *
+ * @example
+ * ```typescript
+ * const ref1 = 'icon-badge'
+ * const ref2 = 'section-header'
+ * const ref3 = 'call-to-action'
+ * ```
+ *
+ * @see specs/app/components/common/component-reference.schema.json#/properties/$ref
+ */
+export const ComponentReferenceNameSchema = Schema.String.pipe(
+  Schema.pattern(/^[a-z][a-z0-9-]*$/, {
+    message: () =>
+      'Component reference name must start with lowercase letter and contain only lowercase letters, numbers, and hyphens (kebab-case)',
+  }),
+  Schema.annotations({
+    title: 'Component Reference Name',
+    description: 'Name of the component to reference (kebab-case)',
+    examples: ['icon-badge', 'section-header', 'call-to-action'],
+  })
+)
+
+/**
+ * Component variables (for template substitution)
+ *
+ * Variables to substitute in the component template.
+ * Keys are alphanumeric identifiers, values are strings, numbers, or booleans.
+ *
+ * @example
+ * ```typescript
+ * const vars = {
+ *   color: 'orange',
+ *   icon: 'users',
+ *   text: '6 à 15 personnes',
+ *   count: 10,
+ *   enabled: true,
+ * }
+ * ```
+ *
+ * @see specs/app/components/common/component-reference.schema.json#/properties/vars
+ */
+export const ComponentVarsSchema = Schema.Record({
+  key: Schema.String.pipe(
+    Schema.pattern(/^[a-zA-Z][a-zA-Z0-9]*$/, {
+      message: () =>
+        'Component variable key must start with a letter and contain only alphanumeric characters',
+    }),
+    Schema.annotations({
+      title: 'Component Variable Key',
+      description: 'Variable name (alphanumeric)',
+      examples: ['color', 'icon', 'text', 'titleColor'],
+    })
+  ),
+  value: Schema.Union(Schema.String, Schema.Number, Schema.Boolean),
+}).pipe(
+  Schema.annotations({
+    title: 'Component Variables',
+    description: 'Variables to substitute in the component template',
+  })
+)
+
+/**
+ * Simple Component Reference (reference to a component by name without variables)
+ *
+ * Simplified syntax for referencing components that don't require variable substitution.
+ * Uses the `component` property to identify the component by name.
+ *
+ * @example
+ * ```typescript
+ * const simpleReference = {
+ *   component: 'shared-component'
+ * }
+ * ```
+ */
+export const SimpleComponentReferenceSchema = Schema.Struct({
+  component: ComponentReferenceNameSchema,
+}).pipe(
+  Schema.annotations({
+    title: 'Simple Component Reference',
+    description: 'Reference to a component by name without variable substitution',
+  })
+)
+
+/**
+ * Component Reference (reference to a reusable component template with variable substitution)
+ *
+ * Allows referencing and customizing predefined component templates.
+ * Supports two syntaxes:
+ * 1. Full syntax: { $ref: 'component-name', vars: {...} }
+ * 2. Shorthand syntax: { component: 'component-name' } (vars default to empty object)
+ *
+ * @example
+ * ```typescript
+ * // Full syntax
+ * const reference1 = {
+ *   $ref: 'icon-badge',
+ *   vars: {
+ *     color: 'orange',
+ *     icon: 'users',
+ *     text: '6 à 15 personnes',
+ *   },
+ * }
+ *
+ * // Shorthand syntax
+ * const reference2 = {
+ *   component: 'shared-component',
+ * }
+ * ```
+ *
+ * @see specs/app/components/common/component-reference.schema.json
+ */
+const FullComponentReferenceSchema = Schema.Struct({
+  $ref: ComponentReferenceNameSchema,
+  vars: ComponentVarsSchema,
+}).pipe(
+  Schema.annotations({
+    title: 'Component Reference (Full Syntax)',
+    description: 'Reference to a reusable component template with variable substitution',
+  })
+)
+
+const ShorthandComponentReferenceSchema = Schema.Struct({
+  component: ComponentReferenceNameSchema,
+}).pipe(
+  Schema.annotations({
+    title: 'Component Reference (Shorthand)',
+    description: 'Shorthand reference to a reusable component without variables',
+  })
+)
+
+const HybridComponentReferenceSchema = Schema.Struct({
+  component: ComponentReferenceNameSchema,
+  vars: ComponentVarsSchema,
+}).pipe(
+  Schema.annotations({
+    title: 'Component Reference (Hybrid)',
+    description: 'Shorthand component reference with variable substitution',
+  })
+)
+
+export const ComponentReferenceSchema = Schema.Union(
+  FullComponentReferenceSchema,
+  HybridComponentReferenceSchema,
+  ShorthandComponentReferenceSchema
+).pipe(
+  Schema.annotations({
+    title: 'Component Reference',
+    description:
+      'Reference to a reusable component template. Supports full syntax ($ref + vars), hybrid syntax (component + vars), or shorthand (component name only).',
+  })
+)
+
+export type ComponentReferenceName = Schema.Schema.Type<typeof ComponentReferenceNameSchema>
+export type ComponentVars = Schema.Schema.Type<typeof ComponentVarsSchema>
+export type SimpleComponentReference = Schema.Schema.Type<typeof SimpleComponentReferenceSchema>
+export type ComponentReference = Schema.Schema.Type<typeof ComponentReferenceSchema>

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

@@ -0,0 +1,81 @@
+/**
+ * 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 { ComponentChildrenSchema } from './common/component-children'
+import { ComponentPropsSchema } from './common/component-props'
+import { ComponentReferenceNameSchema } from './common/component-reference'
+
+/**
+ * Component template name identifier (same pattern as component reference name)
+ *
+ * Must be in kebab-case:
+ * - Start with lowercase letter
+ * - Contain only lowercase letters, numbers, and hyphens
+ * - Used for data-testid generation: data-testid="component-{name}"
+ *
+ * @example
+ * ```typescript
+ * const names = ['icon-badge', 'section-header', 'feature-card', 'cta-button-2']
+ * ```
+ */
+export const ComponentTemplateNameSchema = ComponentReferenceNameSchema.annotations({
+  title: 'Component Template Name',
+  description: 'Unique component template identifier in kebab-case',
+  examples: ['icon-badge', 'section-header', 'feature-card', 'cta-button-2'],
+})
+
+/**
+ * Reusable UI component template with variable placeholders
+ *
+ * A component template defines the structure of a reusable component that can be
+ * instantiated multiple times with different data via component references.
+ *
+ * Required properties:
+ * - name: Unique identifier (kebab-case)
+ * - type: Component type (container, flex, grid, card, text, button, etc.)
+ *
+ * Optional properties:
+ * - props: Component properties (may contain $variable placeholders)
+ * - children: Nested child components
+ * - content: Text content (may contain $variable placeholders)
+ *
+ * @example
+ * ```typescript
+ * const component = {
+ *   name: 'icon-badge',
+ *   type: 'badge',
+ *   props: { color: '$color' },
+ *   children: [
+ *     { type: 'icon', props: { name: '$icon', size: 4 } },
+ *     { type: 'text', props: { level: 'span' }, content: '$text' }
+ *   ]
+ * }
+ * ```
+ *
+ * @see specs/app/components/component/component.schema.json
+ */
+export const ComponentTemplateSchema = Schema.Struct({
+  name: ComponentTemplateNameSchema,
+  type: Schema.String.annotations({
+    description: 'Component type',
+    examples: ['container', 'flex', 'grid', 'card', 'text', 'button'],
+  }),
+  props: Schema.optional(ComponentPropsSchema),
+  children: Schema.optional(ComponentChildrenSchema),
+  content: Schema.optional(
+    Schema.String.annotations({
+      description: 'Text content (may contain $variable references)',
+    })
+  ),
+}).annotations({
+  title: 'Component Template',
+  description: 'A reusable UI component template with variable placeholders',
+})
+
+export type ComponentTemplateName = Schema.Schema.Type<typeof ComponentTemplateNameSchema>
+export type ComponentTemplate = Schema.Schema.Type<typeof ComponentTemplateSchema>

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

@@ -0,0 +1,65 @@
+/**
+ * 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 { ComponentTemplateSchema } from './component/component'
+
+/**
+ * Array of reusable UI component templates
+ *
+ * Components provide a library that can be referenced across pages
+ * using the $ref pattern. Each component defines a template with variable
+ * placeholders ($variable) that are substituted when the component is instantiated.
+ *
+ * Benefits:
+ * - DRY: Define once, reuse multiple times
+ * - Consistency: Centralized updates affect all instances
+ * - Maintainability: Single source of truth for UI patterns
+ *
+ * @example
+ * ```typescript
+ * const components = [
+ *   {
+ *     name: 'icon-badge',
+ *     type: 'badge',
+ *     props: { color: '$color' },
+ *     children: [
+ *       { type: 'icon', props: { name: '$icon' } },
+ *       { type: 'text', content: '$text' }
+ *     ]
+ *   },
+ *   {
+ *     name: 'section-header',
+ *     type: 'container',
+ *     props: { className: 'text-center mb-12' },
+ *     children: [
+ *       { type: 'text', props: { level: 'h2' }, content: '$title' },
+ *       { type: 'text', props: { level: 'p' }, content: '$subtitle' }
+ *     ]
+ *   }
+ * ]
+ * ```
+ *
+ * @see specs/app/components/components.schema.json
+ */
+export const ComponentsSchema = Schema.Array(ComponentTemplateSchema).pipe(
+  Schema.filter((components) => {
+    const names = components.map((component) => component.name)
+    const uniqueNames = new Set(names)
+    return (
+      names.length === uniqueNames.size ||
+      'Component names must be unique within the components array'
+    )
+  }),
+  Schema.annotations({
+    title: 'Reusable Components',
+    description:
+      'Array of reusable UI component templates with variable substitution for use across pages',
+  })
+)
+
+export type Components = Schema.Schema.Type<typeof ComponentsSchema>

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

@@ -0,0 +1,83 @@
+/**
+ * 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'
+
+/**
+ * Maximum length for application descriptions.
+ * This limit prevents UI/database issues with very long descriptions.
+ * Set to 2000 to accommodate long-form descriptions while preventing abuse.
+ */
+const DESCRIPTION_MAX_LENGTH = 2000
+
+/**
+ * DescriptionSchema defines validation rules for application descriptions.
+ *
+ * Application descriptions must be single-line strings:
+ * - No line breaks allowed (\n, \r, or \r\n)
+ * - Maximum 2000 characters
+ * - Can contain any characters except line breaks
+ * - Empty strings are allowed
+ * - Unicode characters and emojis are supported
+ * - Special characters, spaces, and tabs are allowed
+ *
+ * @example
+ * ```typescript
+ * // Valid descriptions
+ * const desc1 = 'A simple application'
+ * const desc2 = 'My app - with special characters!@#$%'
+ * const desc3 = 'Très bien! 你好 🎉'
+ * const desc4 = ''
+ *
+ * // Invalid descriptions (contain line breaks or too long)
+ * const invalid1 = 'Multi\nline'          // ❌ Contains \n
+ * const invalid2 = 'Windows\r\nbreak'     // ❌ Contains \r\n
+ * const invalid3 = 'Mac\rbreak'           // ❌ Contains \r
+ * const invalid4 = 'x'.repeat(2001)       // ❌ Exceeds 2000 characters
+ *
+ * // Validate description
+ * const validated = Schema.decodeUnknownSync(DescriptionSchema)(desc1)
+ * ```
+ */
+export const DescriptionSchema = Schema.String.pipe(
+  Schema.pattern(/^[^\r\n]*$/, {
+    message: () => 'Description must be a single line (line breaks are not allowed)',
+  }),
+  Schema.maxLength(DESCRIPTION_MAX_LENGTH, {
+    message: () =>
+      `Description must be ${DESCRIPTION_MAX_LENGTH} characters or less (current length exceeds limit)`,
+  }),
+  Schema.annotations({
+    title: 'Application Description',
+    description: `A single-line description of the application (max ${DESCRIPTION_MAX_LENGTH} characters, no line breaks)`,
+    examples: [
+      'A simple application',
+      'My app - with special characters!@#$%',
+      'Très bien! 你好 🎉',
+      'Full-featured e-commerce platform with cart, checkout & payment processing',
+    ],
+  })
+)
+
+/**
+ * TypeScript type inferred from DescriptionSchema.
+ *
+ * Use this type for type-safe access to validated description strings.
+ *
+ * @example
+ * ```typescript
+ * const description: Description = 'A simple application'
+ * ```
+ */
+export type Description = Schema.Schema.Type<typeof DescriptionSchema>
+
+/**
+ * Encoded type of DescriptionSchema (what goes in).
+ *
+ * In this case, it's the same as Description since we don't use transformations.
+ */
+export type DescriptionEncoded = Schema.Schema.Encoded<typeof DescriptionSchema>

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

@@ -0,0 +1,258 @@
+/**
+ * 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 { BuiltInAnalyticsSchema } from './analytics'
+import { AuthSchema } from './auth'
+import { BUILT_IN_ROLES } from './auth/roles'
+import { ComponentsSchema } from './components'
+import { DescriptionSchema } from './description'
+import { LanguagesSchema } from './languages'
+import { NameSchema } from './name'
+import { PagesSchema } from './pages'
+import { TablesSchema } from './tables'
+import { ThemeSchema } from './theme'
+import { VersionSchema } from './version'
+
+/**
+ * Helper to extract role names from a permission value.
+ * Permissions can be 'all', 'authenticated', or an array of role names.
+ */
+const extractRolesFromPermission = (permission: unknown): readonly string[] => {
+  if (!permission) return []
+  if (typeof permission === 'string') return [] // 'all' or 'authenticated'
+  if (Array.isArray(permission)) return permission as readonly string[]
+  return []
+}
+
+/**
+ * AppSchema defines the structure of an application configuration.
+ *
+ * This schema represents the core metadata for any application built
+ * with Sovrium, including its name, optional version, and optional description.
+ *
+ * @example
+ * ```typescript
+ * const myApp = {
+ *   name: 'todo-app',
+ *   version: '1.0.0',
+ *   description: 'A simple todo list application',
+ * }
+ *
+ * const validated = Schema.decodeUnknownSync(AppSchema)(myApp)
+ * ```
+ */
+export const AppSchema = Schema.Struct({
+  /**
+   * The name of the application.
+   *
+   * 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)
+   */
+  name: NameSchema,
+
+  /**
+   * The version of the application (optional).
+   *
+   * Must follow Semantic Versioning (SemVer) 2.0.0 specification:
+   * - Format: MAJOR.MINOR.PATCH (e.g., 1.0.0)
+   * - No leading zeros in version components
+   * - Optional pre-release identifiers (e.g., 1.0.0-alpha)
+   * - Optional build metadata (e.g., 1.0.0+build.123)
+   */
+  version: Schema.optional(VersionSchema),
+
+  /**
+   * A description of the application (optional).
+   *
+   * Must be a single-line string:
+   * - No line breaks allowed (\n, \r, or \r\n)
+   * - No maximum length restriction
+   * - Can contain any characters except line breaks
+   * - Unicode characters and emojis are supported
+   */
+  description: Schema.optional(DescriptionSchema),
+
+  /**
+   * Data tables that define the data structure (optional).
+   *
+   * Collection of database tables that define the data structure of your application.
+   * Each table represents an entity (e.g., users, products, orders) with fields that
+   * define the schema. Tables support relationships, indexes, constraints, and various
+   * field types.
+   */
+  tables: Schema.optional(TablesSchema),
+
+  /**
+   * Design system configuration (optional).
+   *
+   * Unified design tokens for colors, typography, spacing, animations, breakpoints,
+   * shadows, and border radius. Theme applies globally to all pages via className
+   * utilities and CSS variables.
+   */
+  theme: Schema.optional(ThemeSchema),
+
+  /**
+   * Multi-language support configuration (optional).
+   *
+   * Defines supported languages, default language, translations, and i18n behavior
+   * (browser detection, persistence). Pages reference translations using $t: syntax.
+   */
+  languages: Schema.optional(LanguagesSchema),
+
+  /**
+   * Authentication configuration (optional).
+   *
+   * Enables authentication features including email/password authentication,
+   * user management, and organization support. Configure authentication providers
+   * and optional plugins (admin, organization) based on application requirements.
+   */
+  auth: Schema.optional(AuthSchema),
+
+  /**
+   * Built-in analytics configuration (optional).
+   *
+   * Enables first-party, privacy-friendly analytics tracking without cookies
+   * or external dependencies. Configure data retention, excluded paths,
+   * session timeout, and Do Not Track behavior.
+   */
+  analytics: Schema.optional(BuiltInAnalyticsSchema),
+
+  /**
+   * Reusable UI components (optional).
+   *
+   * Array of reusable component templates with variable substitution. Components are
+   * defined once at app level and referenced across pages using $ref syntax with
+   * $vars for dynamic content.
+   */
+  components: Schema.optional(ComponentsSchema),
+
+  /**
+   * Marketing and content pages (optional).
+   *
+   * Array of page configurations with server-side rendering support. Pages use a
+   * component-based system with comprehensive metadata, theming, and i18n support.
+   * Minimum of 1 page required when pages property is present.
+   */
+  pages: Schema.optional(PagesSchema),
+}).pipe(
+  Schema.filter((app) => {
+    const userFieldTypes = new Set(['user', 'created-by', 'updated-by'])
+    const hasUserFields =
+      app.tables?.some((table) => table.fields.some((field) => userFieldTypes.has(field.type))) ??
+      false
+
+    if (hasUserFields && !app.auth) {
+      return 'User fields (user, created-by, updated-by) require auth configuration'
+    }
+    return true
+  }),
+  Schema.filter((app) => {
+    // Only validate role references in permissions when auth is explicitly configured.
+    // Without auth, custom role names in permissions are accepted (no validation context).
+    if (!app.auth || !app.tables || app.tables.length === 0) {
+      return true
+    }
+
+    // Build set of all valid roles: built-in + custom auth.roles
+    const customRoleNames = app.auth.roles?.map((role) => role.name) ?? []
+    const validRoles = new Set<string>([...BUILT_IN_ROLES, ...customRoleNames])
+
+    // Check all tables for invalid role references
+    const permissionKeys = ['create', 'read', 'update', 'delete', 'comment'] as const
+    const validationErrors = app.tables
+      .filter((table) => table.permissions)
+      .flatMap((table) => {
+        const tablePermissions = table.permissions as Record<string, unknown>
+        const allPermissionRoles = permissionKeys.flatMap((key) =>
+          extractRolesFromPermission(tablePermissions[key])
+        )
+        const invalidRole = allPermissionRoles.find((role) => !validRoles.has(role))
+        if (!invalidRole) return []
+        const sortedValidRoles = Array.from(validRoles).toSorted((a, b) => a.localeCompare(b))
+        return [
+          `Table '${table.name}' permissions reference undefined role '${invalidRole}'. Valid roles: ${sortedValidRoles.join(', ')}`,
+        ]
+      })
+
+    return validationErrors.length > 0 ? validationErrors[0] : true
+  }),
+  Schema.annotations({
+    title: 'Application Configuration',
+    description:
+      'Complete application configuration including name, version, description, and data tables. This is the root schema for Sovrium applications.',
+    examples: [
+      {
+        name: 'todo-app',
+        version: '1.0.0',
+        description: 'A simple todo list application',
+        tables: [
+          {
+            id: 1,
+            name: 'tasks',
+            fields: [
+              {
+                id: 1,
+                name: 'title',
+                type: 'single-line-text' as const,
+                required: true,
+              },
+              { id: 2, name: 'completed', type: 'checkbox' as const, required: true },
+            ],
+          },
+        ],
+      },
+      {
+        name: '@myorg/dashboard',
+        version: '2.0.0-beta.1',
+        description: 'Admin dashboard for analytics and reporting',
+      },
+      {
+        name: 'blog-system',
+      },
+    ],
+  })
+)
+
+/**
+ * TypeScript type inferred from AppSchema.
+ *
+ * Use this type for type-safe access to validated application data.
+ *
+ * @example
+ * ```typescript
+ * const app: App = {
+ *   name: 'my-app',
+ * }
+ * ```
+ */
+export type App = Schema.Schema.Type<typeof AppSchema>
+
+/**
+ * Encoded type of AppSchema (what goes in).
+ *
+ * In this case, it's the same as App since we don't use transformations.
+ */
+export type AppEncoded = Schema.Schema.Encoded<typeof AppSchema>
+
+// Re-export all domain model schemas and types for convenient imports
+export * from './analytics'
+export * from './name'
+export * from './version'
+export * from './description'
+export * from './tables'
+export * from './theme'
+export * from './languages'
+export * from './auth'
+export * from './components'
+export * from './pages'