🔗 Smart Properties: Full Reusability Architecture

How we connect frontend smart properties with backend properties for 100% reusability

🎯 The Full Picture

┌──────────────────────────────────────────────────────────────────┐
│ BACKEND (MongoDB)                                                 │
│ gograb-core.core_properties                                      │
├──────────────────────────────────────────────────────────────────┤
│ • core_label (id: "core_label")                                  │
│   - aiContext: "Main text content visible to users"              │
│   - controlType: "text"                                          │
│   - themeVariable: null                                          │
│   - tags: ["text", "content", "common"]                          │
│                                                                   │
│ • core_size (id: "core_size")                                    │
│   - aiContext: "Use sm, md, lg for consistent sizing"            │
│   - controlType: "select"                                        │
│   - options: [sm, md, lg]                                        │
│   - themeVariable: null                                          │
│                                                                   │
│ • custom_buttonVariant (id: "custom_buttonVariant")              │
│   - aiContext: "primary (main actions), secondary (less         │
│                 important), ghost (text only), danger            │
│                 (destructive)"                                   │
│   - controlType: "select"                                        │
│   - options: [primary, secondary, ghost, danger]                 │
│   - tags: ["button", "appearance", "variant"]                    │
└──────────────────────────────────────────────────────────────────┘
                              ↓
                    Rich metadata flows down
                              ↓
┌──────────────────────────────────────────────────────────────────┐
│ FRONTEND SMART PROPERTIES                                         │
│ @libs-foundational/core-properties                               │
├──────────────────────────────────────────────────────────────────┤
│ SmartButtonProperties.variant()                                  │
│ → Returns ParameterMetadata with:                                │
│   - name: 'variant'                                              │
│   - type: 'enum' (matches backend controlType)                   │
│   - options: [primary, secondary, ghost, danger]                 │
│   - transform: mapButtonVariant (CSS class mapper)               │
│   - group: 'style'                                               │
│   - order: 1                                                     │
│                                                                   │
│ createSelectProperty({ name, options, transform })               │
│ → Factory that creates standardized ParameterMetadata            │
│ → Ensures consistency across all embeddables                     │
└──────────────────────────────────────────────────────────────────┘
                              ↓
                   Used in embeddable definitions
                              ↓
┌──────────────────────────────────────────────────────────────────┐
│ EMBEDDABLE DEFINITION                                             │
│ @embeddables/embeddable-schemas/button.embeddable.ts            │
├──────────────────────────────────────────────────────────────────┤
│ export const BUTTON_EMBEDDABLE = {                               │
│   inputs: [                                                      │
│     SmartButtonProperties.variant({ order: 1 }),                │
│     SmartButtonProperties.size({ order: 2 }),                   │
│     SmartGlobalProperties.disabled({ order: 1 }),               │
│   ]                                                              │
│ }                                                                │
│                                                                   │
│ Result: ParameterMetadata[] with all backend context            │
└──────────────────────────────────────────────────────────────────┘
                              ↓
                   Consumed by components
                              ↓
┌──────────────────────────────────────────────────────────────────┐
│ COMPONENT (UI Atom)                                               │
│ @libs-ui-core/ui-core/ui-button.component.ts                    │
├──────────────────────────────────────────────────────────────────┤
│ @Input() variant = 'primary';                                    │
│ @Input() size = 'md';                                            │
│ @Input() disabled = false;                                       │
│                                                                   │
│ // Mappers transform values to CSS classes                       │
│ get variantClass() {                                             │
│   return mapButtonVariant(this.variant);                         │
│   // 'primary' → 'btn-primary'                                  │
│ }                                                                │
└──────────────────────────────────────────────────────────────────┘

🔄 How Smart Properties Bridge Backend & Frontend

Current State (Hybrid Approach)

Smart Properties = Type-Safe Factories with Backend Alignment

// Smart property factory
export const SmartButtonProperties = {
  variant: (overrides: Partial<ParameterMetadata> = {}) => ({
    ...createSelectProperty({
      name: 'variant',
      label: 'Variant',
      description: 'Visual style variant',
      defaultValue: 'primary',
      options: [
        { value: 'primary', label: 'Primary (Solid)' },
        // These options MATCH backend 'custom_buttonVariant' property
      ],
      transform: mapButtonVariant, // CSS mapper
    }),
    ...overrides // Allow customization per usage
  })
};

Why this works:

1. ✅ Type-safe: Returns ParameterMetadata (compatible with embeddables)
2. ✅ Reusable: One definition used across all button embeddables
3. ✅ Mappable: Includes transform function for CSS class generation
4. ✅ Backend-aligned: Options match backend property definitions
5. ✅ Customizable: Supports overrides for specific use cases

Using Smart Properties in Embeddables

// Before (Hardcoded - 50+ lines per property):
export const BUTTON_EMBEDDABLE = {
  inputs: [
    {
      name: 'variant',
      type: 'string',
      required: false,
      description: 'Button variant: primary | secondary | ghost | danger',
      defaultValue: 'primary',
      group: 'style',
      order: 1,
      transform: mapButtonVariant,
      options: [
        { value: 'primary', label: 'Primary (Solid)' },
        { value: 'secondary', label: 'Secondary (Outline)' },
        { value: 'ghost', label: 'Ghost (Text Only)' },
        { value: 'danger', label: 'Danger (Destructive)' },
      ],
    },
    // ... repeat for 10+ properties = 500+ lines
  ]
};

// After (Smart Properties - 1 line per property):
export const BUTTON_EMBEDDABLE = {
  inputs: [
    SmartButtonProperties.variant({ order: 1 }),
    SmartButtonProperties.size({ order: 2 }),
    SmartButtonProperties.shape({ order: 3 }),
    SmartGlobalProperties.disabled({ order: 1 }),
    // ... 10 properties = ~10 lines
  ]
};

Reduction: 500+ lines → 10 lines = 98% less code!

🌉 The Future: Property References

Next Evolution: Instead of smart factories, reference backend IDs

// FUTURE STATE (Property References):
export const BUTTON_EMBEDDABLE = {
  inputs: [
    { propertyId: 'core_label', bindTo: 'text' },
    { propertyId: 'custom_buttonVariant', bindTo: 'variant' },
    { propertyId: 'core_size', bindTo: 'size' },
    { propertyId: 'core_disabled', bindTo: 'disabled' },
  ]
};

// Runtime resolution:
// 1. Fetch 'custom_buttonVariant' from backend
// 2. Get aiContext, options, theme variables
// 3. Apply mapper (transform: 'mapButtonVariant')
// 4. Merge with override (order, group)
// 5. Return ResolvedProperty

Benefits:

• ✅ Backend updates instantly reflected (no code deploy)
• ✅ AI context flows through automatically
• ✅ Usage tracking works (backend knows which properties are used)
• ✅ Property definitions stored in MongoDB (true single source)

🧬 Smart Property Factories Explained

Base Factories

/**
 * Creates a select/enum property
 * Aligns with backend controlType: "select"
 */
export function createSelectProperty(config) {
  return {
    name: config.name,
    type: 'enum', // ParameterType
    required: false,
    label: config.label,
    defaultValue: config.defaultValue,
    options: config.options, // Matches backend validation.options
    transform: config.transform, // Mapper function
    group: config.group || 'style',
    order: config.order || 1,
  } as ParameterMetadata;
}

/**
 * Creates a boolean property
 * Aligns with backend controlType: "boolean"
 */
export function createBooleanProperty(config) {
  return {
    name: config.name,
    type: 'boolean',
    required: false,
    defaultValue: config.defaultValue ?? false,
    // ...
  } as ParameterMetadata;
}

/**
 * Creates a text property
 * Aligns with backend controlType: "text"
 */
export function createTextProperty(config) {
  return {
    name: config.name,
    type: 'string',
    required: config.required ?? false,
    defaultValue: config.defaultValue ?? '',
    // ...
  } as ParameterMetadata;
}

Component-Specific Smart Properties

// Button-specific properties
export const SmartButtonProperties = {
  variant: (overrides) => ({
    ...createSelectProperty({/* button variant config */}),
    ...overrides
  }),
  size: (overrides) => ({
    ...createSelectProperty({/* size config */}),
    ...overrides
  }),
  shape: (overrides) => ({
    ...createSelectProperty({/* shape config */}),
    ...overrides
  }),
};

// Global reusable properties
export const SmartGlobalProperties = {
  colorTone: (overrides) => ({
    ...createSelectProperty({/* color config */}),
    ...overrides
  }),
  disabled: (overrides) => ({
    ...createBooleanProperty({/* disabled config */}),
    ...overrides
  }),
  loading: (overrides) => ({
    ...createBooleanProperty({/* loading config */}),
    ...overrides
  }),
};

