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

package/src/lib/components/status/directives/badge/badge.directive.ts

@@ -0,0 +1,190 @@
+import {
+  Directive,
+  ElementRef,
+  inject,
+  Input,
+  OnChanges,
+  OnDestroy,
+  Renderer2,
+  SimpleChanges,
+} from '@angular/core';
+import { Badge } from './badge.interface';
+
+@Directive({
+  selector: '[frgBadge]',
+  standalone: true,
+  host: {
+    class: 'frg-has-badge',
+  },
+})
+export class FrgBadgeDirective implements OnChanges, OnDestroy {
+  private readonly host = inject(ElementRef<HTMLElement>);
+  private readonly renderer = inject(Renderer2);
+
+  /**
+   * Badge configuration object.
+   */
+  @Input() badge!: Badge;
+
+  /**
+   * Reference to the badge HTML element.
+   */
+  private badgeEl?: HTMLElement;
+
+  ngOnChanges(changes: SimpleChanges): void {
+    if (changes['badge']) {
+      this.updateBadge();
+    }
+  }
+
+  /**
+   * Cleans up the badge element when the directive is destroyed.
+   */
+  ngOnDestroy(): void {
+    this.removeBadge();
+  }
+
+  /**
+   * Updates the badge element based on the current badge configuration.
+   * Creates, updates, or removes the badge as necessary.
+   */
+  private updateBadge(): void {
+    if (this.shouldHide()) {
+      this.removeBadge();
+      return;
+    }
+
+    if (!this.badgeEl) {
+      this.createBadge();
+    }
+
+    this.updateBadgeContent();
+    this.updateBadgeClasses();
+  }
+
+  /**
+   * Creates the badge HTML element and appends it to the host element.
+   * Initializes the badge with the base class.
+   */
+  private createBadge(): void {
+    this.badgeEl = this.renderer.createElement('span');
+    this.renderer.addClass(this.badgeEl, 'frg-badge');
+
+    this.renderer.appendChild(this.host.nativeElement, this.badgeEl);
+  }
+
+  /**
+   * Updates the content of the badge element based on the badge configuration.
+   * Handles dot mode, icon placement, and value display.
+   */
+  private updateBadgeContent(): void {
+    if (!this.badgeEl || this.badge.dot) {
+      this.badgeEl!.innerHTML = '';
+      return;
+    }
+
+    this.badgeEl.innerHTML = '';
+
+    const hasIcon = !!this.badge.icon;
+    const hasValue = this.badge.value != null && this.badge.value !== '';
+
+    if (hasIcon) {
+      const iconEl = this.createIconElement(this.badge.icon || '');
+
+      if (this.badge.iconPosition === 'start') {
+        this.appendIconThenValue(iconEl, hasValue);
+      } else {
+        this.appendValueThenIcon(hasValue, iconEl);
+      }
+    } else if (hasValue) {
+      this.badgeEl.innerText = String(this.badge.value);
+    }
+  }
+
+  /**
+   * Creates the icon element with all classes
+   */
+  private createIconElement(iconClass: string): HTMLElement {
+    const iconEl = this.renderer.createElement('i');
+    for (const cls of iconClass.split(' ')) {
+      this.renderer.addClass(iconEl, cls);
+    }
+    this.renderer.addClass(iconEl, 'frg-badge__icon');
+    return iconEl;
+  }
+
+  /**
+   * Append value first, then icon
+   */
+  private appendValueThenIcon(hasValue: boolean, iconEl: HTMLElement): void {
+    if (hasValue) {
+      const textNode = this.renderer.createText(String(this.badge.value));
+      this.renderer.appendChild(this.badgeEl!, textNode);
+    }
+    this.renderer.appendChild(this.badgeEl!, iconEl);
+  }
+
+  /**
+   * Append icon first, then value
+   */
+  private appendIconThenValue(iconEl: HTMLElement, hasValue: boolean): void {
+    this.renderer.appendChild(this.badgeEl!, iconEl);
+    if (hasValue) {
+      const textNode = this.renderer.createText(String(this.badge.value));
+      this.renderer.appendChild(this.badgeEl!, textNode);
+    }
+  }
+
+  /**
+   * Updates the CSS classes of the badge element based on the badge configuration.
+   * Applies size, style, and dot mode classes.
+   */
+  private updateBadgeClasses(): void {
+    if (!this.badgeEl) return;
+
+    this.renderer.setAttribute(this.badgeEl, 'class', 'frg-badge');
+
+    if (this.badge.size) {
+      this.renderer.addClass(this.badgeEl, `frg-badge--${this.badge.size}`);
+    }
+
+    if (this.badge.style) {
+      this.renderer.addClass(this.badgeEl, `frg-badge--${this.badge.style}`);
+    }
+
+    if (this.badge.dot) {
+      this.renderer.addClass(this.badgeEl, 'frg-badge--dot');
+    }
+
+    if (this.badge.disabled) {
+      this.renderer.addClass(this.badgeEl, 'frg-badge--disabled');
+    }
+  }
+
+  /**
+   * Removes the badge element from the host element and clears the reference.
+   * Used when the badge should be hidden.
+   */
+  private removeBadge(): void {
+    if (this.badgeEl) {
+      this.renderer.removeChild(this.host.nativeElement, this.badgeEl);
+      this.badgeEl = undefined;
+    }
+  }
+
+  /**
+   * Determines whether the badge should be hidden based on its configuration.
+   * Returns true if the badge is marked as hidden or has no value in non-dot mode.
+   */
+  private shouldHide(): boolean {
+    if (this.badge.hidden) return true;
+
+    if (this.badge.dot) return false;
+
+    return (
+      this.badge.value === null ||
+      this.badge.value === undefined ||
+      this.badge.value === ''
+    );
+  }
+}

