sovrium 0.0.2

package/src/domain/models/app/common/branded-ids.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'
+
+/**
+ * Base numeric ID schema with common validation
+ *
+ * All numeric IDs share these constraints:
+ * - Must be positive integers (>= 1)
+ * - Must be within JavaScript safe integer range
+ * - Are system-generated and immutable
+ */
+const BaseNumericIdSchema = Schema.Int.pipe(
+  Schema.greaterThanOrEqualTo(1),
+  Schema.lessThanOrEqualTo(9_007_199_254_740_991)
+)
+
+/**
+ * Table ID - Identifier for tables (numeric or string)
+ *
+ * Unique identifier for tables within an application.
+ * Accepts positive integers, UUID strings, or simple string identifiers.
+ * If omitted, an ID will be auto-generated during validation.
+ *
+ * @example
+ * ```typescript
+ * // Numeric ID
+ * const table1 = { id: 1, name: 'users', fields: [] }
+ *
+ * // UUID string ID
+ * const table2 = { id: '550e8400-e29b-41d4-a716-446655440000', name: 'orders', fields: [] }
+ *
+ * // Simple string ID
+ * const table3 = { id: 'products', name: 'products', fields: [] }
+ * ```
+ */
+export const TableIdSchema = Schema.Union(
+  BaseNumericIdSchema,
+  Schema.String.pipe(Schema.minLength(1))
+).pipe(
+  Schema.annotations({
+    identifier: 'TableId',
+    title: 'Table ID',
+    description:
+      'Unique identifier for a table. Accepts positive integers, UUID strings, or simple string identifiers. Examples: 1, 2, 100, "550e8400-e29b-41d4-a716-446655440000", "products"',
+  })
+)
+
+export type TableId = Schema.Schema.Type<typeof TableIdSchema>
+
+/**
+ * Field ID - Numeric identifier for fields
+ *
+ * Unique identifier for fields within a table.
+ * Field IDs are unique within their parent table, not globally.
+ *
+ * @example
+ * ```typescript
+ * const field = { id: 1, name: 'email', type: 'email' }
+ * ```
+ */
+export const FieldIdSchema = BaseNumericIdSchema.pipe(
+  Schema.annotations({
+    identifier: 'FieldId',
+    title: 'Field ID',
+    description: 'Unique identifier for a field within a table. Examples: 1, 2, 3, 100',
+  })
+)
+
+export type FieldId = Schema.Schema.Type<typeof FieldIdSchema>
+
+/**
+ * Record ID - Numeric identifier for records
+ *
+ * Unique identifier for records within a table.
+ * Record IDs are unique within their parent table.
+ *
+ * @example
+ * ```typescript
+ * const record = { id: 1, data: { ... } }
+ * ```
+ */
+export const RecordIdSchema = BaseNumericIdSchema.pipe(
+  Schema.annotations({
+    identifier: 'RecordId',
+    title: 'Record ID',
+    description: 'Unique identifier for a record within a table. Examples: 1, 2, 3, 1000',
+  })
+)
+
+export type RecordId = Schema.Schema.Type<typeof RecordIdSchema>
+
+/**
+ * User ID - Branded type for user identifiers
+ *
+ * Unique identifier for users in the authentication system.
+ * User IDs are globally unique across the application.
+ *
+ * @example
+ * ```typescript
+ * const userId: UserId = 'usr_123abc' as UserId
+ * ```
+ */
+export const UserIdSchema = Schema.String.pipe(
+  Schema.minLength(1),
+  Schema.brand('UserId'),
+  Schema.annotations({
+    identifier: 'UserId',
+    title: 'User ID',
+    description:
+      'Unique identifier for a user (branded type). Examples: usr_123abc, user-456, 550e8400-e29b-41d4-a716-446655440000',
+  })
+)
+
+export type UserId = Schema.Schema.Type<typeof UserIdSchema>
+
+/**
+ * Workspace ID - Branded type for workspace identifiers
+ *
+ * Unique identifier for workspaces.
+ * Workspaces provide logical separation of data.
+ *
+ * @example
+ * ```typescript
+ * const workspaceId: WorkspaceId = 'ws_marketing' as WorkspaceId
+ * ```
+ */
+export const WorkspaceIdSchema = Schema.String.pipe(
+  Schema.minLength(1),
+  Schema.brand('WorkspaceId'),
+  Schema.annotations({
+    identifier: 'WorkspaceId',
+    title: 'Workspace ID',
+    description:
+      'Unique identifier for a workspace (branded type). Examples: ws_marketing, workspace-dev, default',
+  })
+)
+
+export type WorkspaceId = Schema.Schema.Type<typeof WorkspaceIdSchema>
+
+/**
+ * Component Template ID - Branded type for component template identifiers
+ *
+ * Unique identifier for reusable component templates.
+ * Component templates are referenced in page sections via $ref.
+ *
+ * @example
+ * ```typescript
+ * const componentId: ComponentTemplateId = 'hero-section' as ComponentTemplateId
+ * ```
+ */
+export const ComponentTemplateIdSchema = Schema.String.pipe(
+  Schema.minLength(1),
+  Schema.pattern(/^[a-z][a-z0-9-]*$/, {
+    message: () =>
+      'Component template ID must start with a letter and contain only lowercase letters, numbers, and hyphens',
+  }),
+  Schema.brand('ComponentTemplateId'),
+  Schema.annotations({
+    identifier: 'ComponentTemplateId',
+    title: 'Component Template ID',
+    description:
+      'Unique identifier for a reusable component template (branded type). Examples: hero-section, feature-grid, cta-banner',
+  })
+)
+
+export type ComponentTemplateId = Schema.Schema.Type<typeof ComponentTemplateIdSchema>
+
+/**
+ * View ID - Branded type for view identifiers
+ *
+ * Unique identifier for table views.
+ * Views define filtered/sorted/grouped perspectives on table data.
+ *
+ * @example
+ * ```typescript
+ * const viewId: ViewId = 'active_tasks' as ViewId
+ * ```
+ */
+export const BrandedViewIdSchema = Schema.String.pipe(
+  Schema.minLength(1),
+  Schema.pattern(/^[a-z][a-z0-9_]*$/, {
+    message: () =>
+      'View ID must start with a letter and contain only lowercase letters, numbers, and underscores',
+  }),
+  Schema.brand('ViewId'),
+  Schema.annotations({
+    identifier: 'ViewId',
+    title: 'View ID',
+    description:
+      'Unique identifier for a table view (branded type). Examples: active_tasks, by_department, recent_first',
+  })
+)
+
+export type BrandedViewId = Schema.Schema.Type<typeof BrandedViewIdSchema>

