kramme:connect-modernize-legacy-angular-component

Connect - Modernize Legacy Angular Component

Instructions

When to use this skill:

• You're working in the Connect monorepo
• You need to refactor legacy Angular components to modern patterns
• Component extends legacy FormComponent or BaseComponent
• Component uses @Select decorators for state management
• Component uses FormNode instead of typed FormGroup
• Component doesn't use ChangeDetectionStrategy.OnPush
• Component has manual subscription management
• Component dispatches actions directly instead of using ComponentStore

Context: Connect's frontend is modernizing Angular components to use NgRx ComponentStore for state management, OnPush change detection, standalone components, and proper TypeScript typing. This provides better type safety, performance, and maintainability.

Guideline Keywords

• ALWAYS — Mandatory requirement, exceptions are very rare and must be explicitly approved
• NEVER — Strong prohibition, exceptions are very rare and must be explicitly approved
• PREFER — Strong recommendation, exceptions allowed with justification
• CAN — Optional, developer's discretion
• NOTE — Context, rationale, or clarification
• EXAMPLE — Illustrative example

Strictness hierarchy: ALWAYS/​NEVER > PREFER > CAN > NOTE/​EXAMPLE

---

Reference Implementation

• ALWAYS refer to the Q&A components refactoring as the reference implementation:
  • libs/​connect/​cms/​qa/​feature/​src/​lib/​edit-topic/ - Edit topic component with form management
  • libs/​connect/​cms/​qa/​feature/​src/​lib/​settings-page/ - Settings page with conditional form logic
  • libs/​connect/​cms/​qa/​feature/​src/​lib/​topics-page/ - Topics page with complex state

---

Migration Process

Phase 1: Assessment

• ALWAYS read all component files before starting:

  • Component TypeScript file
  • Component template
  • Component styles (if any)
  • Related store/​state files

• ALWAYS identify patterns to migrate:

  • Legacy base class usage (extends FormComponent, extends BaseComponent)
  • @Select decorators for state
  • FormNode usage
  • Manual subscriptions (subscribe(), takeUntil())
  • Direct action dispatching
  • Lifecycle hooks (onInit() vs ngOnInit())

• ALWAYS identify business logic:

  • Form management
  • State updates
  • API calls
  • Conditional field logic
  • User interactions

---

Phase 2: Create ComponentStore

• ALWAYS create the store file in the same directory as the component (e.g., component-name.store.ts)
• ALWAYS define form controls interface separately from state
• ALWAYS define forms as class properties, NOT in state
• ALWAYS extract initialState as a constant
• ALWAYS use readonly for immutability
• ALWAYS use ECMAScript #privateFields for encapsulation
• ALWAYS use proper type narrowing in effects with filter: (tuple): tuple is [void, DataType] => tuple[1] !== null
• ALWAYS use pipe() directly in effects: this.effect<Type>(pipe(...)) not this.effect<Type>((param$) => param$.pipe(...))

EXAMPLE:

import { inject, Injectable } from "@angular/​core";
import { ComponentStore } from "@ngrx/​component-store";
import { Store } from "@ngrx/​store";
import { FormControl, FormGroup, Validators } from "@angular/​forms";
import { filter, pipe, switchMap, tap, withLatestFrom } from "rxjs";

// Define form controls interface
export interface ComponentNameFormControls {
  field1: FormControl<string>;
  field2: FormControl<boolean>;
}

// Define state interface
interface ComponentNameState {
  readonly currentData: DataType | null;
}

const initialState: ComponentNameState = {
  currentData: null,
};

@Injectable()
export class ComponentNameStore extends ComponentStore<ComponentNameState> {
  readonly #store = inject(Store);

  // Selectors
  readonly currentData$ = this.select((state) => state.currentData);
  readonly externalData$ = this.#store.select(getExternalData.selector);

  // Form definition
  readonly form = new FormGroup<ComponentNameFormControls>({
    field1: new FormControl<string>("", {
      validators: [Validators.required],
      nonNullable: true,
    }),
    field2: new FormControl<boolean>(false, { nonNullable: true }),
  });