package/src/lib/components/status/directives/badge/badge.interface.ts

@@ -0,0 +1,19 @@
+import { StatusIndicator } from "../../status.interface";
+
+export interface Badge extends Partial<StatusIndicator> {
+  /**
+   * Badge numeric or string value.
+   * If null or undefined and `dot` is false → badge is hidden.
+   */
+  value?: string | number | null;
+
+  /**
+   * Dot mode: shows only a small circular indicator.
+   */
+  dot?: boolean;
+
+  /**
+   * Determines whether the badge is hidden.
+   */
+  hidden?: boolean;
+}

package/src/lib/components/status/pill/pill.component.html

@@ -0,0 +1,40 @@
+<span
+  class="frg-pill"
+  [class.frg-pill--disabled]="disabled"
+  [class.removable]="removable"
+  [ngClass]="[
+    'frg-pill--' + style,
+    'frg-pill--' + size,
+    iconPosition === 'end' ? 'frg-pill--icon-end' : 'frg-pill--icon-start'
+  ]"
+>
+
+  @if(icon && iconPosition === 'start') {
+    <span class="frg-pill__icon">
+      <i [class]="icon"></i>
+    </span>
+  }
+
+  @if(label) {
+    <span class="frg-pill__label">
+      {{ label }}
+    </span>
+  }
+
+  @if(icon && iconPosition === 'end') {
+    <span class="frg-pill__icon">
+      <i [class]="icon"></i>
+    </span>
+  }
+
+  @if(removable) {
+    <button
+      class="frg-pill__remove"
+      type="button"
+      aria-label="Remove pill"
+      (click)="onRemove()"
+    >
+      ×
+    </button>
+  }
+</span>

package/src/lib/components/status/pill/pill.component.scss