package/src/domain/models/app/common/definitions.ts

@@ -0,0 +1,187 @@
+/**
+ * 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'
+
+/**
+ * Unique positive integer identifier for entities
+ *
+ * IDs are system-generated, auto-incrementing, and immutable.
+ * Must be unique within the parent collection (e.g., field IDs unique within a table).
+ * IDs are read-only and assigned automatically when entities are created.
+ *
+ * Range: 1 to 9,007,199,254,740,991 (JavaScript MAX_SAFE_INTEGER)
+ *
+ * @example
+ * ```typescript
+ * const id = 1
+ * const tableId = 100
+ * const fieldId = 1000
+ * ```
+ *
+ * @see specs/app/common/definitions.schema.json#/definitions/id
+ */
+export const IdSchema = Schema.Int.pipe(
+  Schema.greaterThanOrEqualTo(1),
+  Schema.lessThanOrEqualTo(9_007_199_254_740_991),
+  Schema.annotations({
+    title: 'ID',
+    description: 'Unique positive integer identifier for entities',
+    examples: [1, 2, 3, 100, 1000],
+    readOnly: true,
+  })
+)
+
+/**
+ * Internal identifier name used for database tables, columns, and programmatic references
+ *
+ * Must follow database naming conventions:
+ * - Start with a letter
+ * - Contain only lowercase letters, numbers, and underscores
+ * - Maximum 63 characters (PostgreSQL limit)
+ *
+ * Used in SQL queries, API endpoints, and code generation.
+ * Choose descriptive names that clearly indicate the purpose.
+ *
+ * @example
+ * ```typescript
+ * const name1 = 'user'
+ * const name2 = 'email_address'
+ * const name3 = 'created_at'
+ * ```
+ *
+ * @see specs/app/common/definitions.schema.json#/definitions/name
+ */
+export const NameSchema = Schema.String.pipe(
+  Schema.minLength(1),
+  Schema.maxLength(63),
+  Schema.pattern(/^[a-z][a-z0-9_]*$/, {
+    message: () =>
+      'Name must start with a lowercase letter and contain only lowercase letters, numbers, and underscores (snake_case)',
+  }),
+  Schema.annotations({
+    title: 'Name',
+    description:
+      'Internal identifier name for database tables, columns, and programmatic references',
+    examples: ['user', 'product', 'order_item', 'customer_email', 'shipping_address', 'created_at'],
+  })
+)
+
+/**
+ * URL path for routing and navigation
+ *
+ * Must:
+ * - Start with forward slash (/)
+ * - Contain only lowercase letters, numbers, hyphens, colons, and forward slashes
+ * - Be descriptive and hierarchical
+ * - Support dynamic route parameters with colon prefix (e.g., :id, :slug)
+ *
+ * Used for page routing, API endpoints, and navigation links.
+ * Nested paths and dynamic parameters are supported for flexible routing.
+ *
+ * @example
+ * ```typescript
+ * const root = '/'
+ * const simple = '/about'
+ * const nested = '/products/inventory'
+ * const kebabCase = '/our-team'
+ * const dynamic = '/blog/:slug'
+ * const multiParam = '/users/:userId/posts/:postId'
+ * ```
+ *
+ * @see specs/app/common/definitions.schema.json#/definitions/path
+ */
+export const PathSchema = Schema.String.pipe(
+  Schema.minLength(1),
+  Schema.pattern(/^\/[a-z0-9-_/:]*$/, {
+    message: () =>
+      'Path must start with / and contain only lowercase letters, numbers, hyphens, underscores, colons, and forward slashes',
+  }),
+  Schema.annotations({
+    title: 'Path',
+    description: 'URL path for routing and navigation (supports dynamic parameters with :param)',
+    examples: [
+      '/home',
+      '/customers',
+      '/products/inventory',
+      '/admin/settings',
+      '/reports/sales',
+      '/blog/:slug',
+      '/products/:id',
+      '/users/:userId/posts/:postId',
+    ],
+  })
+)
+
+/**
+ * Relative file path for local assets
+ *
+ * Must:
+ * - Start with ./ or ../
+ * - Be relative to current file or parent directory
+ *
+ * Used for referencing local assets like images, fonts, and stylesheets.
+ * Relative paths are resolved at build time and work across different environments.
+ *
+ * @example
+ * ```typescript
+ * const logo = './public/logo.svg'
+ * const image = '../images/hero.jpg'
+ * const icon = './assets/icon.png'
+ * ```
+ *
+ * @see specs/app/pages/common/definitions.schema.json#/definitions/relativePath
+ */
+export const RelativePathSchema = Schema.String.pipe(
+  Schema.pattern(/^\.{1,2}\//, {
+    message: () => 'Relative path must start with ./ or ../',
+  }),
+  Schema.annotations({
+    title: 'Relative Path',
+    description: 'Relative file path for local assets',
+    examples: ['./public/logo.svg', '../images/hero.jpg', './assets/icon.png'],
+  })
+)
+
+/**
+ * Hex color code (6-digit format)
+ *
+ * Validates hex color format: #RRGGBB
+ * - Starts with #
+ * - Followed by exactly 6 hex digits (0-9, A-F, case-insensitive)
+ *
+ * Used for:
+ * - Banner background/text colors
+ * - Safari mask-icon color attribute
+ * - Theme color customization
+ *
+ * @example
+ * ```typescript
+ * const primary = '#007BFF'
+ * const success = '#28A745'
+ * const danger = '#DC3545'
+ * const safariMask = '#5BBAD5'
+ * ```
+ *
+ * @see specs/app/common/definitions.schema.json#/definitions/hexColor
+ */
+export const HexColorSchema = Schema.String.pipe(
+  Schema.pattern(/^#[0-9A-Fa-f]{6}$/, {
+    message: () => 'Color must be a 6-digit hex code (e.g., #007BFF, #5BBAD5)',
+  }),
+  Schema.annotations({
+    title: 'Hex Color',
+    description: 'Hex color code in #RRGGBB format',
+    examples: ['#007BFF', '#28A745', '#DC3545', '#5BBAD5'],
+  })
+)
+
+export type Id = Schema.Schema.Type<typeof IdSchema>
+export type Name = Schema.Schema.Type<typeof NameSchema>
+export type Path = Schema.Schema.Type<typeof PathSchema>
+export type RelativePath = Schema.Schema.Type<typeof RelativePathSchema>
+export type HexColor = Schema.Schema.Type<typeof HexColorSchema>

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

