tailjng 0.1.6 → 0.1.7

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

@@ -1,677 +1,618 @@
-
-import { Component, Input, Output, EventEmitter, ElementRef, ViewChild, OnDestroy, ChangeDetectorRef, AfterViewInit, OnInit, SimpleChanges, OnChanges, Optional, } from "@angular/core"
-import { FormsModule, 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 { debounceTime, distinctUntilChanged, Subject, Subscription } from "rxjs"
-import { JGenericCrudService, JIconsService } from "tailjng"
-
+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 {
+  DropdownOption,
+  DropdownSelectDefaultFilters,
+  DropdownSelectDynamicParams,
+  DropdownSelectType,
+  DropdownSortOrder,
+} from './dropdown-select.types';
+import {
+  DROPDOWN_PANEL_DEFAULTS,
+  filterOptionsBySearch,
+  mapObjectOptions,
+  mapPrimitiveOptions,
+  positionDropdownPanel,
+  rebuildEndpointUrl,
+  resetDropdownPanelStyles,
+  resolveOptionLabel,
+} from './dropdown-select.util';
+
+export type {
+  DropdownOption,
+  DropdownPanelPosition,
+  DropdownPanelPositionConfig,
+  DropdownSelectDefaultFilters,
+  DropdownSelectDynamicParams,
+  DropdownSelectType,
+  DropdownSortOrder,
+} from './dropdown-select.types';
+export {
+  DROPDOWN_PANEL_DEFAULTS,
+  filterOptionsBySearch,
+  getNestedValue,
+  mapObjectOptions,
+  mapPrimitiveOptions,
+  positionDropdownPanel,
+  rebuildEndpointUrl,
+  resetDropdownPanelStyles,
+  resolveOptionLabel,
+} from './dropdown-select.util';
+
+/**
+ * Dropdown select with static options or searchable CRUD endpoint.
+ * Panel uses fixed viewport positioning (dialogs, tables, filter popovers).
+ *
+ * Install: `npx tailjng add select-dropdown`
+ *
+ * ```html
+ * <JDropdownSelect
+ *   [(ngModel)]="demoSelect"
+ *   [options]="selectOptions"
+ *   optionLabel="text"
+ *   optionValue="value"
+ *   [showClear]="true"
+ * />
+ * ```
+ *
+ * Icons in template: `[icon]="Icons.ChevronDown"` (see `readonly Icons = Icons`).
+ */
 @Component({
-  selector: "JDropdownSelect",
-  imports: [LucideAngularModule, CommonModule, FormsModule, ReactiveFormsModule],
-  templateUrl: "./dropdown-select.component.html",
-  styleUrl: "./dropdown-select.component.css",
+  selector: 'JDropdownSelect',
+  imports: [JIconComponent, CommonModule, FormsModule, ReactiveFormsModule],
+  templateUrl: './dropdown-select.component.html',
+  styleUrl: './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: JDropdownSelectComponent,
+      useExisting: forwardRef(() => JDropdownSelectComponent),
       multi: true,
     },
   ],
 })