@@ -0,0 +1,113 @@
+@use 'sass:color';
+@use './../../../../../assets/styles/scss/variables' as *;
+
+:host {
+  .frg-pill {
+    display: inline-flex;
+    align-items: center;
+    border-radius: 9999px; // pill shape
+    font-family: $base-font;
+    font-weight: 500;
+    line-height: 1.2;
+    cursor: default;
+    user-select: none;
+
+    padding: 0.25rem 0.75rem;
+    font-size: $font-size-sm;
+
+    &.frg-pill--sm {
+      padding: 0.125rem 0.5rem;
+      font-size: $font-size-xs;
+    }
+
+    &.frg-pill--md {
+      padding: 0.25rem 0.75rem;
+      font-size: $font-size-sm;
+    }
+
+    &.frg-pill--lg {
+      padding: 0.375rem 1rem;
+      font-size: $font-size-md;
+    }
+
+    // Style variants
+    &.frg-pill--primary {
+      background-color: $color-primary;
+      color: $color-light;
+    }
+    &.frg-pill--secondary {
+      background-color: $color-secondary;
+      color: $color-dark;
+    }
+    &.frg-pill--tertiary {
+      background-color: $color-tertiary;
+      color: $color-light;
+    }
+    &.frg-pill--success {
+      background-color: $color-success;
+      color: $color-light;
+    }
+    &.frg-pill--warning {
+      background-color: $color-warning;
+      color: $color-dark;
+    }
+    &.frg-pill--danger {
+      background-color: $color-danger;
+      color: $color-light;
+    }
+    &.frg-pill--info {
+      background-color: $color-info;
+      color: $color-light;
+    }
+    &.frg-pill--dark {
+      background-color: $color-dark;
+      color: $color-light;
+    }
+    &.frg-pill--light {
+      background-color: $color-light;
+      color: $color-dark;
+    }
+
+    // Disabled state
+    &.frg-pill--disabled {
+      background-color: $color-light-neutral;
+      color: $color-disabled-text;
+      pointer-events: none;
+      opacity: 0.6;
+    }
+
+    .frg-pill__icon {
+      display: inline-flex;
+      align-items: center;
+      margin: 0;
+
+      & + .frg-pill__label {
+        margin-left: 0.5rem;
+      }
+    }
+
+    .frg-pill--icon-end .frg-pill__icon {
+      margin-left: 0.5rem;
+      margin-right: 0;
+    }
+
+    .frg-pill__label {
+      display: inline-block;
+    }
+
+    .frg-pill__remove {
+      background: transparent;
+      border: none;
+      cursor: pointer;
+      margin-left: 0.5rem;
+      font-size: 1rem;
+      line-height: 1;
+      padding: 0;
+      color: inherit;
+
+      &:hover {
+        opacity: 0.8;
+      }
+    }
+  }
+}

package/src/lib/components/status/pill/pill.component.spec.ts

@@ -0,0 +1,47 @@
+import { ComponentFixture, TestBed } from '@angular/core/testing';
+import { By } from '@angular/platform-browser';
+import { PillComponent } from './pill.component';
+
+describe('PillComponent', () => {
+  let fixture: ComponentFixture<PillComponent>;
+  let component: PillComponent;
+
+  beforeEach(async () => {
+    await TestBed.configureTestingModule({
+      imports: [PillComponent]
+    }).compileComponents();
+
+    fixture = TestBed.createComponent(PillComponent);
+    component = fixture.componentInstance;
+  });
+
+  it('renders the label', () => {
+    component.label = 'New';
+
+    fixture.detectChanges();
+
+    const label = fixture.debugElement.query(By.css('.frg-pill__label'));
+    expect(label.nativeElement.textContent).toContain('New');
+  });
+
+  it('applies disabled class when disabled', () => {
+    component.disabled = true;
+
+    fixture.detectChanges();
+
+    const host = fixture.debugElement.query(By.css('.frg-pill'));
+    expect(host.nativeElement.classList).toContain('frg-pill--disabled');
+  });
+
+  it('emits removed when removable and not disabled', () => {
+    const emitSpy = spyOn(component.removed, 'emit');
+    component.removable = true;
+
+    fixture.detectChanges();
+
+    const removeButton = fixture.debugElement.query(By.css('.frg-pill__remove'));
+    removeButton.nativeElement.click();
+
+    expect(emitSpy).toHaveBeenCalledWith(component.id);
+  });
+});

package/src/lib/components/status/pill/pill.component.ts

