Migrating from UX Components to Widget Components

This guide explains how to migrate from the ux-widgets components to the new widgets library components.

Overview

The ux-widgets library is being gradually replaced by the new widgets library, which offers improved standardization, better performance, and a more flexible API. This document provides guidance on how to migrate your code from UxButtonComponent to ButtonWidgetComponent.

Migrating from UxButtonComponent to ButtonWidgetComponent

The UxButtonComponent is being replaced by the ButtonWidgetComponent from the widgets library. The new component uses the standardized widget API with signals and a more consistent property structure.

Property Mapping

Events Mapping

Example Migration

Before (UxButtonComponent)

<editor-ux-button
  text="Submit"
  buttonType="primary"
  size="medium"
  [rounded]="true"
  [loading]="isLoading"
  [disabled]="!isValid"
  iconName="check"
  iconPosition="right"
  (buttonClick)="onSubmit($event)"
></editor-ux-button>

@Component({
  selector: 'app-example',
  template: `...`
})
export class ExampleComponent {
  isLoading = false;
  isValid = true;

  onSubmit(event: MouseEvent) {
    // Handle button click
  }
}

After (ButtonWidgetComponent)

<lib-button-widget
  [widget]="buttonWidget()"
  [isPreview]="true"
  (widgetAction)="onWidgetAction($event)"
></lib-button-widget>

import { Component, signal, computed } from '@angular/core';
import { ButtonWidgetComponent } from '@widgets';
import { Widget, WidgetType } from '@widgets-editor/core';

@Component({
  selector: 'app-example',
  imports: [ButtonWidgetComponent],
  template: `...`,
  standalone: true
})
export class ExampleComponent {
  isLoading = signal(false);
  isValid = signal(true);

  buttonWidget = computed<Widget>(() => {
    return {
      id: 'submit-button',
      type: WidgetType.BUTTON,
      name: 'Submit Button',
      position: { x: 0, y: 0, constrainToParent: false },
      size: { width: 0, height: 0, minWidth: 0, minHeight: 0, responsive: false },
      rotation: 0,
      zIndex: 1,
      styles: {},
      properties: {
        text: 'Submit',
        buttonType: 'primary',
        size: 'medium',
        rounded: true,
        loading: this.isLoading(),
        disabled: !this.isValid(),
        icon: 'check',
        iconPosition: 'right',
        action: 'event',
        eventName: 'submit'
      },
      visible: true,
      locked: false,
      createdAt: new Date(),
      updatedAt: new Date()
    };
  });

  onWidgetAction(event: { widget: Widget; action: string; data?: any }) {
    if (event.action === 'submit') {
      // Handle button click (equivalent to old onSubmit)
    }
  }
}

Helper Functions

For convenience, you can create helper functions to simplify the migration process:

import { Widget, WidgetType } from '@widgets-editor/core';
import { ButtonWidgetConfig } from '@widgets';

export function createButtonWidget(
  id: string,
  properties: ButtonWidgetConfig
): Widget {
  return {
    id,
    type: WidgetType.BUTTON,
    name: `Button: ${properties.text || 'Button'}`,
    position: { x: 0, y: 0, constrainToParent: false },
    size: { width: 0, height: 0, minWidth: 0, minHeight: 0, responsive: false },
    rotation: 0,
    zIndex: 1,
    styles: {},
    properties,
    visible: true,
    locked: false,
    createdAt: new Date(),
    updatedAt: new Date()
  };
}

With this helper, the example becomes:

buttonWidget = computed<Widget>(() => {
  return createButtonWidget('submit-button', {
    text: 'Submit',
    buttonType: 'primary',
    size: 'medium',
    rounded: true,
    loading: this.isLoading(),
    disabled: !this.isValid(),
    icon: 'check',
    iconPosition: 'right',
    action: 'event',
    eventName: 'submit'
  });
});

Migrating Theme Styles

The UxButtonComponent used a theme property to apply custom styles. In ButtonWidgetComponent, you should use the styles property of the widget instead.

Example Theme Migration

Before (UxButtonComponent)

<editor-ux-button
  text="Custom"
  [theme]="{
    backgroundColor: '#5200ee',
    color: '#ffffff',
    borderRadius: '8px',
    fontSize: '16px'
  }"
></editor-ux-button>

After (ButtonWidgetComponent)

buttonWidget = computed<Widget>(() => {
  return {
    // ...other widget properties
    styles: {
      backgroundColor: '#5200ee',
      color: '#ffffff',
      borderRadius: 8,
      fontSize: 16
    },
    properties: {
      text: 'Custom',
      buttonType: 'custom',
      // ...other button properties
    }
  };
});

Conclusion

By migrating to the new widget components, you'll benefit from improved standardization, better performance, and a more consistent API across the entire widget system. The migration path is straightforward with the property mappings provided above.

For more information about the available widget components and their APIs, refer to the Widget Library documentation.