@3ddv/software-division-components 1.4.1 → 1.4.2

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

@@ -0,0 +1,252 @@
+import { Component, computed, input, OnDestroy, OnInit, signal } from '@angular/core';
+import { FormControl, FormSubmittedEvent, ReactiveFormsModule, ValidationErrors } from '@angular/forms';
+import { Subscription } from 'rxjs';
+import { ThemeClass } from '../../shared/types';
+
+export type CheckboxStyleClasses = ReturnType<(typeof CheckboxComponent.prototype)['styleClass']>;
+
+/**
+ * A customizable checkbox component.
+ *
+ * This component supports various configurations and exposes all Spartan UI checkbox functionality.
+ * All HTML checkbox attributes and events are automatically forwarded to the inner checkbox element.
+ *
+ * @since 1.0.0-alpha.1
+ */
+@Component({
+  standalone: true,
+  selector: 'sdc-checkbox',
+  styleUrls: ['./checkbox.component.css'],
+  templateUrl: './checkbox.component.html',
+  imports: [ReactiveFormsModule],
+})
+export class CheckboxComponent 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;
+
+  /**
+   * 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])[]>(
+    []
+  );
+
+  // Computed signal that validates and filters the styleClass checkbox
+  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)
+      );
+    });
+
+    const invalidValues = value.filter(style => {
+      return (
+        !(this.allowedVariants as readonly string[]).includes(style) &&
+        !(this.allowedSizes as readonly string[]).includes(style)
+      );
+    });
+
+    if (invalidValues.length > 0) {
+      throw new Error(
+        `CheckboxComponent: Invalid styleClass values ignored: ${invalidValues.join(', ')}. Allowed values: ${[
+          ...this.allowedVariants,
+          ...this.allowedSizes,
+        ].join(', ')}`
+      );
+    }
+
+    return validValues;
+  });
+
+  /**
+   * Additional CSS classes to apply to the component.
+   */
+  public readonly className = input<string>('');
+
+  /**
+   * Whether the component is disabled.
+   */
+  public readonly disabled = input<boolean>(false);
+
+  /**
+   * The label text to display above or to the left of the checkbox.
+   * Only visible when a value is provided.
+   */
+  public readonly label = input.required<string>();
+
+  /**
+   * The position of the label relative to the checkbox.
+   */
+  public readonly labelPosition = input<'left' | 'right'>('left');
+
+  /**
+   * The name of the form control.
+   */
+  public readonly name = input.required<string>();
+
+  /**
+   * The FormControl instance to bind to this checkbox.
+   * This allows the component to access form state without circular dependencies.
+   */
+  public readonly control = input.required<FormControl>();
+
+  /**
+   * The value of the checkbox.
+   */
+  public readonly value = input.required<string>();
+
+  /**
+   * Whether the checkbox is checked.
+   */
+  public readonly isChecked = signal<boolean>(false);
+
+  /**
+   * 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 labelClass = this.labelPosition() === 'left' ? 'sdc-checkbox-label-left' : 'sdc-checkbox-label-right';
+    const checkedClass = this.isChecked() ? 'sdc-checkbox-checked' : '';
+    return ['sdc-checkbox', themeClass, ...styleClass, className, labelClass, checkedClass].filter(Boolean).join(' ');
+  });
+
+  /**
+   * 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 state of the form control.
+   */
+  public readonly controlState = signal<{
+    invalid: boolean;
+    errors: ValidationErrors | null;
+    isFormSubmitted: boolean;
+  }>({ errors: null, invalid: false, isFormSubmitted: false });
+
+  /**
+   * 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];
+      return this.getValidatorErrorMessage(firstErrorKey);
+    }
+
+    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 true;
+      } else if (errorMode === 'after-submit') {
+        // Show errors when form is submitted, regardless of touch/focus state
+        return this.controlState()?.isFormSubmitted;
+      }
+    }
+
+    return false;
+  });
+
+  /**
+   * Subscriptions to the control's value changes.
+   */
+  private readonly subscriptions: (Subscription | undefined)[] = [];
+
+  ngOnInit(): void {
+    this.isChecked.set(this.control()?.value === this.value());
+
+    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,
+          errors: this.control()?.errors || null,
+        });
+
+        // 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 });
+        }
+      }
+    });
+
+    // Listen to changes on this specific checkbox's control
+    const valueChangesSubscription = this.control()?.valueChanges.subscribe(value => {
+      this.isChecked.set(value === this.value());
+    });
+
+    const statusChangesSubscription = this.control()?.statusChanges.subscribe(status => {
+      if (status === 'INVALID') {
+        this.controlState.set({ ...this.controlState(), invalid: true });
+      }
+
+      this.controlState.set({ ...this.controlState(), errors: this.control()?.errors || null });
+    });
+
+    this.subscriptions.push(formEventsSubscription, valueChangesSubscription, statusChangesSubscription);
+  }
+
+  ngOnDestroy(): void {
+    this.subscriptions.forEach(subscription => subscription?.unsubscribe());
+  }
+
+  /**
+   * Gets the error message for a specific validator error.
+   */
+  private getValidatorErrorMessage(errorKey: string): string {
+    switch (errorKey) {
+      case 'required':
+        return 'This field is required.';
+      default:
+        return 'This field is required.';
+    }
+  }
+}

