Styling Updates: Frontend and Engine Integration Guide

Quick Start Summary

This guide covers styling implementation for form elements and submit buttons in the Cavai system. The architecture requires updates in both Application-Frontend (configuration UI) and Creative-Engine (rendering).

Key Files for Form & Submit Button Styling

Application-Frontend:

• src/pages/Chatbots/components/BuilderVisuals/Blocks/data/types.ts - Type definitions
• src/pages/Chatbots/components/BuilderVisuals/Blocks/data/defaults.ts - Default values
• src/pages/Chatbots/components/BuilderVisuals/Configuration/components/Form/FormSubmitButtonSection.vue - Submit button UI
• src/pages/Chatbots/components/BuilderVisuals/Configuration/configs/FormConfiguration.vue - Event handling

Creative-Engine:

• src/interfaces/jsonTypes/payload-v2/index.ts - Type definitions
• src/components/creative/CreativeFormBlock/CreativeFormBlock.vue - Rendering logic

Current Status

✅ Submit Button Layout Complete:

• Background styling - Working
• Border styling - Working
• Padding - Working
• Border radius - Working

🔧 Submit Button Issues to Fix:

• Text Styles: Font settings not working (typeface, color, font size, weight)
• Text Alignment: Currently works as flex-align, should be text-align
• Offset: Position/margin not working properly
• Size: Should default to width: 100%, height: 100% unlinked
• Shadow: Only soft shadow works, can't select other options or change colors/values

🚀 Next Phase: Fix remaining submit button issues, then implement form subblocks styling

---

Overview

When adding new styling properties to blocks (like submit buttons, HTML elements, etc.), changes must be made in both Application-Frontend and Creative-Engine to ensure proper configuration UI and rendering.

Required File Updates

1. Application-Frontend Changes

A. Type Definitions (/src/pages/Chatbots/components/BuilderVisuals/Blocks/data/types.ts)

• Add new properties to the relevant block type (e.g., SubmitButtonProperties, HtmlProperties)
• Follow existing patterns:
  • Use sizeStyle?: SizeStyle for width/height properties
  • Use style?: PositionStyle & PaddingStyle & MarginStyle for positioning
  • Use boxShadowSettings?: ShadowSettings for shadow properties

B. Default Values (/src/pages/Chatbots/components/BuilderVisuals/Blocks/data/defaults.ts)

• Add default values for all new properties
• Use helper functions like:
  • shadowSettingsDefaults() for shadow properties
  • paddingStyleDefaults() for padding
  • marginStyleDefaults() for margins
  • positionStyleDefaults() for positioning

C. Configuration Component (/src/pages/Chatbots/components/BuilderVisuals/Configuration/components/Form/[BlockName]Section.vue)

• Add UI sections for new properties:
  • <SizeSection> for width/height
  • <PositionSection> for margins/positioning
  • <BoxShadowSection> for shadows
  • <FontSettings> for font properties
• Critical: Use correct event handling pattern:

  @update:width="updateSizeStyle('width', $event.value, $event.postfix)"
  @update:height="updateSizeStyle('height', $event.value, $event.postfix)"

• Add corresponding update methods that handle postfix (units like px, %, em):

  updateSizeStyle(property, value, postfix = '') {
    const fullValue = postfix ? value + postfix : value
    this.$emit('update:sizeStyle', { [property]: fullValue })
  }

D. Configuration Controller (/src/pages/Chatbots/components/BuilderVisuals/Configuration/configs/[BlockName]Configuration.vue)

• Wire up event handlers from the section component
• Add update methods that use updateValue() pattern:

  updateSizeStyle(value) {
    Object.keys(value).forEach(key => {
      this.updateValue(value[key], `submitButtonProperties.sizeStyle.${key}`)
    })
  }

• Connect events in template:

  @update:sizeStyle="updateSizeStyle"

2. Creative-Engine Changes

A. Payload Types (/src/interfaces/jsonTypes/payload-v2/index.ts)

• Mirror the Application-Frontend type definitions
• Ensure all properties from frontend types are included
• Use same structure and naming conventions

B. Rendering Component (/src/components/creative/Creative[BlockName]/Creative[BlockName].vue)

• Update CSS generation to use new properties
• Follow priority patterns:

  // Prioritize sizeStyle over style for size properties
  width: formProps.submitButtonProperties?.sizeStyle?.width || 
         formProps.submitButtonProperties?.style?.width || 'auto'

• Add CSS class selectors for new styling
• Handle fallback values properly

Common Patterns and Best Practices

Size Properties