  // Updaters
  readonly setCurrentData = this.updater<DataType>(
    (state, data): ComponentNameState => ({
      ...state,
      currentData: data,
    })
  );

  // Effects - use pipe() directly
  readonly initializeForm = this.effect<DataType>(
    pipe(
      tap((data: DataType) => {
        this.setCurrentData(data);
        this.form.reset(data);
        this.#applyConditionalLogic(this.form);
      })
    )
  );

  readonly saveChanges = this.effect<void>(
    pipe(
      tap(() => {
        this.#store.dispatch(updateAction.start(this.form.getRawValue()));
      })
    )
  );

  readonly cancelChanges = this.effect<void>(
    pipe(
      withLatestFrom(this.currentData$),
      filter((tuple): tuple is [void, DataType] => tuple[1] !== null),
      tap(([, data]) => {
        this.form.reset(data);
        this.#applyConditionalLogic(this.form);
      })
    )
  );

  // Private methods
  #applyConditionalLogic(form: FormGroup<ComponentNameFormControls>): void {
    // Conditional enabling/​disabling logic
  }

  constructor() {
    super(initialState);
    // Initialize effects that don't take parameters
    this.applyConditionalDisabling();
  }
}

---

Phase 3: Refactor Component

• ALWAYS add ChangeDetectionStrategy.OnPush
• ALWAYS add standalone: true
• ALWAYS add ComponentStore to providers array
• ALWAYS use inject() for dependency injection
• ALWAYS place all inject() calls first in the class as readonly fields
• ALWAYS use ECMAScript #privateField syntax for private members
• NEVER use the public or private keywords in TypeScript
• ALWAYS remove base class extensions
• ALWAYS remove @Select decorators
• ALWAYS remove manual subscriptions
• ALWAYS remove DestroyRef and takeUntilDestroyed (ComponentStore handles cleanup)

EXAMPLE:

import {
  ChangeDetectionStrategy,
  Component,
  inject,
  Input,
} from "@angular/​core";
import { animate, style, transition, trigger } from "@angular/​animations";
import { ComponentNameStore } from "./​component-name.store";

@Component({
  selector: "co-component-name",
  templateUrl: "./​component-name.component.html",
  standalone: true,
  changeDetection: ChangeDetectionStrategy.OnPush,
  providers: [ComponentNameStore],
  imports: [
    // Only what you need
  ],
  animations: [
    trigger("slideDown", [
      transition(":enter", [
        style({ height: "0", opacity: 0, overflow: "hidden" }),
        animate("300ms ease-out", style({ height: "*", opacity: 1 })),
      ]),
      transition(":leave", [
        style({ height: "*", opacity: 1, overflow: "hidden" }),
        animate("300ms ease-in", style({ height: "0", opacity: 0 })),
      ]),
    ]),
  ],
})
export class ComponentNameComponent {
  readonly #componentStore = inject(ComponentNameStore);

  @Input() set data(data: DataType) {
    if (data) {
      this.#componentStore.initializeForm(data);
    }
  }

  readonly form = this.#componentStore.form;
  readonly data$ = this.#componentStore.currentData$;

  saveChanges(): void {
    this.#componentStore.saveChanges();
  }

  cancelChanges(): void {
    this.#componentStore.cancelChanges();
  }
}

---

Phase 4: Update Template

• ALWAYS use native control flow (@if, @for, @switch) instead of *ngIf, *ngFor, *ngSwitch
• ALWAYS use the *ngrxLet directive or ngrxPush pipe to handle Observables
  • ALWAYS prefer the ngrxPush pipe over async for one-off async bindings
  • PREFER not using *ngrxLet or ngrxPush multiple times for the same Observable; instead assign it to a template variable using @let
• PREFER adding animations for conditional UI
• ALWAYS use form bindings with proper type checking

EXAMPLE - Native control flow with animation:

@if (form.controls.parentField.value) {
<div @slideDown>
  <mat-slide-toggle formControlName="childField">
    Child Field
  </​mat-slide-toggle>
</​div>
}

EXAMPLE - Form bindings:

<form [formGroup]="form" class="tw-space-y-4">
  <mat-form-field class="tw-w-full" subscriptSizing="fixed">
    <mat-label>Field Name</​mat-label>
    <input matInput formControlName="fieldName" required />
    @if (form.controls.fieldName.hasError("required")) {
    <mat-error>Field is required</​mat-error>
    }
  </​mat-form-field>
</​form>

---

Phase 5: UX Enhancements

Confirmation Modals

• ALWAYS add confirmation modals for destructive actions
• ALWAYS use MatDialog to open modals
• ALWAYS subscribe to afterClosed() and only proceed if confirmed

EXAMPLE:

deleteItem(): void {
  this.#dialog
    .open(ConfirmDeleteModalComponent, {
      data: { itemName: this.data$.value?.name },
    })
    .afterClosed()
    .subscribe((confirmed) => {
      if (confirmed) {
        this.#componentStore.deleteItem();
      }
    });
}

User Feedback

• ALWAYS use successMessage in ApiAction definitions (not manual toasts in stores)
• ALWAYS use CoSnackService only for local operations (cancel, info messages)
• NEVER show success before API call completes

EXAMPLE - Success Messages:

// ❌ WRONG - shows before API completes
readonly saveChanges = this.effect<void>(
  pipe(
    tap(() => {
      this.#store.dispatch(updateAction.start(this.form.getRawValue()));
      this.#snacks.success('Saved!'); // ← BAD
    })
  )
);

// ✅ CORRECT - shows only on actual success
export const updateAction = new ApiAction<State, Input, Output>(
  'Entity',
  'Update',
  'Feature',
  {
    showErrors: true,
    successMessage: 'Saved!', // ← GOOD
  }
);

Copy to Clipboard

• PREFER adding copy-to-clipboard buttons for IDs

EXAMPLE:

<button
  matSuffix
  mat-icon-button
  matTooltip="Copy to clipboard"
  [cdkCopyToClipboard]="form.controls.id.value"
  (cdkCopyToClipboardCopied)="onIdCopied($event)"
>
  <fa-icon [icon]="copyIcon" />
</​button>

---

Phase 6: Verification

• ALWAYS run lint: corepack yarn nx lint <library-name>
• ALWAYS check for:
  • No manual subscriptions in components
  • All effects use pipe() directly
  • Forms have proper type annotations
  • No any types
  • Proper change detection strategy
• ALWAYS test:
  • Form initialization
  • Save/​cancel flows
  • Conditional field logic
  • Error handling
  • User feedback

---

Common Patterns

Conditional Field Disabling

• ALWAYS create a private method for conditional logic
• ALWAYS use { emitEvent: false } when programmatically enabling/​disabling controls
• ALWAYS call after form reset and in an effect watching the parent field

EXAMPLE:

#applyConditionalDisabling(form: FormGroup<FormControls>): void {
  const parentValue = form.controls.parentField.value;

  if (!parentValue) {
    form.controls.childField.disable({ emitEvent: false });
  } else {
    form.controls.childField.enable({ emitEvent: false });
  }
}

// Call after form reset and in an effect watching the parent field
readonly applyConditionalDisabling = this.effect<void>(
  pipe(
    switchMap(() => this.form.controls.parentField.valueChanges),
    tap(() => {
      this.#applyConditionalDisabling(this.form);
    })
  )
);

Form Controls with nonNullable

• ALWAYS add nonNullable: true to form controls to ensure type safety
• NOTE: This prevents the form control value from being null after reset

EXAMPLE:

readonly form = new FormGroup<ComponentNameFormControls>({
  field1: new FormControl<string>('', {
    validators: [Validators.required],
    nonNullable: true // ← ALWAYS include this
  }),
  field2: new FormControl<boolean>(false, { nonNullable: true }),
});

---

Critical Rules

Forms

• NEVER store forms in ComponentStore state
  • ALWAYS define forms as class properties in the store
• ALWAYS add nonNullable: true to form controls
• ALWAYS use typed FormGroup and FormControl (not FormNode)
• ALWAYS define form controls interface

Effects

• ALWAYS use pipe() directly: this.effect<Type>(pipe(...))
• NEVER use arrow functions: this.effect<Type>((param$) => param$.pipe(...))
• ALWAYS use proper type narrowing with filter

