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

package/projects/software-division-components/src/generic/button/button.component.ts

@@ -0,0 +1,350 @@
+import { Component, computed, effect, ElementRef, input, output, signal } from '@angular/core';
+import { Subject, Subscription, takeUntil } from 'rxjs';
+import { Size, SIZES, ThemeClass } from '../../shared/types';
+import { HlmButtonModule } from './ui/ui-button-helm/src';
+
+const BUTTON_VARIANTS = {
+  primary: 'primary',
+  'primary-light': 'primary-light',
+  secondary: 'secondary',
+  alternative: 'alternative',
+  'alternative-light': 'alternative-light',
+  warning: 'warning',
+  'warning-light': 'warning-light',
+  destructive: 'destructive',
+  'destructive-light': 'destructive-light',
+  success: 'success',
+  'success-muted': 'success-muted',
+  outline: 'outline',
+  'outline-white': 'outline-white',
+  'outline-alternative': 'outline-alternative',
+  link: 'link',
+} as const;
+
+type ButtonVariant = (typeof BUTTON_VARIANTS)[keyof typeof BUTTON_VARIANTS];
+
+type ButtonType = 'button' | 'submit' | 'reset';
+
+export type ButtonStyleClasses = ReturnType<(typeof ButtonComponent.prototype)['styleClass']>;
+
+/**
+ * A customizable button component built on Spartan UI Button.
+ *
+ * This component supports various configurations and exposes all Spartan UI button functionality.
+ * All HTML button attributes and events are automatically forwarded to the inner button element.
+ *
+ * @since 1.0.0-alpha.1
+ * @updated 1.0.0-alpha.3
+ */
+@Component({
+  selector: 'sdc-button',
+  styleUrls: ['./button.component.css'],
+  templateUrl: './button.component.html',
+  imports: [HlmButtonModule],
+})
+export class ButtonComponent {
+  private readonly allowedVariants = Object.values(BUTTON_VARIANTS).map(v => `variant-${v}` as const);
+  private readonly allowedSizes = Object.values(SIZES).map(v => `size-${v}` as const);
+  private readonly allowedCircleSizes = [
+    'size-circle-sm',
+    'size-circle-md',
+    'size-circle-lg',
+    'size-circle-xl',
+  ] as const;
+  private readonly allowedRadius = [
+    'radius-default',
+    'radius-sm',
+    'radius-md',
+    'radius-lg',
+    'radius-xl',
+    'radius-2xl',
+    'radius-full',
+  ] as const;
+  private readonly allowedBorder = ['border-0', 'border-default', 'border-2', 'border-4', 'border-8'] 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.allowedCircleSizes)[number]
+      | (typeof this.allowedRadius)[number]
+      | (typeof this.allowedBorder)[number]
+    )[]
+  >([]);
+
+  // Computed signal that validates and filters the styleClass input
+  private readonly _validatedStyleClass = computed(() => {
+    const value = this.styleClass();
+
+    if (!Array.isArray(value)) {
+      console.warn('ButtonComponent: styleClass must be an array, defaulting to empty array');
+      return [];
+    }
+
+    const validValues = value.filter(
+      style =>
+        this.allowedVariants.includes(style as any) ||
+        this.allowedSizes.includes(style as any) ||
+        this.allowedCircleSizes.includes(style as any) ||
+        this.allowedRadius.includes(style as any) ||
+        this.allowedBorder.includes(style as any)
+    );
+
+    const invalidValues = value.filter(
+      style =>
+        !this.allowedVariants.includes(style as any) &&
+        !this.allowedSizes.includes(style as any) &&
+        !this.allowedCircleSizes.includes(style as any) &&
+        !this.allowedRadius.includes(style as any) &&
+        !this.allowedBorder.includes(style as any)
+    );
+
+    if (invalidValues.length > 0) {
+      throw new Error(
+        `ButtonComponent: Invalid styleClass values ignored: ${invalidValues.join(', ')}. Allowed values: ${[
+          ...this.allowedVariants,
+          ...this.allowedSizes,
+          ...this.allowedCircleSizes,
+          ...this.allowedRadius,
+          ...this.allowedBorder,
+        ].join(', ')}`
+      );
+    }
+
+    return validValues;
+  });
+
+  /**
+   * Additional classes
+   */
+  public readonly className = input<string>('');
+
+  /**
+   * Button component style variant
+   */
+  public readonly variant = input<ButtonVariant>('primary');
+
+  /**
+   * Button component size variant
+   */
+  public readonly size = input<Size>('md');
+
+  /**
+   * Native button type attribute
+   */
+  public readonly type = input<ButtonType>('button');
+
+  /**
+   * Whether the component is disabled.
+   */
+  public readonly disabled = input<boolean>(false);
+
+  /**
+   * Whether to enable the ripple effect on the component.
+   * Default value is false.
+   */
+  public readonly ripple = input<boolean>(false);
+
+  /**
+   * Event emitted when the component is clicked.
+   */
+  public readonly onClick = output<MouseEvent>();
+
+  /**
+   * Event emitted when the component receives focus.
+   */
+  public readonly onFocus = output<FocusEvent>();
+
+  /**
+   * Event emitted when the component loses focus.
+   */
+  public readonly onBlur = output<FocusEvent>();
+
+  protected readonly _sizeClass = computed(() => {
+    const size = SIZES[this.size()];
+
+    if (!size) {
+      throw new Error(`size must be one of these: ${Object.values(SIZES).join(', ')}}`);
+    }
+
+    return `size-${size}`;
+  });
+
+  protected readonly _variantClass = computed(() => {
+    const variant = BUTTON_VARIANTS[this.variant()];
+
+    if (!variant) {
+      throw new Error(`variant must be one of these: ${Object.values(BUTTON_VARIANTS).join(', ')}}`);
+    }
+
+    return `variant-${variant}`;
+  });
+
+  /**
+   * Computed class string that combines theme and user classes.
+   */
+  protected readonly computedClass = computed(() => {
+    const themeClass = this.theme();
+    const styleClass = this._validatedStyleClass();
+    const sizeClass = this._sizeClass();
+    const variantClass = this._variantClass();
+    const className = this.className();
+    return Array.from(new Set(['sdc-button', themeClass, sizeClass, variantClass, ...styleClass, className]))
+      .filter(Boolean)
+      .join(' ');
+  });
+
+  /**
+   * Debounce time in milliseconds. When null, no debounce is applied.
+   * Default value is null (no debounce).
+   */
+  public readonly debounce = input<number | null>(null);
+
+  /**
+   * 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 click events with debounce.
+   */
+  private readonly clickSubject = new Subject<MouseEvent>();
+
+  /**
+   * 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;
+
+  constructor(private elementRef: ElementRef) {
+    // Set up reactive debounce handling within injection context
+    effect(() => {
+      const debounceTime = this.debounce();
+      this.setupDebounce(debounceTime);
+    });
+  }
+
+  ngOnDestroy(): void {
+    this.destroy$.next();
+    this.destroy$.complete();
+    this.clickSubject.complete();
+    if (this.debounceSubscription) {
+      this.debounceSubscription.unsubscribe();
+    }
+    if (this.debounceTimeout) {
+      clearTimeout(this.debounceTimeout);
+    }
+  }
+
+  /**
+   * Sets up the debounce functionality for click events.
+   */
+  private setupDebounce(debounceTime: number | null): 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.clickSubject.pipe(takeUntil(this.destroy$)).subscribe((event: MouseEvent) => {
+      // Clear existing timeout
+      if (this.debounceTimeout) {
+        clearTimeout(this.debounceTimeout);
+      }
+
+      // Set new timeout
+      this.debounceTimeout = setTimeout(() => {
+        this.debounceState.set(false);
+        this.isDebounced.emit(false);
+        this.onClick.emit(event);
+        this.debounceTimeout = null;
+      }, debounceTime ?? 0);
+    });
+  }
+
+  /**
+   * Handles click events with debounce functionality.
+   */
+  protected handleClick(event: MouseEvent): void {
+    const debounceTime = this.debounce();
+
+    if (debounceTime !== null && debounceTime > 0) {
+      // Apply debounce
+      this.debounceState.set(true);
+      this.isDebounced.emit(true);
+      this.clickSubject.next(event);
+    } else {
+      // No debounce, emit immediately
+      this.onClick.emit(event);
+    }
+  }
+
+  /**
+   * Handles focus events and emits the onFocus output.
+   */
+  protected handleFocus(event: FocusEvent): void {
+    this.onFocus.emit(event);
+  }
+
+  /**
+   * Handles blur events and emits the onBlur output.
+   */
+  protected handleBlur(event: FocusEvent): void {
+    this.onBlur.emit(event);
+  }
+
+  /**
+   * Creates a ripple effect at the specified position.
+   */
+  protected createRipple(event: MouseEvent): void {
+    if (!this.ripple()) return;
+
+    const button = event.currentTarget as HTMLElement;
+    const rect = button.getBoundingClientRect();
+    const size = Math.max(rect.width, rect.height);
+    const x = event.clientX - rect.left - size / 2;
+    const y = event.clientY - rect.top - size / 2;
+
+    const ripple = document.createElement('span');
+    ripple.style.width = ripple.style.height = size + 'px';
+    ripple.style.left = x + 'px';
+    ripple.style.top = y + 'px';
+    ripple.classList.add('sdc-ripple');
+
+    button.appendChild(ripple);
+
+    setTimeout(() => {
+      ripple.remove();
+    }, 600);
+  }
+}

package/projects/software-division-components/src/generic/button/index.ts

@@ -0,0 +1 @@
+export * from './public-api';

package/projects/software-division-components/src/generic/button/package.json

@@ -0,0 +1,5 @@
+{
+  "ngPackage": {
+    "entryFile": "public_api.ts"
+  }
+}

package/projects/software-division-components/src/generic/button/public-api.ts

@@ -0,0 +1,5 @@
+/*
+ * Public API Surface of software-division-components
+ */
+
+export * from './button.component';