tailjng 0.1.6 → 0.1.7

package/src/lib/components/select/select-multi-dropdown/multi-dropdown-select.component.ts

@@ -1,144 +1,275 @@
-import { Component, Input, Output, EventEmitter, ElementRef, ViewChild, OnDestroy, ChangeDetectorRef, AfterViewInit, OnInit, SimpleChanges, OnChanges, Optional, } from "@angular/core"
-import { FormsModule, type ControlValueAccessor, ReactiveFormsModule, NG_VALUE_ACCESSOR } from "@angular/forms"
-import { CommonModule } from "@angular/common"
-import { LucideAngularModule } from "lucide-angular"
-import { animate, style, transition, trigger } from "@angular/animations"
-import { JGenericCrudService, JIconsService } from "tailjng"
-import { debounceTime, distinctUntilChanged, Subject, Subscription } from "rxjs"
-
-interface ProcessedOption {
-  value: any
-  text: string
-  original?: any
-}
-
+import { animate, style, transition, trigger } from '@angular/animations';
+import { CommonModule } from '@angular/common';
+import {
+  AfterViewInit,
+  ChangeDetectorRef,
+  Component,
+  ElementRef,
+  EventEmitter,
+  Input,
+  OnChanges,
+  OnDestroy,
+  OnInit,
+  Optional,
+  Output,
+  SimpleChanges,
+  ViewChild,
+  forwardRef,
+} from '@angular/core';
+import {
+  ControlValueAccessor,
+  FormsModule,
+  NG_VALUE_ACCESSOR,
+  ReactiveFormsModule,
+} from '@angular/forms';
+import { debounceTime, distinctUntilChanged, Subject, Subscription } from 'rxjs';
+import { JGenericCrudService } from 'tailjng';
+import { Icons } from '../../.config/icons/icons.lucide';
+import { JIconComponent } from '../../icon/icon.component';
+import type {
+  MultiDropdownOption,
+  MultiDropdownSelectDefaultFilters,
+  MultiDropdownSelectDynamicParams,
+  MultiDropdownSelectType,
+  MultiDropdownSortOrder,
+} from './multi-dropdown-select.types';
+import {
+  DROPDOWN_PANEL_DEFAULTS,
+  filterOptionsBySearch,
+  mapObjectOptions,
+  mapPrimitiveOptions,
+  normalizeMultiDropdownValue,
+  positionDropdownPanel,
+  rebuildEndpointUrl,
+  resetDropdownPanelStyles,
+} from './multi-dropdown-select.util';
+
+export type {
+  MultiDropdownOption,
+  MultiDropdownSelectDefaultFilters,
+  MultiDropdownSelectDynamicParams,
+  MultiDropdownSelectType,
+  MultiDropdownSortOrder,
+} from './multi-dropdown-select.types';
+export {
+  DROPDOWN_PANEL_DEFAULTS,
+  filterOptionsBySearch,
+  getNestedValue,
+  mapObjectOptions,
+  mapPrimitiveOptions,
+  normalizeMultiDropdownValue,
+  positionDropdownPanel,
+  rebuildEndpointUrl,
+  resetDropdownPanelStyles,
+  resolveOptionLabel,
+} from './multi-dropdown-select.util';
+
+/**
+ * Multi-select dropdown with static options or searchable CRUD endpoint.
+ * Panel uses fixed viewport positioning (dialogs, tables, filter popovers).
+ *
+ * Install: `npx tailjng add select-multi-dropdown`
+ *
+ * ```html
+ * <JMultiDropdownSelect
+ *   [(ngModel)]="demoMultiSelect"
+ *   [options]="selectOptions"
+ *   optionLabel="text"
+ *   optionValue="value"
+ *   [enableSelectAll]="true"
+ * />
+ * ```
+ *
+ * Icons in template: `[icon]="Icons.Check"` (see `readonly Icons = Icons`).
+ */
 @Component({
-  selector: "JMultiDropdownSelect",
-  imports: [LucideAngularModule, CommonModule, FormsModule, ReactiveFormsModule],
-  templateUrl: "./multi-dropdown-select.component.html",
-  styleUrl: "./multi-dropdown-select.component.css",
+  selector: 'JMultiDropdownSelect',
+  imports: [JIconComponent, CommonModule, FormsModule, ReactiveFormsModule],
+  templateUrl: './multi-dropdown-select.component.html',
+  styleUrl: './multi-dropdown-select.component.css',
   animations: [
-    trigger("modalTransition", [
-      transition(":enter", [
-        style({ transform: "translateX(1rem)", opacity: 0 }),
-        animate("300ms ease-out", style({ transform: "translateY(0)", opacity: 1 })),
+    trigger('modalTransition', [
+      transition(':enter', [
+        style({ transform: 'translateX(1rem)', opacity: 0 }),
+        animate('300ms ease-out', style({ transform: 'translateY(0)', opacity: 1 })),
+      ]),
+      transition(':leave', [
+        animate('150ms ease-in', style({ transform: 'translateX(1rem)', opacity: 0 })),
       ]),
-      transition(":leave", [animate("150ms ease-in", style({ transform: "translateX(1rem)", opacity: 0 }))]),
     ]),
   ],
   providers: [
     {
       provide: NG_VALUE_ACCESSOR,
-      useExisting: JMultiDropdownSelectComponent,
+      useExisting: forwardRef(() => JMultiDropdownSelectComponent),
       multi: true,
     },
   ],
 })
-export class JMultiDropdownSelectComponent implements ControlValueAccessor, AfterViewInit, OnInit, OnChanges, OnDestroy {
+export class JMultiDropdownSelectComponent
+  implements ControlValueAccessor, OnInit, AfterViewInit, OnChanges, OnDestroy
+{
+  // Project Icons registry — template usage: Icons.Check, Icons.Loader2, …
+  readonly Icons = Icons;
 
-  @Input() title = "Seleccionar opciones"
-  @Input() placeholder = "Seleccione opciones"
-  @Input() showClear = true
-  @Input() isDisabled = false
-  @Input() isLoading = false
+  // =====================================================
+  // Inputs / outputs
+  // =====================================================
 
-  @Input() options: any[] = []
-  @Input() optionLabel: string | string[] = "text"
-  @Input() optionValue = "value"
-  @Input() labelSeparator = " "
+  // Panel heading above the option list
+  @Input() title = 'Seleccionar opciones';
 
-  /** "dropdown" = local, "searchable" = remota con búsqueda */
-  @Input() type: 'dropdown' | 'searchable' = 'dropdown';
+  // Trigger label when nothing is selected
+  @Input() placeholder = 'Seleccione opciones';
 
-  /** endpoint base, ej: "users" o "users/{companyId}/roles" */
-  private _rawEndpoint = '';
-  _finalEndpoint = '';
-  @Input() set endpoint(value: string) { this._rawEndpoint = value; this.rebuildEndpoint(); }
-  get endpoint() { return this._rawEndpoint; }
+  // Shows clear (X) on the trigger when at least one value is selected
+  @Input() showClear = true;
+
+  @Input() isDisabled = false;
+
+  // Loading state on trigger or panel (API / parent control)
+  @Input() isLoading = false;
+
+  // Static options (`string[]` or object array with optionLabel / optionValue)
+  @Input() options: unknown[] = [];
 
-  /** reemplaza {keys} en endpoint, ej: { companyId: 12 } */
-  private _dynamicParams: Record<string, any> = {};
-  @Input() set dynamicParams(v: Record<string, any>) { this._dynamicParams = v; this.rebuildEndpoint(); }
-  get dynamicParams() { return this._dynamicParams; }
+  // Property name(s) used to build option text (supports dot paths)
+  @Input() optionLabel: string | string[] = 'text';
+
+  // Property name used as the option value
+  @Input() optionValue = 'value';
+
+  // Separator when `optionLabel` is an array of keys
+  @Input() labelSeparator = ' ';
+
+  // `dropdown` = local options · `searchable` = CRUD endpoint + debounced search
+  @Input() type: MultiDropdownSelectType = 'dropdown';
+
+  /** CRUD endpoint; supports `{param}` placeholders resolved via `dynamicParams`. */
+  @Input() set endpoint(value: string) {
+    this.rawEndpoint = value;
+    this.rebuildEndpoint();
+  }
+
+  get endpoint(): string {
+    return this.rawEndpoint;
+  }
 
-  /** filtros por defecto -> se envían como filter[key]=value */
-  @Input() defaultFilters: Record<string, any> = {};
-  /** campos extra para búsqueda en servidor */
+  /** Values substituted into `{param}` segments of `endpoint`. */
+  @Input() set dynamicParams(value: MultiDropdownSelectDynamicParams) {
+    this.endpointDynamicParams = value;
+    this.rebuildEndpoint();
+  }
+
+  get dynamicParams(): MultiDropdownSelectDynamicParams {
+    return this.endpointDynamicParams;
+  }
+
+  // Searchable: default `filter[key]` query params
+  @Input() defaultFilters: MultiDropdownSelectDefaultFilters = {};
+
+  // Searchable: extra fields included in API search
   @Input() searchFields: string[] = [];
-  /** ASC/DESC para el backend */
-  @Input() sort: 'ASC' | 'DESC' = 'ASC';
-  @Input() limit: number = 1000;
 
+  // Searchable: sort order sent to the API
+  @Input() sort: MultiDropdownSortOrder = 'ASC';
+
+  // Searchable: max records per request
+  @Input() limit = 1000;
 
-  /** cargar al iniciar (solo searchable) */
+  // Searchable: fetch on init
   @Input() loadOnInit = false;
-  /** cargar al abrir (solo searchable) */
+
+  // Searchable: fetch when the panel opens
   @Input() loadOpen = false;
 
-  /** activar input de búsqueda (local o remota según type) */
+  // Panel search input (local filter or remote search depending on `type`)
   @Input() isSearch = false;
 
-  /** emite el data crudo recibido del backend */
-  @Output() fullData = new EventEmitter<any[]>();
+  /** Searchable: emits the full API result array after each load. */
+  @Output() fullData = new EventEmitter<unknown[]>();
 
-  searchTerm = '';
-  private readonly searchSubject = new Subject<string>();
-  private searchSubscription?: Subscription;
+  // Shows the “select all” row at the top of the panel
+  @Input() enableSelectAll = true;
 
-  /** opciones filtradas para pintar lista (soporta búsqueda) */
-  filteredProcessedOptions: ProcessedOption[] = [];
+  // Trigger label when every option is selected
+  @Input() labelSelectAll = 'TODOS';
 
-  /** para mapear respuesta */
-  mainEndpoint!: string;
+  // Separator between selected item labels on the trigger
+  @Input() multipleSeparator = ', ';
 
-  // Multi-selection
-  @Input() enableSelectAll = true
-  @Input() labelSelectAll = "TODOS"
-  @Input() multipleSeparator = ", "
-  @Input() maxDisplayItems = 3
+  // Max selected labels shown on the trigger before “y N más”
+  @Input() maxDisplayItems = 3;
 
+  /** Emits the array of selected values (empty when cleared). */
+  @Output() selectionChange = new EventEmitter<unknown[]>();
 
-  @Output() selectionChange = new EventEmitter<any[]>()
+  /** @deprecated Kept for backward compatibility; panel positioning no longer uses this flag. */
   @Input() isFilterSelect = false;
 
-  @ViewChild("selectButton") selectButton!: ElementRef
+  // =====================================================
+  // View / state
+  // =====================================================
 
-  isDropdownOpen = false
-  selectedValues: any[] = []
-  processedOptions: ProcessedOption[] = []
-  displayLabel = ""
+  @ViewChild('selectButton') selectButton!: ElementRef<HTMLElement>;
+  @ViewChild('dropdownPanel') dropdownPanel?: ElementRef<HTMLElement>;
 
-  // Dropdown positioning
-  dropdownTop = 0
-  dropdownLeft = 0
-  dropdownWidth = 0
+  isDropdownOpen = false;
+  selectedValues: unknown[] = [];
+  processedOptions: MultiDropdownOption[] = [];
+  filteredProcessedOptions: MultiDropdownOption[] = [];
+  displayLabel = '';
 
-  // ControlValueAccessor
-  private onChange: any = () => { }
-  private onTouched: any = () => { }
+  searchTerm = '';
+  dropdownWidth = 0;
+
+  mainEndpoint = '';
 
-  // Click outside listener
-  private clickOutsideListener: any
+  /** Resolved endpoint after `{param}` substitution (used by searchable mode). */
+  _finalEndpoint = '';
+
+  private rawEndpoint = '';
+  private endpointDynamicParams: MultiDropdownSelectDynamicParams = {};
+
+  private readonly searchSubject = new Subject<string>();
+  private searchSubscription?: Subscription;
+  private clickOutsideListener?: (event: MouseEvent) => void;
+
+  private onChange: (value: unknown[]) => void = () => {};
+  private onTouched: () => void = () => {};
+
+  private readonly panelPositionConfig = DROPDOWN_PANEL_DEFAULTS;
+  private readonly repositionDropdown = () => {
+    if (this.isDropdownOpen) {
+      this.updateDropdownPosition();
+    }
+  };
 
   constructor(
-    public readonly iconsService: JIconsService,
     private readonly cdr: ChangeDetectorRef,
-    private readonly elementRef: ElementRef,
+    private readonly elementRef: ElementRef<HTMLElement>,
     @Optional() private readonly genericService: JGenericCrudService | null,
-  ) { }
+  ) {}
+
+  // =====================================================
+  // Lifecycle
+  // =====================================================
 
-  ngOnInit() {
+  ngOnInit(): void {
     this.updateDisplayLabel();
 
-    // preparar mainEndpoint (clave del array en response.data)
-    if (this.endpoint) this.mainEndpoint = this.endpoint.split('/')[0] ?? this.endpoint;
+    if (this.endpoint) {
+      this.mainEndpoint = this.endpoint.split('/')[0] ?? this.endpoint;
+    }
 
-    // suscripción de búsqueda (server-side si type = 'searchable')
     this.searchSubscription = this.searchSubject
       .pipe(debounceTime(600), distinctUntilChanged())
       .subscribe(() => {
-        if (this.type === 'searchable') this.loadData();
-        else this.filterOptionsLocally();
+        if (this.type === 'searchable') {
+          this.loadData();
+        } else {
+          this.filterOptionsLocally();
+        }
       });
 
     if (this.type === 'searchable' && this.loadOnInit) {
@@ -146,492 +277,377 @@ export class JMultiDropdownSelectComponent implements ControlValueAccessor, Afte
     }
   }
 
-  ngAfterViewInit() {
-    this.setupClickOutsideListener()
+  ngAfterViewInit(): void {
+    this.setupClickOutsideListener();
     setTimeout(() => this.processOptions());
   }
 
   ngOnChanges(changes: SimpleChanges): void {
-    if (changes['options']) this.processOptions();
+    if (changes['options']) {
+      this.processOptions();
+    }
   }
 
-  ngOnDestroy() {
+  ngOnDestroy(): void {
+    this.removeRepositionListeners();
+
     if (this.clickOutsideListener) {
-      document.removeEventListener("click", this.clickOutsideListener)
+      document.removeEventListener('click', this.clickOutsideListener);
     }
-  }
 
-  // ============================
-  //  ENDPOINT dinámico
-  // ============================
-  private rebuildEndpoint() {
-    if (!this._rawEndpoint) return;
-    this._finalEndpoint = this._rawEndpoint.replace(/\{([^}]+)\}/g, (_, key) => {
-      return this._dynamicParams?.[key] ?? '';
-    });
-    // Si cambia endpoint/params y el dropdown está abierto, recargar si aplica
-    if (this.type === 'searchable' && (this.loadOnInit || this.loadOpen || this.isDropdownOpen)) {
-      this.loadData();
-    }
+    this.searchSubscription?.unsubscribe();
   }
 
-  // ============================
-  //  Procesamiento opciones
-  // ============================
-  processOptions() {
-    // Si llegan opciones por @Input (modo local), respétalas
-    if (this.options && this.options.length > 0 && typeof this.options[0] !== 'object') {
-      this.processedOptions = this.options.map((opt) => ({ value: opt, text: opt.toString() }));
-    } else if (this.options && this.options.length > 0) {
-      this.processedOptions = this.options.map((option) => {
-        const text = Array.isArray(this.optionLabel)
-          ? this.optionLabel.map((k) => this.getNestedValue(option, k)).join(this.labelSeparator)
-          : this.getNestedValue(option, this.optionLabel);
-        return { value: this.normalizeOptionValue(option[this.optionValue]), text, original: option };
-      });
-    } else if (!(this.type === 'searchable' && this.endpoint)) {
-      // No vaciar opciones ya cargadas desde API (modo remoto)
-      this.processedOptions = [];
-    }
-
-    // inicial para pintar
-    this.filteredProcessedOptions = [...this.processedOptions];
+  // =====================================================
+  // ControlValueAccessor
+  // =====================================================
 
+  /**
+   * Writes selected values from Angular forms into the component.
+   * @param value Array of selected values or `null`.
+   */
+  writeValue(value: unknown[] | null): void {
+    this.selectedValues = Array.isArray(value)
+      ? value.map((item) => normalizeMultiDropdownValue(item))
+      : [];
     this.updateDisplayLabel();
-    this.cdr.detectChanges();
+    this.cdr.markForCheck();
   }
 
-  // ============================
-  //  Carga desde API
-  // ============================
-  loadData() {
-    if (!this._finalEndpoint || !this.genericService) return;
-
-    this.isLoading = true;
-
-    const params: any = { sortOrder: this.sort, limit: this.limit };
-
-    // filtros por defecto
-    Object.keys(this.defaultFilters).forEach((k) => {
-      params[`filter[${k}]`] = this.defaultFilters[k];
-    });
-
-    // búsqueda remota
-    if (this.isSearch && this.searchTerm.trim() !== '') {
-      const optionLabelsArray = Array.isArray(this.optionLabel) ? this.optionLabel : [this.optionLabel];
-      const allSearchFields = [...optionLabelsArray, ...this.searchFields];
-      params['search'] = this.searchTerm.trim();
-      params['searchFields'] = allSearchFields;
-    }
-
-    this.genericService.findAll<any>({ endpoint: this._finalEndpoint, params }).subscribe({
-      next: (resp) => {
-        const data = resp?.data?.[this.mainEndpoint] ?? resp?.data ?? [];
-        const list = Array.isArray(data) ? data : [];
-        // Mantener @Input options sincronizado (igual que JDropdownSelect) para processOptions()
-        this.options = list;
-        this.processedOptions = list.map((option: any) => ({
-          value: this.normalizeOptionValue(option?.[this.optionValue]),
-          text: Array.isArray(this.optionLabel)
-            ? this.optionLabel.map((k) => this.getNestedValue(option, k)).filter(Boolean).join(this.labelSeparator)
-            : this.getNestedValue(option, this.optionLabel),
-          original: option,
-        }));
+  /**
+   * Registers the change callback for Angular forms.
+   * @param fn Callback invoked when the selection changes.
+   */
+  registerOnChange(fn: (value: unknown[]) => void): void {
+    this.onChange = fn;
+  }
 
-        this.filteredProcessedOptions = [...this.processedOptions];
-        this.fullData.emit(data);
-        this.isLoading = false;
-        this.updateDisplayLabel();
-        this.cdr.detectChanges();
-      },
-      error: (err) => {
-        console.error('Error fetching data:', err);
-        this.isLoading = false;
-        this.cdr.detectChanges();
-      },
-    });
+  /**
+   * Registers the touched callback for Angular forms.
+   * @param fn Callback invoked when the control is touched.
+   */
+  registerOnTouched(fn: () => void): void {
+    this.onTouched = fn;
   }
 
-  // ============================
-  //  🔎 Búsqueda
-  // ============================
-  onSearchInput() {
-    // dispara debounce para ambos modos
-    this.searchSubject.next(this.searchTerm);
+  /**
+   * Syncs disabled state from Angular forms.
+   * @param isDisabled Whether the control is disabled.
+   */
+  setDisabledState(isDisabled: boolean): void {
+    this.isDisabled = isDisabled;
+    this.cdr.markForCheck();
   }
 
-  private filterOptionsLocally() {
-    if (!this.searchTerm.trim()) {
-      this.filteredProcessedOptions = [...this.processedOptions];
-      return;
+  // =====================================================
+  // Options
+  // =====================================================
+
+  /**
+   * Normalizes `options` into internal `{ value, text }` entries.
+   */
+  processOptions(): void {
+    if (this.options?.length > 0 && typeof this.options[0] !== 'object') {
+      this.processedOptions = mapPrimitiveOptions(this.options).map((option) => ({
+        ...option,
+        value: normalizeMultiDropdownValue(option.value),
+      }));
+    } else if (this.options?.length > 0) {
+      this.processedOptions = mapObjectOptions(
+        this.options as Record<string, unknown>[],
+        this.optionLabel,
+        this.optionValue,
+        this.labelSeparator,
+      ).map((option) => ({
+        ...option,
+        value: normalizeMultiDropdownValue(option.value),
+      }));
+    } else if (!(this.type === 'searchable' && this.endpoint)) {
+      this.processedOptions = [];
     }
-    const q = this.searchTerm.toLowerCase();
-    this.filteredProcessedOptions = this.processedOptions.filter(o => o.text.toLowerCase().includes(q));
+
+    this.filteredProcessedOptions = [...this.processedOptions];
+    this.updateDisplayLabel();
+    this.cdr.detectChanges();
   }
 
   /**
-   * Method to toggle option selection
-   * @param option
+   * Toggles one option in the selection array.
+   * @param option Normalized option from the panel list.
    */
-  toggleOption(option: ProcessedOption) {
-    const index = this.selectedValues.findIndex((v) => v === option.value);
-    if (index > -1) this.selectedValues.splice(index, 1);
-    else this.selectedValues.push(option.value);
+  toggleOption(option: MultiDropdownOption): void {
+    const index = this.selectedValues.findIndex((value) => value === option.value);
+
+    if (index > -1) {
+      this.selectedValues.splice(index, 1);
+    } else {
+      this.selectedValues.push(option.value);
+    }
 
     this.updateDisplayLabel();
     this.onChange(this.selectedValues);
     this.selectionChange.emit(this.selectedValues);
   }
 
-
-
   /**
-   * Method to toggle select all options
+   * Selects or clears every option in `processedOptions`.
    */
-  toggleSelectAll() {
-    const allValues = this.processedOptions.map((o) => o.value); // selecciona TODO el dataset, no solo filtrado
+  toggleSelectAll(): void {
+    const allValues = this.processedOptions.map((option) => option.value);
     this.selectedValues = this.isAllSelected() ? [] : [...allValues];
     this.updateDisplayLabel();
     this.onChange(this.selectedValues);
     this.selectionChange.emit(this.selectedValues);
   }
 
-
   /**
-   * Method to check if all options are selected
-   * @returns boolean
+   * Whether every processed option is currently selected.
+   * @returns `true` when all options are in `selectedValues`.
    */
   isAllSelected(): boolean {
-    const allValues = this.processedOptions.map((opt) => opt.value)
-    return allValues.length > 0 && allValues.every((v) => this.selectedValues.includes(v))
+    const allValues = this.processedOptions.map((option) => option.value);
+    return allValues.length > 0 && allValues.every((value) => this.selectedValues.includes(value));
   }
 
-
-
   /**
-   * Method to clear the selection
-   * @param event
+   * Clears all selected values without opening the panel.
+   * @param event Click event (stopped to avoid toggling the panel).
    */
-  clearSelection(event: Event) {
-    event.stopPropagation()
-    this.selectedValues = []
-    this.updateDisplayLabel()
-    this.onChange(this.selectedValues)
-    this.selectionChange.emit(this.selectedValues)
+  clearSelection(event: Event): void {
+    event.stopPropagation();
+    this.selectedValues = [];
+    this.updateDisplayLabel();
+    this.onChange(this.selectedValues);
+    this.selectionChange.emit(this.selectedValues);
   }
 
-  // ======================================================
-  // Display y UI
-  // ======================================================
-
   /**
-   * Method to update the display label based on selected values
-   * @returns void
+   * Builds the truncated label shown on the trigger.
    */
-  updateDisplayLabel() {
-
-    // Check if no values are selected
+  updateDisplayLabel(): void {
     if (this.selectedValues.length === 0) {
-      this.displayLabel = this.placeholder
-      return
+      this.displayLabel = this.placeholder;
+      return;
     }
 
-    // Verify if all options are selected
     if (this.enableSelectAll && this.isAllSelected()) {
-      this.displayLabel = this.labelSelectAll
-      return
+      this.displayLabel = this.labelSelectAll;
+      return;
     }
 
-    // Get texts of selected options
     const selectedTexts = this.processedOptions
-      .filter((opt) => this.selectedValues.includes(opt.value))
-      .map((opt) => opt.text)
+      .filter((option) => this.selectedValues.includes(option.value))
+      .map((option) => option.text);
 
     if (selectedTexts.length <= this.maxDisplayItems) {
-      this.displayLabel = selectedTexts.join(this.multipleSeparator)
-    } else {
-      const visibleItems = selectedTexts.slice(0, this.maxDisplayItems)
-      const remainingCount = selectedTexts.length - this.maxDisplayItems
-      this.displayLabel = `${visibleItems.join(this.multipleSeparator)} y ${remainingCount} más`
+      this.displayLabel = selectedTexts.join(this.multipleSeparator);
+      return;
     }
-  }
 
+    const visibleItems = selectedTexts.slice(0, this.maxDisplayItems);
+    const remainingCount = selectedTexts.length - this.maxDisplayItems;
+    this.displayLabel = `${visibleItems.join(this.multipleSeparator)} y ${remainingCount} más`;
+  }
 
+  // =====================================================
+  // Search / API
+  // =====================================================
 
   /**
-   * Method to toggle the dropdown visibility
+   * Loads options from the CRUD API (searchable mode).
    */
-  toggleDropdown() {
-    if (this.isDisabled || this.isLoading) return;
-    this.isDropdownOpen = !this.isDropdownOpen;
-    if (this.isDropdownOpen) {
-      this.onTouched();
-      this.updateDropdownPosition();
+  loadData(): void {
+    if (!this._finalEndpoint || !this.genericService) {
+      return;
+    }
 
-      if (this.type === 'searchable' && (this.loadOpen || this.processedOptions.length === 0)) {
-        this.loadData();
-      }
+    this.isLoading = true;
+
+    const params: Record<string, unknown> = {
+      sortOrder: this.sort,
+      limit: this.limit,
+    };
+
+    Object.keys(this.defaultFilters).forEach((key) => {
+      params[`filter[${key}]`] = this.defaultFilters[key];
+    });
+
+    if (this.isSearch && this.searchTerm.trim()) {
+      const optionLabels = Array.isArray(this.optionLabel) ? this.optionLabel : [this.optionLabel];
+      params['search'] = this.searchTerm.trim();
+      params['searchFields'] = [...optionLabels, ...this.searchFields];
     }
-  }
 
-  // ======================================================
-  // Utilities
-  // ======================================================
+    this.genericService.findAll<Record<string, unknown>>({
+      endpoint: this._finalEndpoint,
+      params,
+    }).subscribe({
+      next: (response) => {
+        const data = (response?.data?.[this.mainEndpoint] ?? response?.data ?? []) as unknown;
+        const list = Array.isArray(data) ? data : [];
+
+        this.options = list;
+        this.processedOptions = mapObjectOptions(
+          list as Record<string, unknown>[],
+          this.optionLabel,
+          this.optionValue,
+          this.labelSeparator,
+        ).map((option) => ({
+          ...option,
+          value: normalizeMultiDropdownValue(option.value),
+        }));
+
+        this.filteredProcessedOptions = [...this.processedOptions];
+        this.fullData.emit(list);
+        this.isLoading = false;
+        this.updateDisplayLabel();
+
+        if (this.isDropdownOpen) {
+          this.updateDropdownPosition();
+        }
+
+        this.cdr.detectChanges();
+      },
+      error: (error) => {
+        console.error('Error fetching data:', error);
+        this.isLoading = false;
+        this.cdr.detectChanges();
+      },
+    });
+  }
 
   /**
-   * Get nested value from an object
-   * @param obj
-   * @param path
-   * @returns
+   * Handles panel search input — debounced API call or local filter.
    */
-  getNestedValue(obj: any, path: string): any {
-    return path.split(".").reduce((acc, part) => acc && acc[part], obj) ?? ""
+  onSearchInput(): void {
+    this.searchSubject.next(this.searchTerm);
   }
 
+  /** Resets the panel search field and re-runs {@link onSearchInput}. */
+  clearSearchTerm(): void {
+    this.searchTerm = '';
+    this.onSearchInput();
+  }
+
+  /** Applies local text filter to `processedOptions`. */
+  private filterOptionsLocally(): void {
+    this.filteredProcessedOptions = filterOptionsBySearch(this.processedOptions, this.searchTerm);
+  }
 
+  // =====================================================
+  // Panel open / position
+  // =====================================================
 
   /**
-   * Setup click outside listener to close dropdown
+   * Opens or closes the option panel.
+   * Searchable mode may trigger {@link loadData} on first open.
    */
-  setupClickOutsideListener() {
-    this.clickOutsideListener = (event: MouseEvent) => {
-      const clickedElement = event.target as HTMLElement
-      const isOutsideDropdown = !this.elementRef.nativeElement.contains(clickedElement)
-      if (this.isDropdownOpen && isOutsideDropdown) {
-        this.isDropdownOpen = false
-        this.cdr.detectChanges()
-      }
+  toggleDropdown(): void {
+    if (this.isDisabled || this.isLoading) {
+      return;
     }
-    document.addEventListener("click", this.clickOutsideListener)
-  }
 
+    this.isDropdownOpen = !this.isDropdownOpen;
 
-  /**
-   * Update the dropdown position based on the button
-   */
-  updateDropdownPosition() {
-    setTimeout(() => {
-      if (!this.selectButton) return
-
-      // Get button position
-      const button = this.selectButton.nativeElement
-      const buttonRect = button.getBoundingClientRect()
-
-      // Find the closest form container or dialog
-      let offsetParent: HTMLElement | null = this.selectButton.nativeElement
-      let isInSidebar = false
-
-      // Check if we're inside a sidebar form
-      while (
-        offsetParent &&
-        !offsetParent.classList.contains("content_form") &&
-        !offsetParent.classList.contains("p-dialog")
-      ) {
-        if (offsetParent.classList.contains("fixed") && offsetParent.classList.contains("right-0")) {
-          isInSidebar = true
-          break
-        }
-        offsetParent = offsetParent.parentElement
-      }
+    if (this.isDropdownOpen) {
+      this.onTouched();
+      this.addRepositionListeners();
+      this.updateDropdownPosition();
 
-      // Get offsets based on container
-      let offsetTop = 0
-      let offsetLeft = 0
-      if (
-        isInSidebar ||
-        (offsetParent &&
-          (offsetParent.classList.contains("content_form") || offsetParent.classList.contains("p-dialog")))
-      ) {
-        offsetTop = offsetParent ? offsetParent.getBoundingClientRect().top : 0
-        offsetLeft = offsetParent ? offsetParent.getBoundingClientRect().left : 0
+      if (this.type === 'searchable' && (this.loadOpen || this.processedOptions.length === 0)) {
+        this.loadData();
       }
 
-      // Position directly below the button by default
-      this.dropdownTop = buttonRect.bottom - offsetTop
-      this.dropdownLeft = buttonRect.left - offsetLeft
-      this.dropdownWidth = buttonRect.width
-      this.cdr.detectChanges()
-
-      // Wait for dropdown to be in DOM
-      setTimeout(() => {
-        // Get dropdown element
-        const dropdown = this.elementRef.nativeElement.querySelector(".absolute.z-\\[100\\]")
-        if (!dropdown) return
-
-        // First use fixed positioning to handle scroll position correctly
-        dropdown.style.position = "fixed"
-        dropdown.style.top = buttonRect.bottom + "px"
-        dropdown.style.left = buttonRect.left + "px"
-        dropdown.style.width = buttonRect.width + "px"
-        dropdown.style.zIndex = "600"
-
-        // Wait for dropdown to render with fixed positioning
-        setTimeout(() => {
-          // Get dropdown dimensions
-          const dropdownRect = dropdown.getBoundingClientRect()
-          const viewportHeight = window.innerHeight
-          const documentWidth = document.documentElement.clientWidth
-
-          // Determine if we need to flip or adjust position
-          let newFixedTop = buttonRect.bottom
-          let newFixedLeft = buttonRect.left
-
-          // Check if dropdown goes below viewport and flip it if needed
-          if (buttonRect.bottom + dropdownRect.height > viewportHeight) {
-            newFixedTop = buttonRect.top - dropdownRect.height
-          }
-
-          // Check if dropdown goes beyond right edge
-          if (buttonRect.left + dropdownRect.width > documentWidth) {
-            newFixedLeft = buttonRect.left - dropdownRect.width + buttonRect.width
-            if (newFixedLeft < 0) {
-              newFixedLeft = 5
-              if (dropdownRect.width > documentWidth) {
-                dropdown.classList.add("constrain-width")
-              }
-            }
-          }
-
-          // Apply adjusted fixed position
-          dropdown.style.top = newFixedTop - 5 + "px"
-          dropdown.style.left = newFixedLeft - 15 + "px"
-
-          // Button filter
-          if (this.isFilterSelect) {
-            setTimeout(() => {
-              // Calculate absolute position based on the current fixed position
-              let newAbsoluteTop
-              let newAbsoluteLeft
-
-              if (newFixedTop === buttonRect.bottom) {
-                // Dropdown is below the button
-                newAbsoluteTop = this.dropdownTop
-              } else {
-                // Dropdown is above the button (flipped)
-                newAbsoluteTop = buttonRect.top - dropdownRect.height - offsetTop
-              }
-
-              if (newFixedLeft === buttonRect.left) {
-                // Dropdown is aligned with left edge of button
-                newAbsoluteLeft = this.dropdownLeft
-              } else if (newFixedLeft === buttonRect.left - dropdownRect.width + buttonRect.width) {
-                // Dropdown is aligned with right edge of button
-                newAbsoluteLeft = buttonRect.left - dropdownRect.width + buttonRect.width - offsetLeft
-              } else {
-                // Dropdown is at a fixed position from left edge
-                newAbsoluteLeft = newFixedLeft
-              }
-
-              // Switch to absolute positioning
-              dropdown.style.position = "absolute"
-              dropdown.style.top = newAbsoluteTop + "px"
-              dropdown.style.left = newAbsoluteLeft - 2 + "px"
-
-              // Update internal state
-              this.dropdownTop = newAbsoluteTop
-              this.dropdownLeft = newAbsoluteLeft
-              this.cdr.detectChanges()
-            }, 0)
-          } else {
-            // After positioning is done, switch to absolute positioning
-            setTimeout(() => {
-              // Get the current visual position of the dropdown (relative to viewport)
-              const dropdownRect = dropdown.getBoundingClientRect()
-
-              // Find the dropdown's offset parent for absolute positioning
-              const dropdownOffsetParent = this.findPositionedParent(dropdown) || document.body
-              const parentRect = dropdownOffsetParent.getBoundingClientRect()
-
-              // Calculate absolute position that will maintain the same visual position
-              // Absolute positioning is relative to the offset parent
-              const absoluteTop = dropdownRect.top - parentRect.top + dropdownOffsetParent.scrollTop
-              const absoluteLeft = dropdownRect.left - parentRect.left + dropdownOffsetParent.scrollLeft
-
-              // Switch to absolute positioning with calculated coordinates
-              dropdown.style.position = "absolute"
-              dropdown.style.top = absoluteTop + "px"
-              dropdown.style.left = absoluteLeft + "px"
-
-              // Update internal state
-              this.dropdownTop = absoluteTop
-              this.dropdownLeft = absoluteLeft
-              this.cdr.detectChanges()
-            }, 0)
-          }
-        }, 0)
-      }, 0)
-    })
+      return;
+    }
+
+    this.closePanel(false);
   }
 
   /**
-   * Helper method to find the offset parent for absolute positioning
-   * @param element
-   * @returns
+   * Positions the floating panel with fixed viewport coordinates
+   * (flip above/below, clamp to window — see {@link positionDropdownPanel}).
    */
-  private findPositionedParent(element: HTMLElement): HTMLElement | null {
-    if (!element) return null
-    let parent = element.parentElement
-    while (parent) {
-      const position = window.getComputedStyle(parent).position
-      if (position === "relative" || position === "absolute" || position === "fixed") {
-        return parent
+  updateDropdownPosition(): void {
+    setTimeout(() => {
+      const button = this.selectButton?.nativeElement;
+      if (!button) {
+        return;
       }
-      parent = parent.parentElement
-    }
-    return document.body // Default to body if no positioned parent found
-  }
 
-  // ======================================================
-  // ControlValueAccessor Implementation
-  // ======================================================
+      const buttonRect = button.getBoundingClientRect();
+      this.dropdownWidth = buttonRect.width;
+      this.cdr.detectChanges();
 
-  /**
-   * Write the value to the component
-   * @param value
-   */
-  writeValue(value: any[] | null): void {
-    this.selectedValues = Array.isArray(value)
-      ? value.map((item) => this.normalizeOptionValue(item))
-      : [];
-    this.updateDisplayLabel();
-    this.cdr.markForCheck();
+      requestAnimationFrame(() => {
+        const panel = this.dropdownPanel?.nativeElement;
+        if (!panel) {
+          return;
+        }
+
+        positionDropdownPanel(panel, buttonRect, this.panelPositionConfig);
+        this.cdr.detectChanges();
+      });
+    });
   }
 
-  private normalizeOptionValue(value: unknown): unknown {
-    if (typeof value === 'string' && value.trim() !== '' && !Number.isNaN(Number(value))) {
-      return Number(value);
-    }
-    return value;
+  /** Document click listener — closes the panel when clicking outside. */
+  private setupClickOutsideListener(): void {
+    this.clickOutsideListener = (event: MouseEvent) => {
+      const clickedElement = event.target as HTMLElement;
+      const isOutsideDropdown = !this.elementRef.nativeElement.contains(clickedElement);
+
+      if (this.isDropdownOpen && isOutsideDropdown) {
+        this.closePanel();
+      }
+    };
+
+    document.addEventListener('click', this.clickOutsideListener);
   }
 
+  /** Closes the panel and clears reposition listeners / dynamic panel styles. */
+  private closePanel(detectChanges = true): void {
+    this.isDropdownOpen = false;
+    this.removeRepositionListeners();
+    this.resetDropdownPanelStyles();
 
+    if (detectChanges) {
+      this.cdr.detectChanges();
+    }
+  }
 
-  /**
-   * Register the change of the selected value
-   * @param fn
-   */
-  registerOnChange(fn: any): void {
-    this.onChange = fn
+  /** Re-applies panel position on scroll (capture) and window resize. */
+  private addRepositionListeners(): void {
+    window.addEventListener('scroll', this.repositionDropdown, true);
+    window.addEventListener('resize', this.repositionDropdown);
   }
 
+  /** Removes scroll/resize listeners registered while the panel is open. */
+  private removeRepositionListeners(): void {
+    window.removeEventListener('scroll', this.repositionDropdown, true);
+    window.removeEventListener('resize', this.repositionDropdown);
+  }
 
+  /** Resets dynamic max-height on the scrollable options list. */
+  private resetDropdownPanelStyles(): void {
+    const panel = this.dropdownPanel?.nativeElement;
+    if (!panel) {
+      return;
+    }
 
-  /**
-   * Register the touch event
-   * @param fn
-   */
-  registerOnTouched(fn: any): void {
-    this.onTouched = fn
+    resetDropdownPanelStyles(panel, this.panelPositionConfig.optionsListSelector);
   }
 
+  /** Builds `_finalEndpoint` from `endpoint` + `dynamicParams`. */
+  private rebuildEndpoint(): void {
+    if (!this.rawEndpoint) {
+      return;
+    }
 
+    this._finalEndpoint = rebuildEndpointUrl(this.rawEndpoint, this.endpointDynamicParams);
 
-  /**
-   * Set the disabled state of the component
-   * @param isDisabled
-   */
-  setDisabledState(isDisabled: boolean): void {
-    this.isDisabled = isDisabled
-    this.cdr.markForCheck()
+    if (this.type === 'searchable' && (this.loadOnInit || this.loadOpen || this.isDropdownOpen)) {
+      this.loadData();
+    }
   }
 }