@@ -0,0 +1,119 @@
+/**
+ * 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-props'
+
+/**
+ * Component Child Element (component in a component template)
+ *
+ * Represents a single component element with:
+ * - type: Component type (required)
+ * - props: Component properties (optional)
+ * - children: Nested child elements (optional, recursive)
+ * - content: Text content with $variable support (optional)
+ *
+ * Note: This schema is recursive - children can contain more ComponentChildElement objects.
+ *
+ * @example
+ * ```typescript
+ * const iconChild = {
+ *   type: 'icon',
+ *   props: {
+ *     name: '$icon',
+ *     color: '$color',
+ *   },
+ * }
+ *
+ * const textChild = {
+ *   type: 'text',
+ *   content: '$label',
+ * }
+ *
+ * const containerChild = {
+ *   type: 'div',
+ *   props: { className: 'flex gap-2' },
+ *   children: [iconChild, textChild],
+ * }
+ * ```
+ *
+ * @see specs/app/components/common/component-children.schema.json#/items
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- Recursive schema with suspended children requires any for circular reference resolution
+export const ComponentChildElementSchema: Schema.Schema<any, any, never> = Schema.Struct({
+  type: Schema.String.pipe(
+    Schema.annotations({
+      title: 'Component Type',
+      description: 'Component type identifier',
+      examples: ['icon', 'text', 'div', 'button'],
+    })
+  ),
+  props: Schema.optional(ComponentPropsSchema),
+  children: Schema.optional(
+    Schema.suspend(() => ComponentChildrenSchema).pipe(
+      Schema.annotations({
+        identifier: 'ComponentChildren',
+      })
+    )
+  ),
+  content: Schema.optional(
+    Schema.String.pipe(
+      Schema.annotations({
+        title: 'Text Content',
+        description: 'Text content (may contain $variable)',
+        examples: ['$label', '$title', 'Static text'],
+      })
+    )
+  ),
+}).pipe(
+  Schema.annotations({
+    title: 'Component Child Element',
+    description: 'Component element in a component template',
+  })
+)
+
+/**
+ * Component Children (child elements array for component templates)
+ *
+ * Array of component elements or strings that can be nested recursively.
+ * Each child can be:
+ * - ComponentChildElement: Component with type, optional props, optional nested children, and optional content
+ * - String: Direct text content or variable placeholder (e.g., '$title', 'Static text')
+ *
+ * This enables building complex component hierarchies with variable substitution.
+ *
+ * @example
+ * ```typescript
+ * const children = [
+ *   {
+ *     type: 'icon',
+ *     props: {
+ *       name: '$icon',
+ *       color: '$color',
+ *     },
+ *   },
+ *   {
+ *     type: 'text',
+ *     content: '$label',
+ *   },
+ *   '$title', // Direct string (can be variable or static text)
+ * ]
+ * ```
+ *
+ * @see specs/app/components/common/component-children.schema.json
+ */
+export const ComponentChildrenSchema = Schema.Array(
+  Schema.Union(ComponentChildElementSchema, Schema.String)
+).pipe(
+  Schema.annotations({
+    title: 'Component Children',
+    description: 'Child elements array for component templates (components or strings)',
+  })
+)
+
+export type ComponentChildElement = Schema.Schema.Type<typeof ComponentChildElementSchema>
+export type ComponentChildren = Schema.Schema.Type<typeof ComponentChildrenSchema>

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

