@3ddv/software-division-components 1.1.0 → 1.4.0

package/projects/software-division-components/src/backoffice/input/input.component.ts

@@ -0,0 +1,497 @@
+import { Component, computed, effect, EffectRef, input, OnDestroy, OnInit, output, signal } from '@angular/core';
+import {
+  AbstractControl,
+  FormControl,
+  FormSubmittedEvent,
+  ReactiveFormsModule,
+  ValidationErrors,
+} from '@angular/forms';
+import { Subject, Subscription } from 'rxjs';
+import { takeUntil } from 'rxjs/operators';
+import { ThemeClass } from '../../shared/types';
+
+export type InputStyleClasses = ReturnType<(typeof InputComponent.prototype)['styleClass']>;
+
+/**
+ * A customizable input component built on the native input element.
+ *
+ * This component supports various configurations and exposes all native input functionality.
+ * All HTML input attributes and events are automatically forwarded to the inner input element.
+ *
+ * @since 1.0.0-alpha.1
+ */
+@Component({
+  standalone: true,
+  selector: 'sdc-input',
+  styleUrls: ['./input.component.css'],
+  templateUrl: './input.component.html',
+  imports: [ReactiveFormsModule],
+})
+export class InputComponent implements OnInit, OnDestroy {
+  private readonly allowedVariants = [
+    'variant-primary',
+    'variant-secondary',
+    'variant-alternative',
+    'variant-success',
+    'variant-warning',
+    'variant-danger',
+  ] as const;
+  private readonly allowedSizes = ['size-sm', 'size-md', 'size-lg', 'size-xl'] as const;
+  private readonly allowedRadius = [
+    'radius-default',
+    'radius-sm',
+    'radius-md',
+    'radius-lg',
+    'radius-xl',
+    'radius-2xl',
+    'radius-full',
+  ] as const;
+
+  /**
+   * The current theme applied to the component.
+   */
+  public readonly theme = input<ThemeClass>('theme-sdc');
+
+  /**
+   * Predefined styles to apply to the component.
+   * Can be a single class or multiple classes from different categories.
+   */
+  public readonly styleClass = input<
+    ((typeof this.allowedVariants)[number] | (typeof this.allowedSizes)[number] | (typeof this.allowedRadius)[number])[]
+  >([]);
+
+  // Computed signal that validates and filters the styleClass input
+  private readonly _validatedStyleClass = computed(() => {
+    const value = this.styleClass();
+
+    if (!Array.isArray(value)) {
+      return [];
+    }
+
+    const validValues = value.filter(style => {
+      return (
+        (this.allowedVariants as readonly string[]).includes(style) ||
+        (this.allowedSizes as readonly string[]).includes(style) ||
+        (this.allowedRadius as readonly string[]).includes(style)
+      );
+    });
+
+    const invalidValues = value.filter(style => {
+      return (
+        !(this.allowedVariants as readonly string[]).includes(style) &&
+        !(this.allowedSizes as readonly string[]).includes(style) &&
+        !(this.allowedRadius as readonly string[]).includes(style)
+      );
+    });
+
+    if (invalidValues.length > 0) {
+      throw new Error(
+        `InputComponent: Invalid styleClass values ignored: ${invalidValues.join(', ')}. Allowed values: ${[
+          ...this.allowedVariants,
+          ...this.allowedSizes,
+          ...this.allowedRadius,
+        ].join(', ')}`
+      );
+    }
+
+    return validValues;
+  });
+
+  /**
+   * Additional CSS classes to apply to the component.
+   */
+  public readonly className = input<string>('');
+
+  /**
+   * The label text to display above or to the left of the input.
+   * Only visible when a value is provided.
+   */
+  public readonly label = input<string>('');
+
+  /**
+   * The position of the label relative to the input.
+   * 'top' places the label above the input, 'left' places it to the left.
+   */
+  public readonly labelPosition = input<'top' | 'left'>('top');
+
+  /**
+   * Whether the component is disabled.
+   */
+  public readonly disabled = input<boolean>(false);
+
+  /**
+   * The type of the input element.
+   */
+  public readonly type = input<string>('text');
+
+  /**
+   * The placeholder text for the input.
+   */
+  public readonly placeholder = input<string>('');
+
+  /**
+   * The hint text for the input.
+   */
+  public readonly hint = input<string>('');
+
+  /**
+   * The name of the form control.
+   */
+  public readonly name = input<string>('');
+
+  /**
+   * Whether the input is a textarea.
+   */
+  public readonly isTextarea = input<boolean>(false);
+
+  /**
+   * The number of rows for the textarea.
+   */
+  public readonly textareaRows = input<number>(1);
+
+  /**
+   * The number of columns for the textarea.
+   */
+  public readonly textareaCols = input<number>(1);
+
+  /**
+   * Whether the textarea is resizable.
+   */
+  public readonly textareaResize = input<'none' | 'both' | 'horizontal' | 'vertical'>('vertical');
+
+  /**
+   * Custom error message to override the validator's error message.
+   */
+  public readonly errorMessage = input<string>('');
+
+  /**
+   * Controls when errors are displayed.
+   * - 'after-submit': Show errors only after form submission (default)
+   * - 'always': Show errors immediately when validation fails
+   */
+  public readonly errorDisplayMode = input<'always' | 'after-submit'>('after-submit');
+
+  /**
+   * The FormControl instance to bind to this input.
+   * This allows the component to access form state without circular dependencies.
+   */
+  public readonly control = input<AbstractControl<string | null> | FormControl | null>(null);
+
+  /**
+   * The state of the form control.
+   */
+  public readonly controlState = signal<{
+    invalid: boolean;
+    touched: boolean;
+    dirty: boolean;
+    errors: ValidationErrors | null;
+    value: string;
+    isFormSubmitted: boolean;
+  }>({ invalid: false, touched: false, dirty: false, errors: null, value: '', isFormSubmitted: false });
+
+  /**
+   * Event emitted when the component receives focus.
+   */
+  public readonly onFocus = output<FocusEvent>();
+
+  /**
+   * Event emitted when the component loses focus.
+   */
+  public readonly onBlur = output<FocusEvent>();
+
+  /**
+   * Event emitted when the input value changes.
+   */
+  public readonly onInput = output<InputEvent>();
+
+  /**
+   * Computed class string that combines theme and user classes.
+   */
+  protected readonly computedClass = computed(() => {
+    const themeClass = this.theme();
+    const styleClass = this._validatedStyleClass();
+    const className = this.className();
+    const errorClass = this.showError() ? 'has-error' : '';
+    const textareaResizeClass = this.isTextarea() ? `resize-${this.textareaResize()}` : '';
+    return ['sdc-input', themeClass, ...styleClass, className, errorClass, textareaResizeClass]
+      .filter(Boolean)
+      .join(' ');
+  });
+
+  /**
+   * Computed class string for the label positioning.
+   */
+  protected readonly labelClass = computed(() => {
+    const position = this.labelPosition();
+    return position === 'left' ? 'sdc-input-label left' : 'sdc-input-label top';
+  });
+
+  /**
+   * Debounce time in milliseconds. When 0, no debounce is applied.
+   * Default value is 0 (no debounce).
+   */
+  public readonly debounce = input<number>(0);
+
+  /**
+   * Event emitted to notify the debounce state.
+   * Returns true while the component is debounced, false when not.
+   */
+  public readonly isDebounced = output<boolean>();
+
+  /**
+   * Signal to track the current debounce state of the component.
+   */
+  protected readonly debounceState = signal<boolean>(false);
+
+  /**
+   * Subject for handling input events with debounce.
+   */
+  private readonly inputSubject = new Subject<Event>();
+
+  /**
+   * Subject for cleanup.
+   */
+  private readonly destroy$ = new Subject<void>();
+
+  /**
+   * Current subscription for debounce.
+   */
+  private debounceSubscription: Subscription | null = null;
+
+  /**
+   * Current debounce timeout.
+   */
+  private debounceTimeout: ReturnType<typeof setTimeout> | null = null;
+
+  /**
+   * Component subscriptions.
+   */
+  private subscriptions: (Subscription | undefined)[] = [];
+
+  /**
+   * Computed signal to determine if the label should be visible.
+   */
+  protected readonly showLabel = computed(() => {
+    return this.label() && this.label().trim().length > 0;
+  });
+
+  /**
+   * Computed signal to get the current error message.
+   */
+  protected readonly currentErrorMessage = computed(() => {
+    const customMessage = this.errorMessage();
+    const hasErrors = Object.keys(this.controlState()?.errors ?? {}).length > 0;
+
+    if (hasErrors && customMessage && customMessage.trim().length > 0) {
+      return customMessage;
+    }
+
+    // If no custom message, try to get validation error from the form control state
+    if (hasErrors) {
+      const firstErrorKey = Object.keys(this.controlState()?.errors ?? {})[0];
+      const firstErrorValue = this.controlState()?.errors?.[firstErrorKey];
+      return this.getValidatorErrorMessage(firstErrorKey, firstErrorValue);
+    }
+
+    return '';
+  });
+
+  /**
+   * Computed signal to determine if there's an error to display.
+   */
+  protected readonly showError = computed(() => {
+    const errorMode = this.errorDisplayMode();
+
+    // For validation errors, respect the error display mode
+    if (this.controlState()?.invalid) {
+      if (errorMode === 'always') {
+        // Show errors when component is touched and invalid
+        return this.controlState()?.touched || this.controlState()?.dirty || this.controlState()?.isFormSubmitted;
+      } else if (errorMode === 'after-submit') {
+        // Show errors when form is submitted, regardless of touch/focus state
+        return this.controlState()?.isFormSubmitted;
+      }
+    }
+
+    return false;
+  });
+
+  /**
+   * References to effects for proper cleanup
+   */
+  private readonly effects: EffectRef[] = [];
+
+  constructor() {
+    // Set up reactive debounce handling within injection context
+    const debounceEffect = effect(() => {
+      const debounceTime = this.debounce();
+      this.setupDebounce(debounceTime);
+    });
+    this.effects.push(debounceEffect);
+  }
+
+  ngOnInit(): void {
+    // Validate the name input
+    if ((this.control() || this.showLabel()) && !this.name()) {
+      throw new Error('InputComponent: name is required when control or label inputs are present');
+    }
+
+    const formEventsSubscription = this.control()?.parent?.events.subscribe(event => {
+      // We do not reset this signal because it is used to show the errors
+      // When a form is submitted at least once, we want to show the errors
+      if (event instanceof FormSubmittedEvent) {
+        this.controlState.set({ ...this.controlState(), isFormSubmitted: true });
+
+        // We add this because the statusChanges event is not triggered when the form is submitted
+        if (event.source.status === 'INVALID') {
+          this.controlState.set({ ...this.controlState(), invalid: true });
+        }
+      }
+
+      this.updateErrors();
+    });
+
+    const statusChangesSubscription = this.control()?.statusChanges.subscribe(status => {
+      if (status === 'INVALID') {
+        this.controlState.set({ ...this.controlState(), invalid: true });
+      }
+
+      this.updateErrors();
+    });
+
+    this.subscriptions.push(formEventsSubscription, statusChangesSubscription);
+  }
+
+  ngOnDestroy(): void {
+    this.destroy$.next();
+    this.destroy$.complete();
+    this.inputSubject.complete();
+    if (this.debounceSubscription) {
+      this.debounceSubscription.unsubscribe();
+    }
+    if (this.debounceTimeout) {
+      clearTimeout(this.debounceTimeout);
+    }
+    this.effects.forEach(effect => effect.destroy());
+    this.subscriptions.forEach(subscription => subscription?.unsubscribe());
+  }
+
+  private updateErrors() {
+    // We override the errors except the internal_* errors
+    const currentInternalErrors = Object.entries(this.controlState()?.errors || {})?.filter(([key]) =>
+      key.startsWith('internal_')
+    );
+    const controlStateHasInternalErrors = currentInternalErrors.length > 0;
+
+    const newErrors =
+      this.control()?.errors || controlStateHasInternalErrors
+        ? Object.assign(Object.fromEntries(currentInternalErrors), this.control()?.errors ?? {})
+        : null;
+
+    this.controlState.set({ ...this.controlState(), errors: newErrors });
+  }
+
+  /**
+   * Sets up the debounce functionality for input events.
+   */
+  private setupDebounce(debounceTime: number): void {
+    // Clear existing subscription
+    if (this.debounceSubscription) {
+      this.debounceSubscription.unsubscribe();
+    }
+
+    // Clear existing timeout
+    if (this.debounceTimeout) {
+      clearTimeout(this.debounceTimeout);
+      this.debounceTimeout = null;
+    }
+
+    // Set up new subscription
+    this.debounceSubscription = this.inputSubject.pipe(takeUntil(this.destroy$)).subscribe((event: Event) => {
+      // Clear existing timeout
+      if (this.debounceTimeout) {
+        clearTimeout(this.debounceTimeout);
+      }
+
+      // Set new timeout
+      this.debounceTimeout = setTimeout(() => {
+        this.debounceState.set(false);
+        this.isDebounced.emit(false);
+        this.onInput.emit(event as InputEvent);
+        this.debounceTimeout = null;
+      }, debounceTime);
+    });
+  }
+
+  /**
+   * Handles input events with debounce functionality.
+   */
+  protected handleInput(event: Event): void {
+    const target = event.target as HTMLInputElement;
+    const newValue = target.value;
+
+    // Only allow numbers for input with type number
+    if (this.type() === 'number') {
+      const isValidNumber = /^[0-9]+$/.test(newValue);
+      this.controlState.set({ ...this.controlState(), errors: isValidNumber ? null : { internal_number: true } });
+    }
+
+    // Update the form control value
+    this.controlState.set({ ...this.controlState(), value: newValue, dirty: true });
+    this.control()?.setValue(newValue);
+
+    const debounceTime = this.debounce();
+
+    if (debounceTime > 0) {
+      // Apply debounce
+      this.debounceState.set(true);
+      this.isDebounced.emit(true);
+      this.inputSubject.next({ ...event, target: { ...event.target, value: newValue } } as unknown as InputEvent);
+    } else {
+      // No debounce, emit immediately
+      this.onInput.emit({ ...event, target: { ...event.target, value: newValue } } as unknown as InputEvent);
+    }
+  }
+
+  /**
+   * Handles focus events and emits the onFocus output.
+   */
+  protected handleFocus(event: FocusEvent): void {
+    this.controlState.set({ ...this.controlState(), touched: true });
+    this.onFocus.emit(event);
+  }
+
+  /**
+   * Handles blur events and emits the onBlur output.
+   */
+  protected handleBlur(event: FocusEvent): void {
+    this.controlState.set({ ...this.controlState(), touched: true });
+    this.onBlur.emit(event);
+  }
+
+  /**
+   * Gets the error message for a specific validator error.
+   */
+  private getValidatorErrorMessage(errorKey: string, errorValue: any): string {
+    switch (errorKey) {
+      case 'required':
+        return 'This field is required.';
+      case 'internal_number':
+        return 'Please enter a valid number.';
+      case 'email':
+        return 'Please enter a valid email address.';
+      case 'minlength':
+        return `Minimum length is ${errorValue.requiredLength} characters.`;
+      case 'maxlength':
+        return `Maximum length is ${errorValue.requiredLength} characters.`;
+      case 'min':
+        return `Minimum value is ${errorValue.min}.`;
+      case 'max':
+        return `Maximum value is ${errorValue.max}.`;
+      case 'pattern':
+        return 'Please enter a valid value.';
+      default:
+        return 'Please enter a valid value.';
+    }
+  }
+}

package/projects/software-division-components/src/backoffice/input/public-api.ts

@@ -0,0 +1,2 @@
+// Export the main form component
+export * from './input.component';