sovrium 0.0.2

package/src/domain/models/app/table/field-types/numeric/decimal-field.ts

@@ -0,0 +1,113 @@
+/**
+ * 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 { BaseFieldSchema } from '../base-field'
+import { validateMinMaxRange } from '../validation-utils'
+
+/**
+ * Decimal Field
+ *
+ * Numeric field for storing numbers with decimal places. Ideal for measurements,
+ * calculations, percentages (as decimals), and any value requiring fractional precision.
+ * Supports configurable precision (number of decimal places) and min/max range validation.
+ * Can be marked as required, unique, or indexed. Stored using DECIMAL database type for
+ * exact precision without floating-point errors.
+ *
+ * Business Rules:
+ * - Precision defines number of decimal places (1-10), defaulting to 2 for common use cases
+ * - DECIMAL storage ensures exact representation without floating-point rounding errors
+ * - Min/max validation optional - useful for enforcing valid ranges
+ * - Precision must be at least 1 (use Integer Field for whole numbers without decimals)
+ * - Indexing recommended for fields used in sorting, filtering, or calculations
+ * - Constant value 'decimal' ensures type safety and enables discriminated unions
+ *
+ * @example
+ * ```typescript
+ * const field = {
+ *   id: 1,
+ *   name: 'weight',
+ *   type: 'decimal',
+ *   required: true,
+ *   precision: 2,
+ *   min: 0.01,
+ *   max: 999.99,
+ *   default: 1.00
+ * }
+ * ```
+ */
+export const DecimalFieldSchema = BaseFieldSchema.pipe(
+  Schema.extend(
+    Schema.Struct({
+      type: Schema.Literal('decimal').pipe(
+        Schema.annotations({
+          description: "Constant value 'decimal' for type discrimination in discriminated unions",
+        })
+      ),
+      precision: Schema.optional(
+        Schema.Int.pipe(
+          Schema.greaterThan(0),
+          Schema.lessThanOrEqualTo(10),
+          Schema.annotations({
+            description: 'Number of decimal places (1-10)',
+          })
+        )
+      ),
+      min: Schema.optional(
+        Schema.Number.pipe(
+          Schema.annotations({
+            description: 'Minimum allowed value (inclusive)',
+          })
+        )
+      ),
+      max: Schema.optional(
+        Schema.Number.pipe(
+          Schema.annotations({
+            description: 'Maximum allowed value (inclusive)',
+          })
+        )
+      ),
+      default: Schema.optional(
+        Schema.Number.pipe(
+          Schema.annotations({
+            description: 'Default decimal value when creating new records',
+          })
+        )
+      ),
+    })
+  ),
+  Schema.filter(validateMinMaxRange),
+  Schema.annotations({
+    title: 'Decimal Field',
+    description:
+      'Numeric field for numbers with decimal places. Supports configurable precision (1-10 decimal places) and min/max range validation. Uses exact DECIMAL storage.',
+    examples: [
+      {
+        id: 1,
+        name: 'weight',
+        type: 'decimal',
+        required: true,
+        precision: 2,
+        min: 0.01,
+        max: 999.99,
+        default: 1.0,
+      },
+      {
+        id: 2,
+        name: 'tax_rate',
+        type: 'decimal',
+        required: true,
+        precision: 4,
+        min: 0,
+        max: 1,
+        default: 0.0825,
+      },
+    ],
+  })
+)
+
+export type DecimalField = Schema.Schema.Type<typeof DecimalFieldSchema>

package/src/domain/models/app/table/field-types/numeric/index.ts

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */
+
+export * from './integer-field'
+export * from './decimal-field'
+export * from './currency-field'
+export * from './percentage-field'
+export * from './rating-field'
+export * from './progress-field'

package/src/domain/models/app/table/field-types/numeric/integer-field.ts