@@ -0,0 +1,83 @@
+import { NgClass } from '@angular/common';
+import { Component, EventEmitter, Input, Output } from '@angular/core';
+import { generateUUID } from '../../../utils/uuid.utils';
+import { Pill, TPillIconPosition, TPillSize, TPillType } from './pill.type';
+
+/**
+ * TagComponent
+ *
+ * A small UI element used to display labeled statuses, metadata, or categories.
+ * Supports icons, removable behavior, disabled state, and standardized design-
+ * system styles and sizes. Implements the shared `Tag` interface to ensure
+ * consistency across all status-driven UI components (Tag, Badge, Chip, etc.).
+ */
+@Component({
+  selector: 'frg-pill',
+  templateUrl: './pill.component.html',
+  styleUrls: ['./pill.component.scss'],
+  imports: [NgClass]
+})
+export class PillComponent implements Pill {
+
+  /**
+   * Unique identifier for the tag.
+   * Automatically generated if not provided by the parent.
+   * Used primarily for tracking and removal events.
+   */
+  @Input() id: string = generateUUID();
+
+  /**
+   * Text content displayed inside the tag.
+   */
+  @Input() label?: string = '';
+
+  /**
+   * Visual style of the pill.
+   * Corresponds to design-system status color tokens.
+   * Example: 'primary', 'secondary', 'success', 'warning', etc.
+   */
+  @Input() style: TPillType = 'primary';
+
+  /**
+   * Size variant of the pill.
+   * Options follow the standardized sizing tokens: 'sm', 'md', or 'lg'.
+   */
+  @Input() size: TPillSize = 'md';
+
+  /**
+   * Optional icon class displayed before the label.
+   * Example: 'frg-icon-info', 'frg-icon-alert'.
+   */
+  @Input() icon: string | undefined = undefined;
+
+  /**
+   *  Position of the icon
+   */
+  @Input() iconPosition: TPillIconPosition = 'end';
+
+  /**
+   * Whether the pill is disabled.
+   * Disables interactions and applies the disabled visual style.
+   */
+  @Input() disabled = false;
+
+  /**
+   * If true, displays a remove button allowing the pill to be dismissed.
+   */
+  @Input() removable = false;
+
+  /**
+   * Emits the ID of the pill when it is removed.
+   */
+  @Output() removed = new EventEmitter<string>();
+
+  /**
+   * Emits the `removed` event when the remove button is clicked,
+   * provided the tag is not disabled and removal is allowed.
+   */
+  onRemove(): void {
+    if (!this.disabled && this.removable) {
+      this.removed.emit(this.id);
+    }
+  }
+}

package/src/lib/components/status/pill/pill.type.ts

@@ -0,0 +1,42 @@
+import { StatusIndicator } from "../status.interface";
+import { TBaseStatusIconPosition, TBaseStatusSize, TBaseStatusStyle } from "../status.type";
+
+/**
+ * TagType
+ *
+ * Alias for `TBaseStatusStyle`.
+ * Represents the visual style of a tag according to the design system.
+ * Example: 'primary', 'secondary', 'success', etc.
+ */
+export type TPillType = TBaseStatusStyle;
+
+/**
+ * PillSize
+ *
+ * Alias for `TBaseStatusSize`.
+ * Defines the size of the pill. Options: 'sm', 'md', 'lg'.
+ */
+export type TPillSize = TBaseStatusSize;
+
+/**
+ * PillIconPosition
+ *
+ * Alias for `TBaseStatusIconPosition`.
+ * Defines the icon position of the icon in the pill. Options: 'start' or 'end'.
+ */
+export type TPillIconPosition = TBaseStatusIconPosition;
+/**
+ * Pill
+ *
+ * A UI element that extends the shared `StatusIndicator` interface.
+ * Represents a labeled status, optionally removable.
+ *
+ * @extends StatusIndicator
+ */
+export interface Pill extends StatusIndicator {
+  /**
+   * If true, the pill can be removed by the user.
+   * Triggers the `removed` event in the component.
+   */
+  removable?: boolean;
+}

package/src/lib/components/status/status.interface.ts