• Frontend: Use sizeStyle: { width: '100%', height: '100%' } as defaults
• Engine: Prioritize sizeStyle over style for width/height
• UI: Use SizeSection with linkable="true" for locked dimensions

Event Handling

• Always use $event.value and $event.postfix pattern for SizeSection
• Always handle postfix concatenation in update methods
• Never pass raw $event to size-related updates

Shadow Properties

• Frontend: Use shadowSettingsDefaults() for defaults
• Engine: Use generateBoxShadowValue() helper method
• UI: Use BoxShadowSection component

Position/Margin Properties

• Frontend: Use marginStyleDefaults() and positionStyleDefaults()
• Engine: Apply margin to wrapper elements for alignment
• UI: Use PositionSection component

Debugging Checklist

When styling properties don't work:

1. Check Type Definitions: Ensure property exists in both frontend and engine types
2. Check Defaults: Verify default values are set in defaults.ts
3. Check Event Handling: Ensure $event.value and $event.postfix are used correctly
4. Check Update Methods: Verify postfix concatenation is handled
5. Check Engine Rendering: Ensure CSS generation uses correct property paths
6. Check Priority: Ensure engine prioritizes the right property source (sizeStyle vs style)
7. Build Engine: Always run npm run build:library after engine changes

File Reference Quick List

Application-Frontend

• types.ts - Type definitions
• defaults.ts - Default values
• [Block]Section.vue - UI components
• [Block]Configuration.vue - Event handling

Creative-Engine

• payload-v2/index.ts - Type definitions
• Creative[Block]/Creative[Block].vue - Rendering logic

Common Mistakes

1. Missing postfix handling - Size inputs won't save units (px, %, em)
2. Wrong event pattern - Using $event instead of $event.value
3. Missing engine build - Changes won't apply until library is rebuilt
4. Type mismatches - Frontend and engine types must match exactly
5. Missing defaults - Properties show as undefined/0 without proper defaults
6. Wrong priority - Engine should prioritize newer property patterns (sizeStyle over style)

Testing Workflow

1. Add property to frontend types and defaults
2. Add UI component and event handling
3. Test that configuration UI shows correct values
4. Add property to engine types
5. Update engine rendering logic
6. Build engine library (npm run build:library)
7. Test that changes render correctly in preview
8. Verify real-time updates work properly

Submit Button Remaining Issues

The following submit button styling properties still need to be fixed:

High Priority Issues

• Offset (Position/Margin): PositionSection not working properly
• Text Alignment: AlignmentSection not applying to button text
• Font Size: FontSettings size component needs label override to "Font Size" instead of "Size"
• Typeface (Font Family): FontSettings family selection not working

Implementation Notes

• Follow the same event handling pattern as SizeSection ($event.value, $event.postfix)
• Ensure all properties have proper defaults in defaults.ts
• Verify Creative-Engine rendering uses correct CSS properties
• Test that real-time updates work in preview

Form Subblocks Styling Plan

After completing submit button styling, the next major task is to implement comprehensive styling for all form input subblocks (text inputs, email inputs, dropdowns, etc.).

Approach

1. Use Submit Button as Template: Follow the exact same architecture and patterns established for submit button
2. Consistent Property Structure: Use same property naming conventions (sizeStyle, style, boxShadowSettings, etc.)
3. Reuse Components: Leverage existing UI components (SizeSection, FontSettings, AlignmentSection, etc.)
4. Batch Implementation: Update all input types simultaneously to maintain consistency

Form Input Properties to Implement

• Size (width/height) with sizeStyle
• Position/Margin with style object
• Font styling (size, weight, family, color)
• Background styling
• Border styling
• Box shadow
• Text alignment
• Padding

Files to Update for Each Input Type

Application-Frontend:

• types.ts - Add styling properties to FormInputProperties
• defaults.ts - Add default values for all styling properties
• FormInputConfiguration.vue - Add styling sections and event handlers
• Input-specific configuration components (TextInputConfiguration.vue, etc.)

Creative-Engine:

• payload-v2/index.ts - Mirror frontend types
• CreativeFormBlock.vue - Update CSS generation for input styling
• Add per-input CSS class generation

Benefits of This Approach

• Consistent user experience across all form elements
• Reusable code patterns and components
• Easier maintenance and debugging
• Comprehensive styling control for form design

Timeline Estimate

• Submit button completion: 1-2 days
• Form subblocks styling: 3-5 days
• Testing and refinement: 1-2 days

This systematic approach ensures all form elements have the same level of styling control and follows established architectural patterns.