@@ -0,0 +1,98 @@
+/**
+ * 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 { BaseFieldSchema } from '../base-field'
+import { validateMinMaxRange } from '../validation-utils'
+
+/**
+ * Integer Field
+ *
+ * Numeric field for storing whole numbers without decimal places. Ideal for counts,
+ * quantities, IDs, ages, and other discrete numeric values. Supports min/max range
+ * validation to enforce business rules. Can be marked as required, unique, or indexed.
+ * Stored as database integer type for optimal performance and storage efficiency.
+ *
+ * Business Rules:
+ * - Integers only - no decimal places allowed (enforced at validation level)
+ * - Min/max validation optional - useful for enforcing valid ranges (e.g., age >= 0)
+ * - Unique constraint useful for custom ID fields or unique numeric identifiers
+ * - Indexing recommended for fields used in sorting, filtering, or range queries
+ * - Constant value 'integer' ensures type safety and enables discriminated unions
+ *
+ * @example
+ * ```typescript
+ * const field = {
+ *   id: 1,
+ *   name: 'quantity',
+ *   type: 'integer',
+ *   required: true,
+ *   min: 0,
+ *   max: 1000,
+ *   default: 1
+ * }
+ * ```
+ */
+export const IntegerFieldSchema = BaseFieldSchema.pipe(
+  Schema.extend(
+    Schema.Struct({
+      type: Schema.Literal('integer').pipe(
+        Schema.annotations({
+          description: "Constant value 'integer' for type discrimination in discriminated unions",
+        })
+      ),
+      min: Schema.optional(
+        Schema.Number.pipe(
+          Schema.annotations({
+            description: 'Minimum allowed value (inclusive)',
+          })
+        )
+      ),
+      max: Schema.optional(
+        Schema.Number.pipe(
+          Schema.annotations({
+            description: 'Maximum allowed value (inclusive)',
+          })
+        )
+      ),
+      default: Schema.optional(
+        Schema.Int.pipe(
+          Schema.annotations({
+            description: 'Default integer value when creating new records',
+          })
+        )
+      ),
+    })
+  ),
+  Schema.filter(validateMinMaxRange),
+  Schema.annotations({
+    title: 'Integer Field',
+    description:
+      'Numeric field for whole numbers without decimal places. Supports min/max range validation and is optimized for performance.',
+    examples: [
+      {
+        id: 1,
+        name: 'quantity',
+        type: 'integer',
+        required: true,
+        min: 0,
+        max: 1000,
+        default: 1,
+      },
+      {
+        id: 2,
+        name: 'age',
+        type: 'integer',
+        required: false,
+        min: 0,
+        max: 150,
+      },
+    ],
+  })
+)
+
+export type IntegerField = Schema.Schema.Type<typeof IntegerFieldSchema>

package/src/domain/models/app/table/field-types/numeric/percentage-field.ts

@@ -0,0 +1,115 @@
+/**
+ * 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 { BaseFieldSchema } from '../base-field'
+import { validateMinMaxRange } from '../validation-utils'
+
+/**
+ * Percentage Field
+ *
+ * Specialized numeric field for storing percentage values with automatic formatting.
+ * Values are stored as decimals (0-100) and displayed with the % symbol in the UI.
+ * Supports configurable precision for decimal places and min/max range validation.
+ * Can be marked as required, unique, or indexed. Ideal for rates, discounts,
+ * completion status, and other ratio-based metrics.
+ *
+ * Business Rules:
+ * - Values stored as numbers 0-100 (e.g., 25 = 25%, not 0.25)
+ * - UI automatically appends % symbol for display
+ * - Precision defines decimal places (0-10), defaulting to 0 for whole percentages
+ * - Min/max validation useful for enforcing valid ranges (e.g., 0-100)
+ * - Common use cases: tax rates, discounts, completion %, growth rates
+ * - Indexing recommended for fields used in calculations and reporting
+ * - Constant value 'percentage' ensures type safety and enables discriminated unions
+ *
+ * @example
+ * ```typescript
+ * const field = {
+ *   id: 1,
+ *   name: 'discount_rate',
+ *   type: 'percentage',
+ *   required: true,
+ *   precision: 1,
+ *   min: 0,
+ *   max: 100,
+ *   default: 10.0
+ * }
+ * ```
+ */
+export const PercentageFieldSchema = BaseFieldSchema.pipe(
+  Schema.extend(
+    Schema.Struct({
+      type: Schema.Literal('percentage').pipe(
+        Schema.annotations({
+          description:
+            "Constant value 'percentage' for type discrimination in discriminated unions",
+        })
+      ),
+      precision: Schema.optional(
+        Schema.Int.pipe(
+          Schema.greaterThanOrEqualTo(0),
+          Schema.lessThanOrEqualTo(10),
+          Schema.annotations({
+            description: 'Number of decimal places (0-10, default: 0 for whole percentages)',
+          })
+        )
+      ),
+      min: Schema.optional(
+        Schema.Number.pipe(
+          Schema.annotations({
+            description: 'Minimum allowed percentage value (inclusive, typically 0)',
+          })
+        )
+      ),
+      max: Schema.optional(
+        Schema.Number.pipe(
+          Schema.annotations({
+            description: 'Maximum allowed percentage value (inclusive, typically 100)',
+          })
+        )
+      ),
+      default: Schema.optional(
+        Schema.Number.pipe(
+          Schema.annotations({
+            description: 'Default percentage value when creating new records',
+          })
+        )
+      ),
+    })
+  ),
+  Schema.filter(validateMinMaxRange),
+  Schema.annotations({
+    title: 'Percentage Field',
+    description:
+      'Specialized numeric field for percentage values (0-100). Values automatically display with % symbol in UI. Supports configurable decimal precision.',
+    examples: [
+      {
+        id: 1,
+        name: 'discount_rate',
+        type: 'percentage',
+        required: true,
+        precision: 1,
+        min: 0,
+        max: 100,
+        default: 10.0,
+      },
+      {
+        id: 2,
+        name: 'completion',
+        type: 'percentage',
+        required: true,
+        precision: 0,
+        min: 0,
+        max: 100,
+        default: 0,
+      },
+    ],
+  })
+)
+
+export type PercentageField = Schema.Schema.Type<typeof PercentageFieldSchema>