package/projects/software-division-components/src/backoffice/checkbox/index.ts

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

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

@@ -0,0 +1 @@
+export * from './checkbox.component';

package/projects/software-division-components/src/backoffice/checkbox/story/checkbox.stories.ts

@@ -0,0 +1,304 @@
+import { FormControl } from '@angular/forms';
+import type { Meta, StoryObj } from '@storybook/angular';
+import { CheckboxComponent } from '../checkbox.component';
+
+const meta: Meta<CheckboxComponent> = {
+  title: 'Backoffice/Checkbox',
+  component: CheckboxComponent,
+  parameters: {
+    layout: 'centered',
+  },
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<CheckboxComponent>;
+
+// Basic checkbox with default settings
+export const Default: Story = {
+  render: () => ({
+    props: {
+      formControl: new FormControl(false),
+    },
+    template: `
+      <sdc-checkbox
+        label="Accept terms and conditions"
+        name="terms"
+        value="accepted"
+        [control]="formControl"
+      />
+    `,
+  }),
+};
+
+// Checkbox group with multiple options
+export const CheckboxGroup: Story = {
+  render: () => ({
+    props: {
+      formControl: new FormControl(['option1']),
+    },
+    template: `
+      <div style="display: flex; flex-direction: column; gap: 1rem;">
+        <sdc-checkbox
+          label="Option 1"
+          name="group1"
+          value="option1"
+          [control]="formControl"
+        />
+        <sdc-checkbox
+          label="Option 2"
+          name="group1"
+          value="option2"
+          [control]="formControl"
+        />
+        <sdc-checkbox
+          label="Option 3"
+          name="group1"
+          value="option3"
+          [control]="formControl"
+        />
+      </div>
+    `,
+  }),
+};
+
+// Checkbox with label on the right
+export const LabelRight: Story = {
+  render: () => ({
+    props: {
+      formControl: new FormControl(false),
+    },
+    template: `
+      <sdc-checkbox
+        label="Checkbox with right label"
+        labelPosition="right"
+        name="right-label"
+        value="option1"
+        [control]="formControl"
+      />
+    `,
+  }),
+};
+
+// Checkbox with different themes
+export const ThemeVariations: Story = {
+  render: () => ({
+    template: `
+      <div style="display: flex; flex-direction: column; gap: 1rem;">
+        <sdc-checkbox
+          label="SDC Theme"
+          theme="theme-sdc"
+          name="theme-sdc"
+          value="sdc"
+          [control]="sdcControl"
+        />
+        <sdc-checkbox
+          label="Backoffice Theme"
+          theme="theme-backoffice"
+          name="theme-backoffice"
+          value="backoffice"
+          [control]="backofficeControl"
+        />
+      </div>
+    `,
+    props: {
+      sdcControl: new FormControl(false),
+      backofficeControl: new FormControl(false),
+    },
+  }),
+};
+
+// Checkbox with different style classes (variants and sizes)
+export const StyleVariations: Story = {
+  render: () => ({
+    template: `
+      <div style="display: flex; flex-direction: column; gap: 1rem; width: 400px;">
+        <div style="display: flex; flex-direction: column; gap: 0.5rem;">
+          <h4 style="margin: 0; color: #666;">Primary Variant</h4>
+          <sdc-checkbox
+            label="Primary Option"
+            [styleClass]="['variant-primary', 'size-md']"
+            name="primary-group"
+            value="primary"
+            [control]="primaryControl"
+          />
+        </div>
+        
+        <div style="display: flex; flex-direction: column; gap: 0.5rem;">
+          <h4 style="margin: 0; color: #666;">Secondary Variant</h4>
+          <sdc-checkbox
+            label="Secondary Option"
+            [styleClass]="['variant-secondary', 'size-md']"
+            name="secondary-group"
+            value="secondary"
+            [control]="secondaryControl"
+          />
+        </div>
+        
+        <div style="display: flex; flex-direction: column; gap: 0.5rem;">
+          <h4 style="margin: 0; color: #666;">Alternative Variant</h4>
+          <sdc-checkbox
+            label="Alternative Option"
+            [styleClass]="['variant-alternative', 'size-md']"
+            name="alternative-group"
+            value="alternative"
+            [control]="alternativeControl"
+          />
+        </div>
+        
+        <div style="display: flex; flex-direction: column; gap: 0.5rem;">
+          <h4 style="margin: 0; color: #666;">Success Variant</h4>
+          <sdc-checkbox
+            label="Success Option"
+            [styleClass]="['variant-success', 'size-md']"
+            name="success-group"
+            value="success"
+            [control]="successControl"
+          />
+        </div>
+        
+        <div style="display: flex; flex-direction: column; gap: 0.5rem;">
+          <h4 style="margin: 0; color: #666;">Warning Variant</h4>
+          <sdc-checkbox
+            label="Warning Option"
+            [styleClass]="['variant-warning', 'size-md']"
+            name="warning-group"
+            value="warning"
+            [control]="warningControl"
+          />
+        </div>
+        
+        <div style="display: flex; flex-direction: column; gap: 0.5rem;">
+          <h4 style="margin: 0; color: #666;">Danger Variant</h4>
+          <sdc-checkbox
+            label="Danger Option"
+            [styleClass]="['variant-danger', 'size-md']"
+            name="danger-group"
+            value="danger"
+            [control]="dangerControl"
+          />
+        </div>
+      </div>
+    `,
+    props: {
+      primaryControl: new FormControl(false),
+      secondaryControl: new FormControl(false),
+      alternativeControl: new FormControl(false),
+      successControl: new FormControl(false),
+      warningControl: new FormControl(false),
+      dangerControl: new FormControl(false),
+    },
+  }),
+};
+
+// Checkbox with different sizes
+export const SizeVariations: Story = {
+  render: () => ({
+    template: `
+      <div style="display: flex; flex-direction: column; gap: 1rem; width: 400px;">
+        <div style="display: flex; flex-direction: column; gap: 0.5rem;">
+          <h4 style="margin: 0; color: #666;">Small Size</h4>
+          <sdc-checkbox
+            label="Small Checkbox"
+            [styleClass]="['size-sm']"
+            name="size-sm"
+            value="small"
+            [control]="smallControl"
+          />
+        </div>
+        
+        <div style="display: flex; flex-direction: column; gap: 0.5rem;">
+          <h4 style="margin: 0; color: #666;">Medium Size</h4>
+          <sdc-checkbox
+            label="Medium Checkbox"
+            [styleClass]="['size-md']"
+            name="size-md"
+            value="medium"
+            [control]="mediumControl"
+          />
+        </div>
+        
+        <div style="display: flex; flex-direction: column; gap: 0.5rem;">
+          <h4 style="margin: 0; color: #666;">Large Size</h4>
+          <sdc-checkbox
+            label="Large Checkbox"
+            [styleClass]="['size-lg']"
+            name="size-lg"
+            value="large"
+            [control]="largeControl"
+          />
+        </div>
+        
+        <div style="display: flex; flex-direction: column; gap: 0.5rem;">
+          <h4 style="margin: 0; color: #666;">Extra Large Size</h4>
+          <sdc-checkbox
+            label="Extra Large Checkbox"
+            [styleClass]="['size-xl']"
+            name="size-xl"
+            value="xl"
+            [control]="xlControl"
+          />
+        </div>
+      </div>
+    `,
+    props: {
+      smallControl: new FormControl(false),
+      mediumControl: new FormControl(false),
+      largeControl: new FormControl(false),
+      xlControl: new FormControl(false),
+    },
+  }),
+};
+
+// Disabled checkbox
+export const Disabled: Story = {
+  render: () => ({
+    props: {
+      formControl: new FormControl({ value: false, disabled: true }),
+    },
+    template: `
+      <sdc-checkbox
+        label="Disabled Checkbox"
+        name="disabled-group"
+        value="disabled"
+        [disabled]="true"
+        [control]="formControl"
+      />
+    `,
+  }),
+};
+
+// Checked checkbox
+export const Checked: Story = {
+  render: () => ({
+    props: {
+      formControl: new FormControl(true),
+    },
+    template: `
+      <sdc-checkbox
+        label="Checked Checkbox"
+        name="checked-group"
+        value="checked"
+        [control]="formControl"
+      />
+    `,
+  }),
+};
+
+// Checkbox with custom className
+export const CustomClassName: Story = {
+  render: () => ({
+    props: {
+      formControl: new FormControl(false),
+    },
+    template: `
+      <sdc-checkbox
+        label="Custom Styled Checkbox"
+        name="custom-group"
+        value="custom"
+        className="border-2 border-blue-500 p-2 rounded"
+        [control]="formControl"
+      />
+    `,
+  }),
+};