@@ -0,0 +1,89 @@
+/**
+ * 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 property value (string, number, boolean, object, or array)
+ *
+ * Flexible property values supporting:
+ * - String: May contain $variable references for template substitution
+ * - Number: Numeric values
+ * - Boolean: True/false flags
+ * - Object: Nested property objects
+ * - Array: Lists of values
+ *
+ * @example
+ * ```typescript
+ * const stringProp = 'text-$color bg-$bgColor'
+ * const numberProp = 100
+ * const booleanProp = true
+ * const objectProp = { nested: 'value' }
+ * const arrayProp = [1, 2, 3]
+ * ```
+ *
+ * @see specs/app/components/common/component-props.schema.json#/patternProperties/.../oneOf
+ */
+export const ComponentPropValueSchema: Schema.Schema<
+  string | number | boolean | Record<string, unknown> | readonly unknown[]
+> = Schema.Union(
+  Schema.String,
+  Schema.Number,
+  Schema.Boolean,
+  Schema.Record({ key: Schema.String, value: Schema.Unknown }),
+  Schema.Array(Schema.Unknown)
+)
+
+/**
+ * Component Props (properties for component templates with variable references)
+ *
+ * Dynamic object supporting:
+ * - JavaScript property names (camelCase): className, maxWidth, isEnabled
+ * - HTML data-* attributes (kebab-case): data-testid, data-user-id
+ * - HTML aria-* attributes (kebab-case): aria-label, aria-describedby
+ *
+ * Properties can be strings (with $variable), numbers, booleans, objects, or arrays.
+ * Used for template customization and variable substitution.
+ *
+ * @example
+ * ```typescript
+ * const props = {
+ *   className: 'text-$color bg-$bgColor',
+ *   size: '$size',
+ *   enabled: true,
+ *   maxWidth: 'max-w-$width',
+ *   count: 10,
+ *   'data-testid': 'my-component',
+ *   'aria-label': 'Interactive button',
+ * }
+ * ```
+ *
+ * @see specs/app/components/common/component-props.schema.json
+ */
+export const ComponentPropsSchema = Schema.Record({
+  key: Schema.String.pipe(
+    Schema.pattern(/^([a-zA-Z][a-zA-Z0-9]*|data-[a-z]+(-[a-z]+)*|aria-[a-z]+(-[a-z]+)*)$/, {
+      message: () =>
+        'Property key must be camelCase (e.g., className, maxWidth) or kebab-case with data-/aria- prefix (e.g., data-testid, aria-label)',
+    }),
+    Schema.annotations({
+      title: 'Component Prop Key',
+      description:
+        'Valid JavaScript property name (camelCase) or HTML data-*/aria-* attribute (kebab-case)',
+      examples: ['className', 'size', 'enabled', 'maxWidth', 'data-testid', 'aria-label'],
+    })
+  ),
+  value: ComponentPropValueSchema,
+}).pipe(
+  Schema.annotations({
+    title: 'Component Props',
+    description: 'Properties for component templates, supporting variable references',
+  })
+)
+
+export type ComponentPropValue = Schema.Schema.Type<typeof ComponentPropValueSchema>
+export type ComponentProps = Schema.Schema.Type<typeof ComponentPropsSchema>