package/src/domain/models/app/table/field-types/numeric/progress-field.ts

@@ -0,0 +1,71 @@
+/**
+ * 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 { BaseFieldSchema } from '../base-field'
+
+/**
+ * Progress Field
+ *
+ * Displays a percentage value as a progress bar.
+ * Used for tracking completion status, goals, or percentages.
+ * Supports optional color customization for the progress bar.
+ * Values are typically stored as numbers between 0 and 100.
+ *
+ * @example
+ * ```typescript
+ * const field = {
+ *   id: 1,
+ *   name: 'task_completion',
+ *   type: 'progress',
+ *   required: true,
+ *   color: '#10B981'
+ * }
+ * ```
+ */
+export const ProgressFieldSchema = BaseFieldSchema.pipe(
+  Schema.extend(
+    Schema.Struct({
+      type: Schema.Literal('progress'),
+      color: Schema.optional(
+        Schema.String.pipe(
+          Schema.pattern(/^#[0-9a-fA-F]{6}$/, {
+            message: () => 'Color of the progress bar',
+          }),
+          Schema.annotations({
+            description: 'Color of the progress bar',
+          })
+        )
+      ),
+      default: Schema.optional(
+        Schema.Number.pipe(
+          Schema.greaterThanOrEqualTo(0),
+          Schema.lessThanOrEqualTo(100),
+          Schema.annotations({
+            description: 'Default progress value (0-100) when creating new records',
+          })
+        )
+      ),
+    })
+  ),
+  Schema.annotations({
+    title: 'Progress Field',
+    description:
+      'Displays percentage value as progress bar. Used for tracking completion status or goals.',
+    examples: [
+      {
+        id: 1,
+        name: 'task_completion',
+        type: 'progress',
+        required: true,
+        color: '#10B981',
+      },
+    ],
+  })
+)
+
+export type ProgressField = Schema.Schema.Type<typeof ProgressFieldSchema>

package/src/domain/models/app/table/field-types/numeric/rating-field.ts

@@ -0,0 +1,74 @@
+/**
+ * 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 { BaseFieldSchema } from '../base-field'
+
+/**
+ * Rating Field
+ *
+ * Allows users to assign a rating value (e.g., 1-5 stars, 1-10 points).
+ * Supports configurable maximum rating value and visual style.
+ * Typically rendered as stars, hearts, or other rating indicators in the UI.
+ *
+ * @example
+ * ```typescript
+ * const field = {
+ *   id: 1,
+ *   name: 'product_rating',
+ *   type: 'rating',
+ *   max: 5,
+ *   style: 'stars'
+ * }
+ * ```
+ */
+export const RatingFieldSchema = BaseFieldSchema.pipe(
+  Schema.extend(
+    Schema.Struct({
+      type: Schema.Literal('rating'),
+      max: Schema.optional(
+        Schema.Int.pipe(
+          Schema.greaterThanOrEqualTo(1),
+          Schema.lessThanOrEqualTo(10),
+          Schema.annotations({
+            description: 'Maximum rating value',
+          })
+        )
+      ),
+      style: Schema.optional(
+        Schema.String.pipe(
+          Schema.annotations({
+            description: 'Visual style for the rating',
+          })
+        )
+      ),
+      default: Schema.optional(
+        Schema.Int.pipe(
+          Schema.annotations({
+            description: 'Default rating value when creating new records',
+          })
+        )
+      ),
+    })
+  ),
+  Schema.annotations({
+    title: 'Rating Field',
+    description:
+      'Allows rating values with configurable maximum. Typically rendered as stars or other indicators.',
+    examples: [
+      {
+        id: 1,
+        name: 'product_rating',
+        type: 'rating',
+        max: 5,
+        style: 'stars',
+      },
+    ],
+  })
+)
+
+export type RatingField = Schema.Schema.Type<typeof RatingFieldSchema>

package/src/domain/models/app/table/field-types/relational/index.ts

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+
+export * from './relationship-field'
+export * from './lookup-field'
+export * from './rollup-field'