🎯 Reusability Patterns

Pattern 1: Cross-Component Reuse

// Many components use 'size' property
export const BUTTON_EMBEDDABLE = {
  inputs: [SmartButtonProperties.size({ order: 2 })],
};

export const INPUT_EMBEDDABLE = {
  inputs: [SmartButtonProperties.size({ order: 1 })], // ✅ Same mapper
};

export const CARD_EMBEDDABLE = {
  inputs: [SmartButtonProperties.size({ order: 1 })], // ✅ Same mapper
};

Result: One mapSize function used everywhere!

Pattern 2: Variant Customization

// Button variant
SmartButtonProperties.variant({ order: 1 })

// Alert variant (different options, same pattern)
SmartGlobalProperties.variant({
  options: [
    { value: 'info', label: 'Info' },
    { value: 'warning', label: 'Warning' },
    { value: 'error', label: 'Error' },
    { value: 'success', label: 'Success' },
  ],
  order: 1
})

Pattern 3: State Properties

// ALL components with state use these
export const BUTTON_EMBEDDABLE = {
  inputs: [
    SmartGlobalProperties.disabled({ order: 1 }),
    SmartGlobalProperties.loading({ order: 2 }),
  ]
};

export const INPUT_EMBEDDABLE = {
  inputs: [
    SmartGlobalProperties.disabled({ order: 1 }), // ✅ Reused
  ]
};

🔧 Property Mappers: The Secret Sauce

Mappers transform user-friendly values to CSS classes

// In @libs-foundational/core-properties/property-mappers.ts

export function mapButtonVariant(value: unknown): string {
  const variant = String(value || 'primary');
  
  const classMap = {
    primary: 'btn-primary',
    secondary: 'btn-secondary',
    ghost: 'btn-ghost',
    danger: 'btn-danger',
  };
  
  return classMap[variant] || 'btn-primary';
}

export function mapSize(value: unknown): string {
  const size = String(value || 'md');
  
  const classMap = {
    sm: 'size-sm',
    md: 'size-md',
    lg: 'size-lg',
  };
  
  return classMap[size] || 'size-md';
}

Usage in component:

export class UiButtonComponent {
  @Input() variant = 'primary';
  @Input() size = 'md';
  
  // Computed CSS classes
  variantClass = computed(() => mapButtonVariant(this.variant()));
  sizeClass = computed(() => mapSize(this.size()));
  
  // Combined classes
  hostClasses = computed(() => [
    'ui-button',
    this.variantClass(),
    this.sizeClass(),
  ].join(' '));
}

📊 Reusability Metrics

Before Smart Properties

After Smart Properties

Result: 1,350 → 24 lines = 98.2% reduction!

🚀 Next Steps: Full Backend Integration

Phase 1: Sync Smart Properties with Backend

# Backend: Ensure all smart properties exist in MongoDB
POST /api/properties
{
  "id": "custom_buttonVariant",
  "key": "buttonVariant",
  "controlType": "select",
  "aiContext": "Button variants: primary (solid), secondary (outline)...",
  "options": [...] // Same as SmartButtonProperties.variant
}

Phase 2: Add Property References

// Update embeddables to reference backend IDs
export const BUTTON_EMBEDDABLE = {
  inputs: [
    { propertyId: 'custom_buttonVariant', bindTo: 'variant' },
    { propertyId: 'core_size', bindTo: 'size' },
  ]
};

Phase 3: PropertyResolverService

// Runtime resolution with caching
const resolved = await propertyResolver.resolveEmbeddableProperties('ui-button');

// Returns Map<bindTo, ResolvedProperty>
resolved.get('variant'); // { id: 'custom_buttonVariant', ..., transformFn: mapButtonVariant }

✅ Current State Summary

What We Have:

• ✅ Smart property factories (type-safe, reusable)
• ✅ Property mappers (CSS transformation)
• ✅ Backend properties (rich metadata, AI context)
• ⚠️ Manual sync required (frontend factories ↔ backend definitions)

What We're Building:

• ⏭️ Property references (backend IDs)
• ⏭️ PropertyResolverService (runtime resolution)
• ⏭️ Automatic sync (backend updates flow through)
• ⏭️ Full AI integration (leverage backend metadata)

Timeline: 5-6 sessions for complete rollout

Status: 🟡 Hybrid State (Smart Factories + Backend Alignment)
Next: PropertyResolverService implementation
Goal: Full backend property reference system