@@ -0,0 +1,57 @@
+import { TBaseStatusIconPosition, TBaseStatusSize, TBaseStatusStyle } from "./status.type";
+
+/**
+ * StatusIndicator
+ *
+ * Base interface for all UI components that represent a status or state.
+ * Provides standardized properties for label, visual style, size, icon, and
+ * interaction state. This interface is intended to be extended by components
+ * such as Tag, Badge, Chip, etc.
+ */
+export interface StatusIndicator {
+  /**
+   * Unique identifier for the status element.
+   * Used for tracking, removal, or other programmatic operations.
+   */
+  id: string;
+  /**
+   * Text label displayed within the UI element.
+   */
+  label?: string;
+  /**
+   * Visual style of the element.
+   * Corresponds to the design system status colors.
+   * Example: 'primary', 'secondary', 'success', 'warning', etc.
+   *
+   * @see TBaseStatusStyle
+   */
+  style: TBaseStatusStyle;
+  /**
+   * Optional size of the element.
+   * Should conform to design-system sizing tokens.
+   * Example: 'sm', 'md', 'lg'.
+   *
+   * @see TBaseStatusSize
+   */
+  size?: TBaseStatusSize;
+  /**
+   * Optional icon class displayed before the label.
+   * Example: 'frg-icon-info', 'frg-icon-alert'.
+   */
+  icon?: string;
+  /**
+   * Determines the position of the icon relative to the label in a status-based component
+   * such as a tag, badge, or chip.
+   *
+   * Available options:
+   * - 'start' — icon appears before the label (default)
+   * - 'end' — icon appears after the label
+   *
+   * @see TBaseStatusIconPosition
+   */
+  iconPosition?: TBaseStatusIconPosition
+  /**
+   * If true, the element is disabled and user interactions are blocked.
+   */
+  disabled?: boolean;
+}

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

@@ -0,0 +1,62 @@
+/**
+ * TBaseStatusStyle
+ *
+ * Represents the allowed visual styles for status-based UI components.
+ * Typically maps to the design system color palette for components like
+ * tags, badges, or chips.
+ *
+ * Available options:
+ * - 'primary'
+ * - 'secondary'
+ * - 'tertiary'
+ * - 'info'
+ * - 'success'
+ * - 'warning'
+ * - 'danger'
+ * - 'dark'
+ * - 'light'
+ */
+export type TBaseStatusStyle =
+  'primary'
+  | 'secondary'
+  | 'tertiary'
+  | 'info'
+  | 'warning'
+  | 'danger'
+  | 'success'
+  | 'dark'
+  | 'light';
+
+/**
+ * TBaseStatusSize
+ *
+ * Represents the allowed sizes for status-based UI components.
+ * Used to adjust the dimensions and spacing of elements like tags, badges,
+ * or chips.
+ *
+ * Available options:
+ * - 'sm' (small)
+ * - 'md' (medium, default)
+ * - 'lg' (large)
+ */
+export type TBaseStatusSize =
+  'sm'
+  | 'md'
+  | 'lg';
+
+/**
+ * TBaseStatusIconPosition
+ *
+ * Represents the allowed positions for an icon inside a status-based UI component
+ * such as a tag, badge, or chip.
+ *
+ * Determines whether the icon appears before (start) or after (end) the label.
+ *
+ * Available options:
+ * - 'start' (default) — icon appears before the label
+ * - 'end' — icon appears after the label
+ */
+export type TBaseStatusIconPosition =
+  'start'
+  | 'end';
+

package/src/lib/components/status/tag/tag.component.html

@@ -0,0 +1,39 @@
+<span
+  class="frg-tag"
+  [class.frg-tag--disabled]="disabled"
+  [class.removable]="removable"
+  [ngClass]="[
+    'frg-tag--' + style,
+    'frg-tag--' + size,
+    iconPosition === 'end' ? 'frg-tag--icon-end' : ''
+  ]"
+>
+  @if(icon && iconPosition === 'start') {
+    <span class="frg-tag__icon">
+      <i [class]="icon"></i>
+    </span>
+  }
+
+  @if(label) {
+    <span class="frg-tag__label">
+      {{ label }}
+    </span>
+  }
+
+  @if(icon && iconPosition === 'end') {
+    <span class="frg-tag__icon">
+      <i [class]="icon"></i>
+    </span>
+  }
+
+  @if(removable) {
+    <button
+      class="frg-tag__remove"
+      type="button"
+      aria-label="Remove tag"
+      (click)="onRemove()"
+    >
+      ×
+    </button>
+  }
+</span>