package/src/domain/models/app/table/field-types/relational/lookup-field.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 { ViewFiltersSchema } from '../../views/filters'
+import { BaseFieldSchema } from '../base-field'
+
+export const LookupFieldSchema = BaseFieldSchema.pipe(
+  Schema.extend(
+    Schema.Struct({
+      type: Schema.Literal('lookup'),
+      relationshipField: Schema.String.pipe(
+        Schema.nonEmptyString({ message: () => 'relationshipField is required' }),
+        Schema.annotations({ description: 'Name of the relationship field to lookup from' })
+      ),
+      relatedField: Schema.String.pipe(
+        Schema.nonEmptyString({ message: () => 'relatedField is required' }),
+        Schema.annotations({ description: 'Name of the field in the related table to display' })
+      ),
+      filters: Schema.optional(
+        ViewFiltersSchema.pipe(
+          Schema.annotations({ description: 'Filters to apply to the lookup results' })
+        )
+      ),
+    })
+  ),
+  Schema.annotations({
+    title: 'Lookup Field',
+    description: 'Displays values from related records without aggregation.',
+    examples: [
+      {
+        id: 1,
+        name: 'customer_email',
+        type: 'lookup',
+        relationshipField: 'customer',
+        relatedField: 'email',
+      },
+    ],
+  })
+)
+
+export type LookupField = Schema.Schema.Type<typeof LookupFieldSchema>

package/src/domain/models/app/table/field-types/relational/relationship-field.ts

@@ -0,0 +1,112 @@
+/**
+ * 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 { BaseFieldSchema } from '../base-field'
+
+export const RelationshipFieldSchema = BaseFieldSchema.pipe(
+  Schema.extend(
+    Schema.Struct({
+      type: Schema.Literal('relationship'),
+      relatedTable: Schema.String.pipe(
+        Schema.nonEmptyString({ message: () => 'relatedTable is required' }),
+        Schema.annotations({
+          description: 'Name of the related table',
+        })
+      ),
+      relationType: Schema.optionalWith(
+        Schema.String.pipe(
+          Schema.nonEmptyString({ message: () => 'relationType is required' }),
+          Schema.annotations({
+            description: 'Type of relationship (defaults to many-to-one if not specified)',
+          })
+        ),
+        { default: () => 'many-to-one' as const }
+      ),
+      foreignKey: Schema.optional(
+        Schema.String.pipe(
+          Schema.nonEmptyString({ message: () => 'foreignKey is required' }),
+          Schema.annotations({
+            description:
+              'Name of the foreign key field in the related table for one-to-many relationships',
+          })
+        )
+      ),
+      displayField: Schema.optional(
+        Schema.String.pipe(
+          Schema.nonEmptyString({ message: () => 'displayField is required' }),
+          Schema.annotations({
+            description: 'Field from related table to display in UI',
+          })
+        )
+      ),
+      onDelete: Schema.optional(
+        Schema.String.pipe(
+          Schema.annotations({
+            description: 'Action to take when the related record is deleted',
+          })
+        )
+      ),
+      onUpdate: Schema.optional(
+        Schema.String.pipe(
+          Schema.annotations({
+            description: "Action to take when the related record's key is updated",
+          })
+        )
+      ),
+      reciprocalField: Schema.optional(
+        Schema.String.pipe(
+          Schema.nonEmptyString({ message: () => 'reciprocalField is required' }),
+          Schema.annotations({
+            description:
+              'Name of the reciprocal link field in the related table for bidirectional relationships',
+          })
+        )
+      ),
+      allowMultiple: Schema.optional(
+        Schema.Boolean.pipe(
+          Schema.annotations({
+            description:
+              'Whether to allow linking to multiple records (default: true for many-to-many)',
+          })
+        )
+      ),
+      limitToView: Schema.optional(
+        Schema.String.pipe(
+          Schema.nonEmptyString({ message: () => 'limitToView is required' }),
+          Schema.annotations({
+            description: 'Name of the view to limit linkable records to',
+          })
+        )
+      ),
+      relatedField: Schema.optional(
+        Schema.String.pipe(
+          Schema.nonEmptyString({ message: () => 'relatedField is required' }),
+          Schema.annotations({
+            description:
+              'Name of the field in the related table to reference (defaults to id). The referenced field must have a primary key or unique constraint.',
+          })
+        )
+      ),
+    })
+  ),
+  Schema.annotations({
+    title: 'Relationship Field',
+    description: 'Links records to another table with referential integrity.',
+    examples: [
+      {
+        id: 1,
+        name: 'author',
+        type: 'relationship',
+        relatedTable: 'users',
+        relationType: 'many-to-one',
+      },
+    ],
+  })
+)
+
+export type RelationshipField = Schema.Schema.Type<typeof RelationshipFieldSchema>