Subscriptions

• NEVER use manual subscriptions in components
  • NOTE: ComponentStore handles cleanup automatically
• NEVER use DestroyRef and takeUntilDestroyed for ComponentStore subscriptions
• ALWAYS wire observables directly to updaters/​effects

User Feedback

• NEVER show success toasts before API calls complete
• ALWAYS use successMessage in ApiAction definitions
• ALWAYS use CoSnackService only for local operations

TypeScript

• NEVER use any types
  • ALWAYS use unknown when type is uncertain
• ALWAYS use ECMAScript #privateField syntax for encapsulation
• NEVER use the public or private keywords in TypeScript class members

State Management

• NEVER use ComponentStore.get()
  • ALWAYS read state via selectors
• NEVER keep empty effects

---

Migration Checklist

• Phase 1: Read all component files and identify patterns
• Phase 2: Create ComponentStore
  • Defined state interface with readonly properties
  • Defined form controls interface
  • Created form as class property (not in state)
  • All selectors use $ suffix
  • All effects use pipe() directly
  • Proper type narrowing in effects
• Phase 3: Refactor component
  • Component uses OnPush change detection
  • Component is standalone: true
  • ComponentStore in providers array
  • Removed base class extensions
  • Removed @Select decorators
  • Removed manual subscriptions
  • All inject() calls first in class
  • Using #privateField syntax
• Phase 4: Update template
  • Updated template to use native control flow
  • Added animations for conditional UI
  • Proper form bindings
• Phase 5: UX enhancements
  • Added confirmation dialogs for destructive actions
  • Success messages in ApiAction (not manual toasts)
  • Copy-to-clipboard for IDs (if applicable)
• Phase 6: Verification
  • Lint passes
  • No manual subscriptions in components
  • Forms have proper type annotations
  • No any types
  • Tested all workflows

---

Additional Best Practices from AGENTS.md

• ALWAYS check AGENTS.md for the latest definite best practices

Angular Components

• ALWAYS set changeDetection: ChangeDetectionStrategy.OnPush in @Component decorator for new components
• ALWAYS use separate HTML files (do NOT use inline templates)
• ALWAYS place all inject() calls first in the class as readonly fields
• ALWAYS place @Input and @Output properties second in the class
• ALWAYS use class bindings instead of ngClass
• ALWAYS use style bindings instead of ngStyle
• ALWAYS use pipes for data transformation in templates, not methods in the component class

UI and Styling

• PREFER Angular Material/​CDK for complex, interactive UI
• NEVER override internal APIs in Angular Material components
• ALWAYS use Tailwind for layout, spacing, and simple styling
• ALWAYS use tw- prefix (enforced in libs/​co/​ui-tailwind-preset/​tailwind.config.js)
• ALWAYS define repeated patterns in CSS layer using @apply directive

FontAwesome Icons

• ALWAYS use FontAwesome icons via the @fortawesome/​angular-fontawesome package
• ALWAYS use <fa-icon> component, not <i> tags with CSS classes
• ALWAYS import from @fortawesome/​pro-*-svg-icons (not free packages)
• ALWAYS store icons as readonly component properties; prefer regular style by default

---

Before Submitting Code Review

• ALWAYS ensure all affected tests pass locally
• ALWAYS run formatting: yarn run format (from Connect/​ng-app-monolith)
• ALWAYS run linting: yarn exec nx affected --targets=lint,test --skip-nx-cache
• ALWAYS verify no linting errors are present
• ALWAYS ensure code follows established patterns as outlined in AGENTS.md

---

Reference Files

ALWAYS refer to these files for complete examples:

• libs/​connect/​cms/​qa/​feature/​src/​lib/​edit-topic/​cms-qa-edit-topic.store.ts
• libs/​connect/​cms/​qa/​feature/​src/​lib/​settings-page/​cms-qa-settings-page.store.ts
• libs/​connect/​cms/​qa/​feature/​src/​lib/​topics-page/​cms-qa-topics-page.store.ts
• AGENTS.md - Angular Development Patterns section

Examples

See the Instructions section.