-export class JDropdownSelectComponent implements ControlValueAccessor, AfterViewInit, OnDestroy, OnInit, OnChanges {
+export class JDropdownSelectComponent
+  implements ControlValueAccessor, OnInit, AfterViewInit, OnChanges, OnDestroy
+{
+  // Project Icons registry — template usage: Icons.ChevronDown, Icons.Loader2, …
+  readonly Icons = Icons;
+
+  // =====================================================
+  // Inputs / outputs
+  // =====================================================
+
+  // `dropdown` = static options · `searchable` = CRUD endpoint + debounced search
+  @Input() type: DropdownSelectType = 'dropdown';
+
+  // Panel heading above the option list
+  @Input() title = 'Seleccionar';
+
+  // Trigger label when nothing is selected
+  @Input() placeholder = 'Seleccione una opción';
+
+  // Static options (`string[]` or object array with optionLabel / optionValue)
+  @Input() options: unknown[] = [];
+
+  // Property name(s) used to build option text (supports dot paths)
+  @Input() optionLabel: string | string[] = 'text';
 
-  @Input() type: "dropdown" | "searchable" = "dropdown";
+  // Property name used as the option value
+  @Input() optionValue = 'value';
 
-  @Input() title = "Seleccionar";
-  @Input() placeholder = "Seleccione una opción";
+  // Separator when `optionLabel` is an array of keys
+  @Input() labelSeparator = ' ';
 
-  @Input() options: any[] = [];
-  @Input() optionLabel: string | string[] = "text";
-  @Input() optionValue = "value";
-  @Input() labelSeparator = " ";
+  // Prepends a synthetic “TODOS” option with `value: null` (searchable mode)
   @Input() showAllOption = false;
 
-  @Input() isDisabled = false
+  @Input() isDisabled = false;
+
+  // Shows clear (X) on the trigger when a value is selected
   @Input() showClear = false;
+
+  // Loading state on trigger or panel (API / parent control)
   @Input() isLoading = false;
 
+  // Searchable: fetch on init
   @Input() loadOnInit = false;
+
+  // Searchable: fetch when the panel opens
   @Input() loadOpen = false;
 
-  @Input() defaultFilters: { [key: string]: any } = {};
-  @Input() searchFields: any[] = [];
-  @Input() sort: "ASC" | "DESC" = "ASC";
-  @Input() limit: number = 1000;
+  // Searchable: default `filter[key]` query params
+  @Input() defaultFilters: DropdownSelectDefaultFilters = {};
 
-  @Input() isSearch = true;
-  @Input() isFilterSelect = false;
+  // Searchable: extra fields included in API search
+  @Input() searchFields: string[] = [];
 
-  @Input() classes: string = '';
-  @Input() ngClasses: { [key: string]: boolean } = {};
+  // Searchable: sort order sent to the API
+  @Input() sort: DropdownSortOrder = 'ASC';
 
-  @Output() selectionChange = new EventEmitter<any>();
-  @Output() fullData = new EventEmitter<any[]>();
+  // Searchable: max records per request
+  @Input() limit = 1000;
 
-  @ViewChild("selectButton") selectButton!: ElementRef;
-
-  // Selectors
-  isColumnSelectorOpen = false
-  selectedValue: any = null
-  selectedLabel = ""
-  internalOptions: Array<{ value: any; text: string }> = [];
+  // Searchable panel: show inline search input
+  @Input() isSearch = true;
 
-  // Search functionality
-  searchTerm = "";
-  private readonly searchSubject = new Subject<string>();
-  private searchSubscription?: Subscription;
-  filteredOptions: Array<{ value: any; text: string; original?: any }> = [];
+  /** @deprecated Kept for backward compatibility; panel positioning no longer uses this flag. */
+  @Input() isFilterSelect = false;
 
-  // Dropdown positioning
-  dropdownTop = 0;
-  dropdownLeft = 0;
-  dropdownWidth = 0;
+  // Extra Tailwind classes on trigger and panel shell
+  @Input() classes = '';
 
-  // Implement writeValue, registerOnChange, registerOnTouched
-  private onChange: any = () => { };
-  private onTouched: any = () => { };
+  // Extra conditional classes on the trigger button
+  @Input() ngClasses: Record<string, boolean> = {};
 
-  // Will be used to close the dropdown when clicking outside
-  private clickOutsideListener: any;
+  /** Emits the selected raw value or `null` when cleared. */
+  @Output() selectionChange = new EventEmitter<unknown>();
 
-  // Assigned dynamically to the endpoint
-  private _rawEndpoint = "";
-  _finalEndpoint = "";
+  /** Searchable: emits the full API result array after each load. */
+  @Output() fullData = new EventEmitter<unknown[]>();
 
+  /** CRUD endpoint; supports `{param}` placeholders resolved via `dynamicParams`. */
   @Input() set endpoint(value: string) {
-    this._rawEndpoint = value
-    this.rebuildEndpoint()
+    this.rawEndpoint = value;
+    this.rebuildEndpoint();
   }
 
   get endpoint(): string {
-    return this._rawEndpoint
+    return this.rawEndpoint;
   }
 
-  mainEndpoint!: string
-  private _dynamicParams: { [key: string]: any } = {}
-  @Input() set dynamicParams(value: { [key: string]: any }) {
-    this._dynamicParams = value
-    this.rebuildEndpoint()
-  }
-  get dynamicParams(): { [key: string]: any } {
-    return this._dynamicParams
+  /** Values substituted into `{param}` segments of `endpoint`. */
+  @Input() set dynamicParams(value: DropdownSelectDynamicParams) {
+    this.endpointDynamicParams = value;
+    this.rebuildEndpoint();
   }
 
-  private rebuildEndpoint() {
-    if (!this._rawEndpoint) return
-    this._finalEndpoint = this._rawEndpoint.replace(/\{([^}]+)\}/g, (_, key) => {
-      return this._dynamicParams?.[key] ?? ""
-    })
+  get dynamicParams(): DropdownSelectDynamicParams {
+    return this.endpointDynamicParams;
   }
 
+  // =====================================================
+  // View / state
+  // =====================================================
+
+  @ViewChild('selectButton') selectButton!: ElementRef<HTMLElement>;
+  @ViewChild('dropdownPanel') dropdownPanel?: ElementRef<HTMLElement>;
+
+  isColumnSelectorOpen = false;
+  selectedValue: unknown = null;
+  selectedLabel = '';
+  internalOptions: DropdownOption[] = [];
+  filteredOptions: DropdownOption[] = [];
+
+  searchTerm = '';
+  dropdownWidth = 0;
+
+  mainEndpoint = '';
+
+  /** Resolved endpoint after `{param}` substitution (used by searchable mode). */
+  _finalEndpoint = '';
+
+  private rawEndpoint = '';
+  private endpointDynamicParams: DropdownSelectDynamicParams = {};
+
+  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.isColumnSelectorOpen) {
+      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,
-  ) { }
+  ) {}
 
-  ngOnInit() {
-    this.mainEndpoint = this.endpoint.split("/")[0] ?? this.endpoint
+  // =====================================================
+  // Lifecycle
+  // =====================================================
 
-    // Config the search input
-    this.searchSubscription = this.searchSubject.pipe(debounceTime(1000), distinctUntilChanged()).subscribe(() => {
-      if (this.type === "searchable") {
-        this.loadData()
-      }
-    })
+  ngOnInit(): void {
+    this.mainEndpoint = this.endpoint.split('/')[0] ?? this.endpoint;
 
-    // Charge data on init if loadOnInit is true
-    if (this.loadOnInit && this.type === "searchable") {
-      this.loadData()
+    this.searchSubscription = this.searchSubject
+      .pipe(debounceTime(1000), distinctUntilChanged())
+      .subscribe(() => {
+        if (this.type === 'searchable') {
+          this.loadData();
+        }
+      });
+
+    if (this.loadOnInit && this.type === 'searchable') {
+      this.loadData();
     }
 
-    // Assigned the button text if not provided
-    this.updateSelectedLabel()
+    this.updateSelectedLabel();
   }
 
-  ngAfterViewInit() {
-    this.setupClickOutsideListener()
-    setTimeout(() => {
-      this.processOptions()
-    })
+  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)
-    }
-    if (this.searchSubscription) {
-      this.searchSubscription.unsubscribe()
+      document.removeEventListener('click', this.clickOutsideListener);
     }
+
+    this.searchSubscription?.unsubscribe();
   }
 
-  // ======================================================
-  // Methods for processing options and selection
-  // ======================================================
+  // =====================================================
+  // ControlValueAccessor
+  // =====================================================
 
   /**
-   * Method to process dropdown options
+   * Writes the value from Angular forms into the component.
+   * @param value Selected option value or `null`.
    */
-  processOptions() {
-    this.internalOptions = []
-
-    if (this.options && this.options.length > 0 && typeof this.options[0] !== "object") {
-      this.internalOptions = this.options.map((option) => ({
-        value: option,
-        text: option.toString(),
-      }))
-    } else if (this.options && this.options.length > 0) {
-      this.internalOptions = this.options.map((option) => {
-        const text = Array.isArray(this.optionLabel)
-          ? this.optionLabel.map((k) => this.getNestedValue(option, k)).join(" ")
-          : this.getNestedValue(option, this.optionLabel)
-        return {
-          value: option[this.optionValue],
-          text,
-          original: option,
-        }
-      })
+  writeValue(value: unknown): void {
+    this.selectedValue = value;
+
+    if (this.internalOptions.length > 0) {
+      this.updateSelectedLabel();
+    } else {
+      setTimeout(() => {
+        this.updateSelectedLabel();
+        this.cdr.detectChanges();
+      });
     }
 
-    this.filteredOptions = [...this.internalOptions]
-    this.updateSelectedLabel()
-    this.cdr.detectChanges()
+    this.cdr.markForCheck();
   }
 
-
-
   /**
-   * Selected option from the dropdown
-   * @param option 
+   * Registers the change callback for Angular forms.
+   * @param fn Callback invoked when the selection changes.
    */
-  selectOption(option: { value: any; text: string; original?: any }) {
-    this.selectedValue = option.value
-    this.selectedLabel = option.text
-    this.onChange(this.selectedValue)
-    this.selectionChange.emit(option.original ?? option.value)
-    this.isColumnSelectorOpen = false
+  registerOnChange(fn: (value: unknown) => void): void {
+    this.onChange = fn;
   }
 
+  /**
+   * Registers the touched callback for Angular forms.
+   * @param fn Callback invoked when the control is touched.
+   */
+  registerOnTouched(fn: () => void): void {
+    this.onTouched = fn;
+  }
 
+  // =====================================================
+  // Options
+  // =====================================================
 
   /**
-   * Clean the selection
-   * @param event 
+   * Normalizes `options` into internal `{ value, text }` entries.
    */
-  clearSelection(event: Event) {
-    event.stopPropagation()
-    this.writeValue(null)
-    this.onChange(null)
-    this.selectionChange.emit(null)
-  }
+  processOptions(): void {
+    this.internalOptions = [];
+
+    if (this.options?.length > 0 && typeof this.options[0] !== 'object') {
+      this.internalOptions = mapPrimitiveOptions(this.options);
+    } else if (this.options?.length > 0) {
+      this.internalOptions = mapObjectOptions(
+        this.options as Record<string, unknown>[],
+        this.optionLabel,
+        this.optionValue,
+        this.labelSeparator,
+      );
+    }
 
+    this.filteredOptions = [...this.internalOptions];
+    this.updateSelectedLabel();
+    this.cdr.detectChanges();
+  }
 
+  /**
+   * Selects an option, updates the form model and closes the panel.
+   * @param option Normalized option from the panel list.
+   */
+  selectOption(option: DropdownOption): void {
+    this.selectedValue = option.value;
+    this.selectedLabel = option.text;
+    this.onChange(this.selectedValue);
+    this.selectionChange.emit(option.original ?? option.value);
+    this.closePanel();
+  }
 
   /**
-   * Clean the search term
+   * Clears the current selection without opening the panel.
+   * @param event Click event (stopped to avoid toggling the panel).
    */
-  clearSearchTerm(): void {
-    this.searchTerm = ""
-    this.onSearchInput()
+  clearSelection(event: Event): void {
+    event.stopPropagation();
+    this.writeValue(null);
+    this.onChange(null);
+    this.selectionChange.emit(null);
   }
 
   /**
-   * Update the selected label based on the current selection
-   * @returns 
+   * Syncs `selectedLabel` with `selectedValue` and `internalOptions`.
    */
-  updateSelectedLabel() {
+  updateSelectedLabel(): void {
     if (this.selectedValue === null) {
-      this.selectedLabel = this.placeholder
-      return
+      this.selectedLabel = this.placeholder;
+      return;
     }
 
-    const selectedOption = this.internalOptions.find((opt) => opt.value === this.selectedValue)
-    this.selectedLabel = selectedOption ? selectedOption.text : this.placeholder
+    const selectedOption = this.internalOptions.find((option) => option.value === this.selectedValue);
+    this.selectedLabel = selectedOption ? selectedOption.text : this.placeholder;
   }
 
   /**
-   * Get nested value from an object
-   * @param obj 
-   * @param path 
-   * @returns 
+   * Class map for the trigger button (disabled / loading + `ngClasses`).
+   * @returns Conditional classes merged with consumer `ngClasses`.
    */
-  getNestedValue(obj: any, path: string): any {
-    return path.split(".").reduce((acc, part) => acc && acc[part], obj) ?? ""
+  getButtonNgClass(): Record<string, boolean> {
+    return {
+      'opacity-50 cursor-not-allowed pointer-events-none': this.isDisabled || this.isLoading,
+      ...this.ngClasses,
+    };
   }
 
-  // ======================================================
-  // Search input service
-  // ======================================================
+  // =====================================================
+  // Search / API
+  // =====================================================
 
   /**
-   * Load data from the service
-   * @returns 
+   * Loads options from the CRUD API (searchable mode).
    */
-  loadData() {
-    if (!this.endpoint || !this.genericService) return
+  loadData(): void {
+    if (!this.endpoint || !this.genericService) {
+      return;
+    }
+
+    this.isLoading = true;
 
-    this.isLoading = true
-    const params: any = {}
-    params["sortOrder"] = this.sort
-    params["limit"] = this.limit
+    const params: Record<string, unknown> = {
+      sortOrder: this.sort,
+      limit: this.limit,
+    };
 
-    // Apply default filters sent from the parent
     Object.keys(this.defaultFilters).forEach((key) => {
-      params[`filter[${key}]`] = this.defaultFilters[key]
-    })
-
-    // Add search term to the parameters
-    if (this.searchTerm && this.searchTerm.trim() !== "") {
-      params["search"] = this.searchTerm
-      // Apply additional search filters
-      const optionLabelsArray = Array.isArray(this.optionLabel) ? this.optionLabel : [this.optionLabel]
-      const allSearchFields = [...optionLabelsArray, ...this.searchFields]
-      params["searchFields"] = allSearchFields
+      params[`filter[${key}]`] = this.defaultFilters[key];
+    });
+
+    if (this.searchTerm.trim()) {
+      params['search'] = this.searchTerm;
+      const optionLabels = Array.isArray(this.optionLabel) ? this.optionLabel : [this.optionLabel];
+      params['searchFields'] = [...optionLabels, ...this.searchFields];
     }
 
-    this.genericService.findAll<any>({ endpoint: this._finalEndpoint, params }).subscribe({
+    this.genericService.findAll<Record<string, unknown>>({
+      endpoint: this._finalEndpoint,
+      params,
+    }).subscribe({
       next: (response) => {
-        // Process the response data
-        const data = response.data[this.mainEndpoint] || []
+        const data = (response.data[this.mainEndpoint] as Record<string, unknown>[]) || [];
         this.options = data;
 
-        // Add the "ALL" option if required
         if (this.showAllOption) {
-
-          this.internalOptions = [{
-            value: null,  // Null value for the "ALL" option
-            text: 'TODOS',
-          }];
-
-          // Process the options for the dropdown
+          this.internalOptions = [{ value: null, text: 'TODOS' }];
           this.internalOptions.push(
-            ...this.options.map((option) => ({
-              value: option[this.optionValue],
-              text: this.resolveLabel(option),
-              original: option,
-            }))
+            ...mapObjectOptions(data, this.optionLabel, this.optionValue, this.labelSeparator),
           );
-
         } else {
+          this.internalOptions = mapObjectOptions(
+            data,
+            this.optionLabel,
+            this.optionValue,
+            this.labelSeparator,
+          );
+        }
 
-          // Process the options for the dropdown
-          this.internalOptions = this.options.map((option) => ({
-            value: option[this.optionValue],
-            text: this.resolveLabel(option),
-            original: option,
-          }))
+        this.filteredOptions = [...this.internalOptions];
+        this.fullData.emit(this.options);
+        this.isLoading = false;
+        this.updateSelectedLabel();
 
+        if (this.isColumnSelectorOpen) {
+          this.updateDropdownPosition();
         }
 
-        this.filteredOptions = [...this.internalOptions]
-        this.fullData.emit(this.options)
-        this.isLoading = false
-        this.updateSelectedLabel()
-        this.cdr.detectChanges()
+        this.cdr.detectChanges();
       },
       error: (error) => {
-        console.error("Error fetching data:", error)
-        this.isLoading = false
-        this.cdr.detectChanges()
+        console.error('Error fetching data:', error);
+        this.isLoading = false;
+        this.cdr.detectChanges();
       },
-    })
-  }
-
-
-
-  /**
-   * Search input handler
-   */
-  onSearchInput() {
-    if (this.type === "searchable") {
-      // For searchable type, send the search term to the service
-      this.searchSubject.next(this.searchTerm)
-    } else {
-      // For other types, filter locally
-      this.filterOptions()
-    }
+    });
   }
 
-
-
   /**
-   * Filter options locally
-   * @returns 
+   * Handles panel search input — debounced API call or local filter.
    */
-  filterOptions() {
-    if (!this.searchTerm || this.searchTerm.trim() === "") {
-      this.filteredOptions = [...this.internalOptions]
-      return
+  onSearchInput(): void {
+    if (this.type === 'searchable') {
+      this.searchSubject.next(this.searchTerm);
+      return;
     }
 
-    const searchTermLower = this.searchTerm.toLowerCase()
-    this.filteredOptions = this.internalOptions.filter((option) => option.text.toLowerCase().includes(searchTermLower))
+    this.filteredOptions = filterOptionsBySearch(this.internalOptions, this.searchTerm);
   }
 
+  /** Resets the panel search field and re-runs {@link onSearchInput}. */
+  clearSearchTerm(): void {
+    this.searchTerm = '';
+    this.onSearchInput();
+  }
 
+  // =====================================================
+  // Panel open / position
+  // =====================================================
 
   /**
-   * Filter options locally
-   * @param option 
-   * @returns 
+   * Opens or closes the option panel.
+   * Searchable mode may trigger {@link loadData} on first open.
    */
-  resolveLabel(option: any): string {
-    if (Array.isArray(this.optionLabel)) {
-      return this.optionLabel
-        .map((key) => this.getNestedValue(option, key))
-        .filter(Boolean)
-        .join(this.labelSeparator)
+  toggleColumnSelector(): void {
+    if (this.isDisabled) {
+      return;
     }
-    return this.getNestedValue(option, this.optionLabel)
-  }
 
-  // ======================================================
-  // Elements
-  // ======================================================
+    this.isColumnSelectorOpen = !this.isColumnSelectorOpen;
 
-  /**
-   * Open or close the dropdown
-   * @returns 
-   */
-  toggleColumnSelector() {
-    if (this.isDisabled) return
-
-    this.isColumnSelectorOpen = !this.isColumnSelectorOpen
     if (this.isColumnSelectorOpen) {
-      this.onTouched()
-      this.updateDropdownPosition()
+      this.onTouched();
+      this.addRepositionListeners();
+      this.updateDropdownPosition();
 
-      // Load data if searchable and loadOpen is true
-      if (this.type === "searchable" && this.loadOpen) {
-        this.loadData()
+      if (this.type === 'searchable' && this.loadOpen) {
+        this.loadData();
       }
 
-      if (this.type === "searchable" && !this.loadOnInit && this.shouldTriggerLoad()) {
-        this.loadData()
+      if (this.type === 'searchable' && !this.loadOnInit && this.shouldTriggerLoad()) {
+        this.loadData();
       }
-    }
-  }
-
-
 
-  /**
-   * Detect clicks outside the dropdown to close it
-   */
-  setupClickOutsideListener() {
-    this.clickOutsideListener = (event: MouseEvent) => {
-      const clickedElement = event.target as HTMLElement
-      const isOutsideDropdown = !this.elementRef.nativeElement.contains(clickedElement)
-      if (this.isColumnSelectorOpen && isOutsideDropdown) {
-        this.isColumnSelectorOpen = false
-        this.cdr.detectChanges()
-      }
+      return;
     }
-    document.addEventListener("click", this.clickOutsideListener)
-  }
-
 
+    this.closePanel(false);
+  }
 
   /**
-   * Update the dropdown position based on the button
+   * Positions the floating panel with fixed viewport coordinates
+   * (flip above/below, clamp to window — see {@link positionDropdownPanel}).
    */
-  updateDropdownPosition() {
+  updateDropdownPosition(): void {
     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
+      const button = this.selectButton?.nativeElement;
+      if (!button) {
+        return;
       }
 
-      // 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
-      }
+      const buttonRect = button.getBoundingClientRect();
+      this.dropdownWidth = buttonRect.width;
+      this.cdr.detectChanges();
 
-      // Position directly below the button by default
-      this.dropdownTop = buttonRect.bottom - offsetTop
-      this.dropdownLeft = buttonRect.left - offsetLeft
-      this.dropdownWidth = buttonRect.width
-      this.cdr.detectChanges()
+      requestAnimationFrame(() => {
+        const panel = this.dropdownPanel?.nativeElement;
+        if (!panel) {
+          return;
+        }
 
-      // 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)
-    })
+        positionDropdownPanel(panel, buttonRect, this.panelPositionConfig);
+        this.cdr.detectChanges();
+      });
+    });
   }
 
-  /**
-   * Helper method to find the offset parent for absolute positioning
-   * @param element 
-   * @returns 
-   */
-  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
-      }
-      parent = parent.parentElement
-    }
-    return document.body // Default to body if no positioned parent found
-  }
+  /** 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.isColumnSelectorOpen && isOutsideDropdown) {
+        this.closePanel();
+      }
+    };
 
+    document.addEventListener('click', this.clickOutsideListener);
+  }
 
-  /**
-   * Read the selected value
-   * @param value 
-   */
-  writeValue(value: any): void {
-    this.selectedValue = value
+  /** Closes the panel and clears reposition listeners / dynamic panel styles. */
+  private closePanel(detectChanges = true): void {
+    this.isColumnSelectorOpen = false;
+    this.removeRepositionListeners();
+    this.resetDropdownPanelStyles();
 
-    // If there are already options available, update the label
-    if (this.internalOptions.length > 0) {
-      this.updateSelectedLabel()
-    } else {
-      // Wait for options to load and then update the label
-      setTimeout(() => {
-        this.updateSelectedLabel()
-        this.cdr.detectChanges()
-      })
+    if (detectChanges) {
+      this.cdr.detectChanges();
     }
-    this.cdr.markForCheck()
   }
 
-  // ================================================
-  // Register changes
-  // ================================================
-
-  /**
-   * 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;
+    }
 
-
-  /**
-   * Load searchable elements when needed
-   * @returns 
-   */
-  private shouldTriggerLoad(): boolean {
-    const isSearchActive = this.searchTerm && this.searchTerm.trim() !== ""
-    const isInitialState = this.selectedValue === null
-    return isSearchActive || isInitialState
+    this._finalEndpoint = rebuildEndpointUrl(this.rawEndpoint, this.endpointDynamicParams);
   }
 
-  /**
-   * Get the ngClass for the button based on disabled and loading state
-   * @returns 
-   */
-  getButtonNgClass(): { [key: string]: boolean } {
-    return {
-      'opacity-50 cursor-not-allowed pointer-events-none': this.isDisabled || this.isLoading,
-      ...this.ngClasses,
-    };
+  /** Whether searchable mode should fetch on first panel open. */
+  private shouldTriggerLoad(): boolean {
+    const isSearchActive = this.searchTerm.trim().length > 0;
+    const isInitialState = this.selectedValue === null;
+    return isSearchActive || isInitialState;
   }
-}
+}