@tacdaed/fragments 1.0.0-beta.0 → 1.0.0-beta.2

package/src/lib/components/stepper/stepper.component.ts

@@ -0,0 +1,482 @@
+import { NgTemplateOutlet } from '@angular/common';
+import {
+  Component,
+  ContentChild,
+  ElementRef,
+  EventEmitter,
+  Input,
+  OnChanges,
+  Output,
+  QueryList,
+  SimpleChanges,
+  TemplateRef,
+  ViewChildren
+} from '@angular/core';
+import { AbstractControl } from '@angular/forms';
+import {
+  StepChangeEvent,
+  StepItem,
+  StepItemContext,
+  StepValidationEvent,
+  TStepNavigationSource,
+  TStepperMotion,
+  TStepperOrientation
+} from './stepper.type';
+
+interface StepViewItem<T = unknown> extends StepItem<T> {
+  id: string;
+  active?: boolean;
+}
+
+interface StepValidationState {
+  checked: boolean;
+  valid: boolean;
+}
+
+@Component({
+  selector: 'frg-stepper',
+  standalone: true,
+  imports: [NgTemplateOutlet],
+  templateUrl: './stepper.component.html',
+  styleUrl: './stepper.component.scss'
+})
+export class StepperComponent implements OnChanges {
+  @Input() steps: StepItem[] = [];
+  @Input() activeId: string | null = null;
+  @Input() linear: boolean = true;
+  @Input() animated: boolean = true;
+  @Input() orientation: TStepperOrientation = 'horizontal';
+  @Input() focusPanelOnChange: boolean = true;
+  @Input() validateOnChange: boolean = true;
+  @Input() allowStepClick: boolean = true;
+  @Input() formGroup?: AbstractControl | null;
+
+  @Output() activeIdChange = new EventEmitter<string | null>();
+  @Output() changed = new EventEmitter<StepChangeEvent>();
+  @Output() validationChange = new EventEmitter<StepValidationEvent>();
+
+  @ContentChild('frgStepLabel', { read: TemplateRef }) labelTemplate?: TemplateRef<StepItemContext>;
+  @ContentChild('frgStepContent', { read: TemplateRef }) contentTemplate?: TemplateRef<StepItemContext>;
+  @ContentChild('frgStepIndicator', { read: TemplateRef }) indicatorTemplate?: TemplateRef<StepItemContext>;
+
+  @ViewChildren('stepBtn') stepButtons!: QueryList<ElementRef<HTMLButtonElement>>;
+  @ViewChildren('panelBody') panelBodies!: QueryList<ElementRef<HTMLElement>>;
+
+  viewSteps: StepViewItem[] = [];
+  motion: TStepperMotion = 'none';
+
+  private uidCounter = 0;
+  private readonly validationState = new Map<string, StepValidationState>();
+
+  ngOnChanges(changes: SimpleChanges): void {
+    if (changes['steps']) {
+      this.validationState.clear();
+      this.viewSteps = this.normalizeSteps(this.steps);
+      const initialActive = this.resolveActiveId(this.activeId);
+      this.setActiveId(initialActive, false, 'none');
+    }
+
+    if (changes['activeId'] && !changes['activeId'].firstChange) {
+      this.setActiveId(this.activeId, false, 'none');
+    }
+  }
+
+  get activeIndex(): number {
+    return this.viewSteps.findIndex(step => step.id === this.activeId);
+  }
+
+  isActive(id?: string | null): boolean {
+    return !!id && this.activeId === id;
+  }
+
+  stepId(id: string): string {
+    return `${id}-step`;
+  }
+
+  panelId(id: string): string {
+    return `${id}-panel`;
+  }
+
+  onStepClick(index: number, event: Event): void {
+    event.preventDefault();
+    if (!this.allowStepClick) {
+      return;
+    }
+    void this.requestStepChange(index, 'click');
+  }
+
+  onStepKeydown(event: KeyboardEvent, index: number): void {
+    const key = event.key;
+    const steps = this.stepButtons?.toArray() || [];
+    if (!steps.length) {
+      return;
+    }
+
+    if (key === 'Enter' || key === ' ') {
+      event.preventDefault();
+      void this.requestStepChange(index, 'click');
+      return;
+    }
+
+    const isHorizontal = this.orientation === 'horizontal';
+    const nextKey = isHorizontal ? 'ArrowRight' : 'ArrowDown';
+    const prevKey = isHorizontal ? 'ArrowLeft' : 'ArrowUp';
+
+    if (key === nextKey) {
+      event.preventDefault();
+      this.focusStep(this.findNextEnabledIndex(index, 1));
+    } else if (key === prevKey) {
+      event.preventDefault();
+      this.focusStep(this.findNextEnabledIndex(index, -1));
+    } else if (key === 'Home') {
+      event.preventDefault();
+      this.focusStep(this.findNextEnabledIndex(-1, 1));
+    } else if (key === 'End') {
+      event.preventDefault();
+      this.focusStep(this.findNextEnabledIndex(this.viewSteps.length, -1));
+    }
+  }
+
+  next(): void {
+    const currentIndex = this.getResolvedActiveIndex();
+    const target = currentIndex + 1;
+    if (target < this.viewSteps.length) {
+      void this.requestStepChange(target, 'next');
+    }
+  }
+
+  previous(): void {
+    const currentIndex = this.getResolvedActiveIndex();
+    const target = currentIndex - 1;
+    if (target >= 0) {
+      void this.requestStepChange(target, 'previous');
+    }
+  }
+
+  buildContext<T = unknown>(step: StepItem<T>, index: number): StepItemContext<T> {
+    return {
+      $implicit: step,
+      item: step,
+      index,
+      active: this.isActive(step.id),
+      completed: this.isStepComplete<T>(step),
+      error: this.isStepError<T>(step),
+      select: () => void this.requestStepChange(index, 'click'),
+      next: () => this.next(),
+      previous: () => this.previous()
+    };
+  }
+
+  stepStatus(step: StepItem, index: number): 'completed' | 'active' | 'error' | 'default' {
+    if (this.isStepError(step)) {
+      return 'error';
+    }
+    if (this.isActive(step.id)) {
+      return 'active';
+    }
+    if (this.isStepComplete(step)) {
+      return 'completed';
+    }
+    if (index === 0 && this.activeId === null) {
+      return 'active';
+    }
+    return 'default';
+  }
+
+  indicatorText(step: StepItem, index: number): string {
+    const status = this.stepStatus(step, index);
+    if (status === 'completed') {
+      return 'OK';
+    }
+    if (status === 'error') {
+      return '!';
+    }
+    if (step.icon) {
+      return step.icon;
+    }
+    return `${index + 1}`;
+  }
+
+  indicatorLabel(step: StepItem, index: number): string {
+    const status = this.stepStatus(step, index);
+    if (status === 'completed') {
+      return `${step.label} completed`;
+    }
+    if (status === 'error') {
+      return `${step.label} has errors`;
+    }
+    if (status === 'active') {
+      return `${step.label} active`;
+    }
+    return `Step ${index + 1}: ${step.label}`;
+  }
+
+  isStepDisabled(step: StepItem, index: number): boolean {
+    return !!step.disabled || this.isStepBlocked(index);
+  }
+
+  tabIndexFor(index: number): number {
+    if (this.isActive(this.viewSteps[index]?.id)) {
+      return 0;
+    }
+    const firstEnabled = this.findNextEnabledIndex(-1, 1);
+    if (this.activeId === null && index === firstEnabled) {
+      return 0;
+    }
+    return -1;
+  }
+
+  private async requestStepChange(index: number, source: TStepNavigationSource): Promise<void> {
+    const currentIndex = this.getResolvedActiveIndex();
+    const target = this.viewSteps[index];
+    if (!target || index === currentIndex) {
+      return;
+    }
+
+    if (target.disabled) {
+      return;
+    }
+
+    const forward = currentIndex >= 0 ? index > currentIndex : true;
+    if (forward && this.validateOnChange) {
+      const valid = await this.validateStep(currentIndex, source);
+      if (!valid && this.linear) {
+        return;
+      }
+    }
+
+    if (this.linear && this.isStepBlocked(index)) {
+      return;
+    }
+
+    const direction: TStepperMotion = forward ? 'next' : 'previous';
+    this.setActiveId(target.id, true, direction, target, index);
+  }
+
+  private normalizeSteps(steps: StepItem[]): StepViewItem[] {
+    return (steps || []).map((step, index) => ({
+      ...step,
+      id: step.id ?? this.generateId(index)
+    }));
+  }
+
+  private generateId(index: number): string {
+    this.uidCounter += 1;
+    return `frg-step-${index}-${this.uidCounter}`;
+  }
+
+  private resolveActiveId(candidate: string | null): string | null {
+    const available = (this.viewSteps || []).filter(step => !step.disabled);
+    if (!available.length) {
+      return null;
+    }
+    if (candidate && available.some(step => step.id === candidate)) {
+      return candidate;
+    }
+    const preselected = available.find(step => step.active && step.id);
+    if (preselected?.id) {
+      return preselected.id;
+    }
+    return available[0].id ?? null;
+  }
+
+  private setActiveId(
+    nextId: string | null,
+    emit: boolean,
+    direction: TStepperMotion,
+    item?: StepItem,
+    _index?: number
+  ): void {
+    const resolved = this.resolveActiveId(nextId);
+    const resolvedIndex = resolved ? this.viewSteps.findIndex(step => step.id === resolved) : -1;
+    const currentIndex = this.activeIndex;
+
+    this.activeId = resolved;
+    this.viewSteps = this.viewSteps.map(viewStep => ({
+      ...viewStep,
+      active: resolved ? viewStep.id === resolved : false
+    }));
+    this.motion = direction === 'none' ? this.getDirection(currentIndex, resolvedIndex) : direction;
+
+    if (emit) {
+      this.activeIdChange.emit(this.activeId);
+      this.changed.emit({
+        id: this.activeId,
+        index: resolvedIndex,
+        direction: this.motion,
+        item
+      });
+    }
+
+    if (this.focusPanelOnChange && resolvedIndex >= 0) {
+      setTimeout(() => this.focusPanel(resolvedIndex), 0);
+    }
+  }
+
+  private getDirection(fromIndex: number, toIndex: number): TStepperMotion {
+    if (fromIndex === -1 || toIndex === -1 || fromIndex === toIndex) {
+      return 'none';
+    }
+    return toIndex > fromIndex ? 'next' : 'previous';
+  }
+
+  isStepComplete<T>(step: StepItem<T>): boolean {
+    if (step.completed) {
+      return true;
+    }
+    const validation = this.getValidationResult<T>(step);
+    return validation === true;
+  }
+
+  isStepError<T>(step: StepItem<T>): boolean {
+    if (step.error) {
+      return true;
+    }
+    const control = step.control;
+    if (control) {
+      if (control.invalid && (control.touched || control.dirty)) {
+        return true;
+      }
+      const validation = this.validationState.get(step.id ?? '');
+      return validation ? !validation.valid : false;
+    }
+    const validation = this.validationState.get(step.id ?? '');
+    return validation ? !validation.valid : false;
+  }
+
+  private getValidationResult<T>(step: StepItem<T>): boolean | null {
+    if (step.control) {
+      if (step.control.pending) {
+        return null;
+      }
+      return step.control.valid;
+    }
+    const validation = this.validationState.get(step.id ?? '');
+    if (validation) {
+      return validation.valid;
+    }
+    return null;
+  }
+
+  private isStepBlocked(index: number): boolean {
+    if (!this.linear) {
+      return false;
+    }
+    const currentIndex = this.getResolvedActiveIndex();
+    if (currentIndex === -1) {
+      return index !== this.findNextEnabledIndex(-1, 1);
+    }
+    if (index <= currentIndex) {
+      return false;
+    }
+    for (let i = 0; i < index; i += 1) {
+      const step = this.viewSteps[i];
+      if (!step) {
+        continue;
+      }
+      if (step.optional) {
+        continue;
+      }
+      if (!this.isStepComplete(step)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  private async validateStep(index: number, source: TStepNavigationSource): Promise<boolean> {
+    if (index < 0 || index >= this.viewSteps.length) {
+      return true;
+    }
+    const step = this.viewSteps[index];
+    if (!step) {
+      return true;
+    }
+
+    const hasControl = !!step.control;
+    const hasValidator = !!step.validator;
+    if (!hasControl && !hasValidator) {
+      return true;
+    }
+
+    let valid = true;
+    if (hasControl && step.control) {
+      step.control.markAllAsTouched();
+      step.control.updateValueAndValidity({ onlySelf: false, emitEvent: false });
+      if (step.control.invalid) {
+        valid = false;
+      }
+    }
+
+    if (hasValidator && step.validator) {
+      const context = {
+        step,
+        index,
+        formGroup: this.formGroup ?? null,
+        source
+      };
+      const result = await Promise.resolve(step.validator(context));
+      if (!result) {
+        valid = false;
+      }
+    }
+
+    this.validationState.set(step.id, { checked: true, valid });
+    this.viewSteps = this.viewSteps.map(item =>
+      item.id === step.id
+        ? {
+          ...item,
+          completed: valid ? true : item.completed,
+          error: valid ? false : true
+        }
+        : item
+    );
+
+    this.validationChange.emit({
+      id: step.id,
+      index,
+      valid,
+      source,
+      item: step
+    });
+
+    return valid;
+  }
+
+  private focusStep(index: number): void {
+    const step = this.stepButtons?.get(index);
+    if (step?.nativeElement) {
+      step.nativeElement.focus();
+    }
+  }
+
+  private focusPanel(index: number): void {
+    const panel = this.panelBodies?.get(index);
+    if (panel?.nativeElement) {
+      panel.nativeElement.focus();
+    }
+  }
+
+  private getResolvedActiveIndex(): number {
+    const index = this.viewSteps.findIndex(step => step.id === this.activeId);
+    if (index >= 0) {
+      return index;
+    }
+    return this.viewSteps.findIndex(step => !step.disabled);
+  }
+
+  private findNextEnabledIndex(startIndex: number, delta: number): number {
+    if (!this.viewSteps.length) {
+      return -1;
+    }
+    let index = startIndex + delta;
+    while (index >= 0 && index < this.viewSteps.length) {
+      const step = this.viewSteps[index];
+      if (step && !this.isStepDisabled(step, index)) {
+        return index;
+      }
+      index += delta;
+    }
+    return startIndex;
+  }
+}

package/src/lib/components/stepper/stepper.type.ts

@@ -0,0 +1,60 @@
+import { TemplateRef } from '@angular/core';
+import { AbstractControl } from '@angular/forms';
+
+export type TStepperOrientation = 'horizontal' | 'vertical';
+export type TStepperMotion = 'next' | 'previous' | 'none';
+export type TStepNavigationSource = 'click' | 'next' | 'previous' | 'programmatic';
+
+export interface StepItemContext<T = unknown> {
+  $implicit: StepItem<T>;
+  item: StepItem<T>;
+  index: number;
+  active: boolean;
+  completed: boolean;
+  error: boolean;
+  select: () => void;
+  next: () => void;
+  previous: () => void;
+}
+
+export interface StepValidationContext<T = unknown> {
+  step: StepItem<T>;
+  index: number;
+  formGroup?: AbstractControl | null;
+  source: TStepNavigationSource;
+}
+
+export type StepValidator<T = unknown> = (context: StepValidationContext<T>) => boolean | Promise<boolean>;
+
+export interface StepItem<T = unknown> {
+  id?: string;
+  label: string;
+  description?: string;
+  disabled?: boolean;
+  optional?: boolean;
+  completed?: boolean;
+  error?: boolean;
+  icon?: string;
+  data?: T;
+  content?: string;
+  control?: AbstractControl | null;
+  validator?: StepValidator<T>;
+  labelTemplate?: TemplateRef<StepItemContext<T>>;
+  contentTemplate?: TemplateRef<StepItemContext<T>>;
+  indicatorTemplate?: TemplateRef<StepItemContext<T>>;
+}
+
+export interface StepChangeEvent<T = unknown> {
+  id: string | null;
+  index: number;
+  direction: TStepperMotion;
+  item?: StepItem<T>;
+}
+
+export interface StepValidationEvent<T = unknown> {
+  id: string | null;
+  index: number;
+  valid: boolean;
+  source: TStepNavigationSource;
+  item?: StepItem<T>;
+}