ngx-com 0.0.1 → 0.0.4

package/types/ngx-com-components-dropdown.d.ts

@@ -0,0 +1,938 @@
+import * as i0 from '@angular/core';
+import { TemplateRef, Signal, InputSignal, OutputEmitterRef, WritableSignal, OnInit } from '@angular/core';
+import { ControlValueAccessor, NgControl } from '@angular/forms';
+import { FormFieldControl, ErrorStateMatcher, FormFieldAppearance } from 'ngx-com/components/form-field';
+import { VariantProps } from 'class-variance-authority';
+import { CdkVirtualScrollViewport } from '@angular/cdk/scrolling';
+
+/**
+ * Context provided to the custom option template.
+ * @template T The type of the option value.
+ */
+interface ComDropdownOptionContext<T> {
+    /** The option value (available as implicit $implicit). */
+    $implicit: T;
+    /** The index of this option in the filtered list. */
+    index: number;
+    /** Whether this option is currently selected. */
+    selected: boolean;
+    /** Whether this option is currently active (focused via keyboard). */
+    active: boolean;
+    /** Whether this option is disabled. */
+    disabled: boolean;
+}
+/**
+ * Context provided to the custom selected value template.
+ * @template T The type of the option value.
+ */
+interface ComDropdownSelectedContext<T> {
+    /** The selected value(s) (available as implicit $implicit). */
+    $implicit: T | T[] | null;
+    /** The placeholder text when no value is selected. */
+    placeholder: string;
+    /** Whether multiple selection is enabled. */
+    multiple: boolean;
+}
+/**
+ * Context provided to the custom empty state template.
+ */
+interface ComDropdownEmptyContext {
+    /** The current search query (available as implicit $implicit). */
+    $implicit: string;
+}
+/**
+ * Context provided to the custom group header template.
+ */
+interface ComDropdownGroupContext {
+    /** The group key/label (available as implicit $implicit). */
+    $implicit: string;
+    /** Whether the group is expanded. */
+    expanded: boolean;
+    /** The number of options in this group. */
+    count: number;
+}
+/**
+ * Context provided to the custom tag template (multi-select mode).
+ * @template T The type of the option value.
+ */
+interface ComDropdownTagContext<T> {
+    /** The tag value (available as implicit $implicit). */
+    $implicit: T;
+    /** The index of this tag. */
+    index: number;
+    /** Function to remove this tag. */
+    remove: () => void;
+}
+/**
+ * Represents a grouped collection of options.
+ * @template T The type of the option value.
+ */
+interface ComDropdownGroup$1<T> {
+    /** The group key/label. */
+    key: string;
+    /** The options belonging to this group. */
+    options: T[];
+    /** Whether the group is expanded (for collapsible groups). */
+    expanded: boolean;
+}
+/**
+ * Internal representation of a processed option.
+ * @template T The type of the option value.
+ */
+interface ComDropdownProcessedOption<T> {
+    /** The original option value. */
+    value: T;
+    /** The display text for this option. */
+    displayText: string;
+    /** Whether this option is disabled. */
+    disabled: boolean;
+    /** The group this option belongs to (if grouped). */
+    group?: string;
+    /** Unique identifier for tracking. */
+    id: string;
+}
+/**
+ * Configuration for dropdown positioning.
+ */
+interface ComDropdownPosition {
+    /** The origin X position. */
+    originX: 'start' | 'center' | 'end';
+    /** The origin Y position. */
+    originY: 'top' | 'center' | 'bottom';
+    /** The overlay X position. */
+    overlayX: 'start' | 'center' | 'end';
+    /** The overlay Y position. */
+    overlayY: 'top' | 'center' | 'bottom';
+    /** Offset along the X axis. */
+    offsetX?: number;
+    /** Offset along the Y axis. */
+    offsetY?: number;
+}
+/**
+ * Panel width configuration.
+ */
+type ComDropdownPanelWidth = 'trigger' | 'auto' | string;
+/**
+ * Default compare function for primitive values.
+ * @param a First value.
+ * @param b Second value.
+ * @returns Whether the values are equal.
+ */
+declare function defaultCompareWith<T>(a: T, b: T): boolean;
+/**
+ * Default display function for converting values to strings.
+ * @param value The value to display.
+ * @returns The string representation.
+ */
+declare function defaultDisplayWith<T>(value: T): string;
+/**
+ * Default filter function for search.
+ * @param option The option to test.
+ * @param query The search query.
+ * @param displayWith The display function to get the searchable text.
+ * @returns Whether the option matches the query.
+ */
+declare function defaultFilterWith<T>(option: T, query: string, displayWith: (value: T) => string): boolean;
+/**
+ * Generates a unique ID for dropdown options.
+ * @param prefix Optional prefix for the ID.
+ * @returns A unique ID string.
+ */
+declare function generateDropdownId(prefix?: string): string;
+
+/**
+ * Directive to mark a template as the custom option template.
+ *
+ * @example
+ * ```html
+ * <com-dropdown [options]="users()">
+ *   <ng-template comDropdownOption let-user let-selected="selected">
+ *     <div class="flex items-center gap-2">
+ *       <span>{{ user.name }}</span>
+ *       @if (selected) {
+ *         <svg class="h-4 w-4"><!-- check --></svg>
+ *       }
+ *     </div>
+ *   </ng-template>
+ * </com-dropdown>
+ * ```
+ */
+declare class ComDropdownOptionTpl<T> {
+    /** Reference to the template. */
+    readonly templateRef: TemplateRef<ComDropdownOptionContext<T>>;
+    /**
+     * Static type guard for template type checking.
+     * Enables type-safe access to context properties in templates.
+     */
+    static ngTemplateContextGuard<T>(_dir: ComDropdownOptionTpl<T>, ctx: unknown): ctx is ComDropdownOptionContext<T>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ComDropdownOptionTpl<any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<ComDropdownOptionTpl<any>, "ng-template[comDropdownOption]", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Directive to mark a template as the custom selected value template.
+ *
+ * @example
+ * ```html
+ * <com-dropdown [options]="users()">
+ *   <ng-template comDropdownSelected let-user>
+ *     @if (user) {
+ *       <div class="flex items-center gap-2">
+ *         <img [src]="user.avatar" class="h-5 w-5 rounded-full" />
+ *         {{ user.name }}
+ *       </div>
+ *     } @else {
+ *       <span class="text-input-placeholder">Select user...</span>
+ *     }
+ *   </ng-template>
+ * </com-dropdown>
+ * ```
+ */
+declare class ComDropdownSelectedTpl<T> {
+    /** Reference to the template. */
+    readonly templateRef: TemplateRef<ComDropdownSelectedContext<T>>;
+    /**
+     * Static type guard for template type checking.
+     * Enables type-safe access to context properties in templates.
+     */
+    static ngTemplateContextGuard<T>(_dir: ComDropdownSelectedTpl<T>, ctx: unknown): ctx is ComDropdownSelectedContext<T>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ComDropdownSelectedTpl<any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<ComDropdownSelectedTpl<any>, "ng-template[comDropdownSelected]", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Directive to mark a template as the custom empty state template.
+ *
+ * @example
+ * ```html
+ * <com-dropdown [options]="users()" [searchable]="true">
+ *   <ng-template comDropdownEmpty let-query>
+ *     <div class="flex flex-col items-center gap-2 py-6">
+ *       <svg class="h-8 w-8 text-muted-foreground"><!-- search icon --></svg>
+ *       <span>No results for "{{ query }}"</span>
+ *     </div>
+ *   </ng-template>
+ * </com-dropdown>
+ * ```
+ */
+declare class ComDropdownEmptyTpl {
+    /** Reference to the template. */
+    readonly templateRef: TemplateRef<ComDropdownEmptyContext>;
+    /**
+     * Static type guard for template type checking.
+     * Enables type-safe access to context properties in templates.
+     */
+    static ngTemplateContextGuard(_dir: ComDropdownEmptyTpl, ctx: unknown): ctx is ComDropdownEmptyContext;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ComDropdownEmptyTpl, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<ComDropdownEmptyTpl, "ng-template[comDropdownEmpty]", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Directive to mark a template as the custom group header template.
+ *
+ * @example
+ * ```html
+ * <com-dropdown [options]="users()" [groupBy]="groupByDepartment">
+ *   <ng-template comDropdownGroup let-group let-count="count">
+ *     <div class="flex items-center justify-between">
+ *       <span class="font-semibold">{{ group }}</span>
+ *       <span class="text-xs text-muted-foreground">({{ count }})</span>
+ *     </div>
+ *   </ng-template>
+ * </com-dropdown>
+ * ```
+ */
+declare class ComDropdownGroupTpl {
+    /** Reference to the template. */
+    readonly templateRef: TemplateRef<ComDropdownGroupContext>;
+    /**
+     * Static type guard for template type checking.
+     * Enables type-safe access to context properties in templates.
+     */
+    static ngTemplateContextGuard(_dir: ComDropdownGroupTpl, ctx: unknown): ctx is ComDropdownGroupContext;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ComDropdownGroupTpl, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<ComDropdownGroupTpl, "ng-template[comDropdownGroup]", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Directive to mark a template as the custom tag template (multi-select mode).
+ *
+ * @example
+ * ```html
+ * <com-dropdown [options]="users()" [multiple]="true">
+ *   <ng-template comDropdownTag let-user let-remove="remove">
+ *     <div class="flex items-center gap-1 rounded bg-primary-subtle px-2 py-0.5 text-primary-subtle-foreground">
+ *       <img [src]="user.avatar" class="h-4 w-4 rounded-full" />
+ *       <span>{{ user.name }}</span>
+ *       <button type="button" (click)="remove()" class="ml-1">
+ *         <svg class="h-3 w-3"><!-- x icon --></svg>
+ *       </button>
+ *     </div>
+ *   </ng-template>
+ * </com-dropdown>
+ * ```
+ */
+declare class ComDropdownTagTpl<T> {
+    /** Reference to the template. */
+    readonly templateRef: TemplateRef<ComDropdownTagContext<T>>;
+    /**
+     * Static type guard for template type checking.
+     * Enables type-safe access to context properties in templates.
+     */
+    static ngTemplateContextGuard<T>(_dir: ComDropdownTagTpl<T>, ctx: unknown): ctx is ComDropdownTagContext<T>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ComDropdownTagTpl<any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<ComDropdownTagTpl<any>, "ng-template[comDropdownTag]", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Variant type for dropdown trigger appearance.
+ */
+type DropdownVariant = 'default' | 'outline' | 'ghost' | 'filled' | 'naked';
+/**
+ * Size type for dropdown components.
+ */
+type DropdownSize = 'sm' | 'default' | 'lg';
+/**
+ * State type for validation states.
+ */
+type DropdownState = 'default' | 'error' | 'success';
+/**
+ * Option state for styling.
+ */
+type OptionState = 'default' | 'active' | 'selected' | 'selected-active' | 'disabled';
+/**
+ * Tag variant type.
+ */
+type TagVariant = 'default' | 'primary';
+/**
+ * CVA variants for the dropdown trigger button.
+ * Uses semantic theme tokens for consistent cross-theme styling.
+ *
+ * @tokens `--color-input-background`, `--color-input-foreground`, `--color-input-border`,
+ *         `--color-input-placeholder`, `--color-ring`, `--color-muted`, `--color-muted-hover`,
+ *         `--color-warn`, `--color-success`, `--color-primary`, `--color-border`, `--radius-input`
+ */
+declare const dropdownTriggerVariants: (props?: {
+    variant?: DropdownVariant;
+    size?: DropdownSize;
+    state?: DropdownState;
+    open?: boolean;
+}) => string;
+type DropdownTriggerVariants = VariantProps<typeof dropdownTriggerVariants>;
+/**
+ * CVA variants for the dropdown panel (overlay).
+ *
+ * @tokens `--color-popover`, `--color-popover-foreground`, `--color-border-subtle`, `--radius-overlay`
+ */
+declare const dropdownPanelVariants: (props?: {
+    size?: DropdownSize;
+}) => string;
+type DropdownPanelVariants = VariantProps<typeof dropdownPanelVariants>;
+/**
+ * CVA variants for individual dropdown options.
+ *
+ * @tokens `--color-popover-foreground`, `--color-muted`, `--color-primary-subtle`,
+ *         `--color-primary-subtle-foreground`, `--color-disabled-foreground`
+ */
+declare const dropdownOptionVariants: (props?: {
+    size?: DropdownSize;
+    state?: OptionState;
+}) => string;
+type DropdownOptionVariants = VariantProps<typeof dropdownOptionVariants>;
+/**
+ * CVA variants for the search input.
+ *
+ * @tokens `--color-border-subtle`, `--color-input-placeholder`, `--color-disabled-foreground`
+ */
+declare const dropdownSearchVariants: (props?: {
+    size?: DropdownSize;
+}) => string;
+type DropdownSearchVariants = VariantProps<typeof dropdownSearchVariants>;
+/**
+ * CVA variants for multi-select tags.
+ *
+ * @tokens `--color-muted`, `--color-muted-foreground`, `--color-muted-hover`,
+ *         `--color-primary-subtle`, `--color-primary-subtle-foreground`, `--radius-tag`
+ */
+declare const dropdownTagVariants: (props?: {
+    size?: DropdownSize;
+    variant?: TagVariant;
+}) => string;
+type DropdownTagVariants = VariantProps<typeof dropdownTagVariants>;
+/**
+ * CVA variants for the tag remove button.
+ *
+ * @tokens `--color-ring`, `--radius-interactive-sm`
+ */
+declare const dropdownTagRemoveVariants: (props?: {
+    size?: DropdownSize;
+}) => string;
+type DropdownTagRemoveVariants = VariantProps<typeof dropdownTagRemoveVariants>;
+/**
+ * CVA variants for the overflow badge (+N indicator).
+ *
+ * @tokens `--color-muted`, `--color-muted-foreground`, `--radius-tag`
+ */
+declare const dropdownOverflowBadgeVariants: (props?: {
+    size?: DropdownSize;
+}) => string;
+type DropdownOverflowBadgeVariants = VariantProps<typeof dropdownOverflowBadgeVariants>;
+/**
+ * CVA variants for group headers.
+ *
+ * @tokens `--color-muted-foreground`
+ */
+declare const dropdownGroupVariants: (props?: {
+    size?: DropdownSize;
+}) => string;
+type DropdownGroupVariants = VariantProps<typeof dropdownGroupVariants>;
+/**
+ * CVA variants for the empty state.
+ *
+ * @tokens `--color-muted-foreground`
+ */
+declare const dropdownEmptyVariants: (props?: {
+    size?: DropdownSize;
+}) => string;
+type DropdownEmptyVariants = VariantProps<typeof dropdownEmptyVariants>;
+/**
+ * CVA variants for the clear button.
+ *
+ * @tokens `--color-ring`, `--radius-interactive-sm`
+ */
+declare const dropdownClearVariants: (props?: {
+    size?: DropdownSize;
+}) => string;
+type DropdownClearVariants = VariantProps<typeof dropdownClearVariants>;
+/**
+ * CVA variants for the chevron icon.
+ */
+declare const dropdownChevronVariants: (props?: {
+    size?: DropdownSize;
+    open?: boolean;
+}) => string;
+type DropdownChevronVariants = VariantProps<typeof dropdownChevronVariants>;
+
+/**
+ * Reusable dropdown/select component with full accessibility support.
+ * Implements ControlValueAccessor for Reactive Forms integration.
+ *
+ * @tokens `--color-input-background`, `--color-input-foreground`, `--color-input-border`,
+ *         `--color-input-placeholder`, `--color-ring`, `--color-muted`, `--color-muted-foreground`,
+ *         `--color-popover`, `--color-popover-foreground`, `--color-border-subtle`,
+ *         `--color-primary`, `--color-primary-subtle`, `--color-primary-subtle-foreground`,
+ *         `--color-warn`, `--color-success`, `--color-disabled`, `--color-disabled-foreground`,
+ *         `--color-placeholder`
+ *
+ * @example
+ * ```html
+ * <com-dropdown
+ *   [options]="users()"
+ *   [compareWith]="compareById"
+ *   formControlName="assignee"
+ *   placeholder="Select user..."
+ *   [searchable]="true"
+ * >
+ *   <ng-template comDropdownOption let-user let-selected="selected">
+ *     <span>{{ user.name }}</span>
+ *   </ng-template>
+ * </com-dropdown>
+ * ```
+ */
+declare class ComDropdown<T> implements ControlValueAccessor, FormFieldControl<T | T[] | null> {
+    private readonly elementRef;
+    private readonly destroyRef;
+    private readonly overlay;
+    private readonly viewContainerRef;
+    private readonly liveAnnouncer;
+    private readonly defaultErrorStateMatcher;
+    private readonly parentForm;
+    private readonly parentFormGroup;
+    /** NgControl bound to this dropdown (if using reactive forms). */
+    readonly ngControl: NgControl | null;
+    /** Reference to the trigger button element. */
+    private readonly triggerRef;
+    /** Reference to the panel template. */
+    private readonly panelTemplateRef;
+    /** Content query for custom option template. */
+    protected readonly optionTemplate: Signal<ComDropdownOptionTpl<T> | undefined>;
+    /** Content query for custom selected template. */
+    protected readonly selectedTemplate: Signal<ComDropdownSelectedTpl<T> | undefined>;
+    /** Content query for custom empty template. */
+    protected readonly emptyTemplate: Signal<ComDropdownEmptyTpl | undefined>;
+    /** Content query for custom group template. */
+    protected readonly groupTemplate: Signal<ComDropdownGroupTpl | undefined>;
+    /** Content query for custom tag template. */
+    protected readonly tagTemplate: Signal<ComDropdownTagTpl<T> | undefined>;
+    /** Overlay reference. */
+    private overlayRef;
+    /** Unique ID for the dropdown. */
+    private readonly dropdownId;
+    /** Array of options to display. */
+    readonly options: InputSignal<T[]>;
+    /** Current value (single or array for multiple). */
+    readonly value: InputSignal<T | T[] | null>;
+    /** Placeholder text when no value is selected. */
+    readonly placeholder: InputSignal<string>;
+    /** Enable multi-select mode. */
+    readonly multiple: InputSignal<boolean>;
+    /** Enable search/filter input. */
+    readonly searchable: InputSignal<boolean>;
+    /** Search input placeholder. */
+    readonly searchPlaceholder: InputSignal<string>;
+    /** Disable the dropdown. */
+    readonly disabled: InputSignal<boolean>;
+    /** Mark as required. */
+    readonly required: InputSignal<boolean>;
+    /** Show clear button. */
+    readonly clearable: InputSignal<boolean>;
+    /** Custom equality function for comparing values. */
+    readonly compareWith: InputSignal<(a: T, b: T) => boolean>;
+    /** Function to get display text from a value. */
+    readonly displayWith: InputSignal<(value: T) => string>;
+    /** Custom filter function for search. */
+    readonly filterWith: InputSignal<((option: T, query: string) => boolean) | null>;
+    /** Function to group options by a key. */
+    readonly groupBy: InputSignal<((option: T) => string) | null>;
+    /** CVA variant for trigger styling. */
+    readonly variant: InputSignal<DropdownVariant>;
+    /** Size variant. */
+    readonly size: InputSignal<DropdownSize>;
+    /** Validation state. */
+    readonly state: InputSignal<DropdownState>;
+    /** Additional CSS classes for the trigger. */
+    readonly userClass: InputSignal<string>;
+    /** Additional CSS classes for the panel. */
+    readonly panelClass: InputSignal<string>;
+    /** Maximum height of the panel. */
+    readonly maxHeight: InputSignal<string>;
+    /** Panel width strategy. */
+    readonly panelWidth: InputSignal<ComDropdownPanelWidth>;
+    /** Debounce time for search (ms). */
+    readonly searchDebounceMs: InputSignal<number>;
+    /** Virtual scroll threshold. */
+    readonly virtualScrollThreshold: InputSignal<number>;
+    /** Maximum number of tags to display in multi-select mode. Set to null for no limit. */
+    readonly maxVisibleTags: InputSignal<number | null>;
+    /** Custom error state matcher for determining when to show errors. */
+    readonly errorStateMatcher: InputSignal<ErrorStateMatcher | undefined>;
+    /** Emitted when the value changes. */
+    readonly valueChange: OutputEmitterRef<T | T[] | null>;
+    /** Emitted when search query changes. */
+    readonly searchChange: OutputEmitterRef<string>;
+    /** Emitted when panel opens. */
+    readonly opened: OutputEmitterRef<void>;
+    /** Emitted when panel closes. */
+    readonly closed: OutputEmitterRef<void>;
+    /** Whether the panel is open. */
+    readonly isOpen: WritableSignal<boolean>;
+    /** Whether the trigger button is focused. */
+    private readonly _triggerFocused;
+    /** Current search query. */
+    readonly searchQuery: WritableSignal<string>;
+    /** Currently active (keyboard focused) option ID. */
+    readonly activeOptionId: WritableSignal<string | null>;
+    /** Internal value state (managed by CVA or input). */
+    readonly internalValue: WritableSignal<T | T[] | null>;
+    /** Live announcements for screen readers. */
+    readonly liveAnnouncement: WritableSignal<string>;
+    /** IDs for aria-describedby (set by form-field). */
+    private readonly _describedByIds;
+    /** Form field appearance (set by form-field). */
+    private readonly _appearance;
+    /** Trigger element ID. */
+    readonly triggerId: Signal<string>;
+    /** Panel element ID. */
+    readonly panelId: Signal<string>;
+    /** Currently active descendant ID (for ARIA). */
+    readonly activeDescendant: Signal<string | null>;
+    /** Whether the dropdown has a value. */
+    readonly hasValue: Signal<boolean>;
+    /** Whether the dropdown is focused (trigger focused or panel open). Implements FormFieldControl. */
+    readonly focused: Signal<boolean>;
+    /** Whether the label should float. Label floats when focused or has a value. */
+    readonly shouldLabelFloat: Signal<boolean>;
+    /** Whether the control is in an error state. Implements FormFieldControl. */
+    readonly errorState: Signal<boolean>;
+    /** Unique ID for the control. Implements FormFieldControl. */
+    readonly id: Signal<string>;
+    /**
+     * Effective state combining manual state with automatic error detection.
+     * Manual state takes precedence over auto-detected error state.
+     */
+    readonly effectiveState: Signal<DropdownState>;
+    /** Combined aria-describedby from form-field. */
+    readonly ariaDescribedBy: Signal<string | null>;
+    /** Selected value (single mode). */
+    readonly selectedValue: Signal<T | null>;
+    /** Selected values (multiple mode). */
+    readonly selectedValues: Signal<T[]>;
+    /** Tags visible in the trigger (limited by maxVisibleTags). */
+    readonly visibleTags: Signal<T[]>;
+    /** Count of hidden tags (for +N badge). */
+    readonly hiddenTagsCount: Signal<number>;
+    /** Processed options with display text and IDs. */
+    readonly processedOptions: Signal<ComDropdownProcessedOption<T>[]>;
+    /** Filtered options based on search query. */
+    readonly filteredOptions: Signal<ComDropdownProcessedOption<T>[]>;
+    /** Grouped options (when groupBy is provided). */
+    readonly groupedOptions: Signal<ComDropdownGroup$1<ComDropdownProcessedOption<T>>[]>;
+    /** Whether virtual scrolling should be enabled. */
+    readonly virtualScrollEnabled: Signal<boolean>;
+    /** Context for selected template. */
+    readonly selectedContext: Signal<ComDropdownSelectedContext<T>>;
+    /** Context for empty template. */
+    readonly emptyContext: Signal<ComDropdownEmptyContext>;
+    /** Computed trigger classes. */
+    readonly triggerClasses: Signal<string>;
+    /** Computed panel classes. */
+    readonly panelClasses: Signal<string>;
+    /** Computed chevron classes. */
+    readonly chevronClasses: Signal<string>;
+    /** Computed clear button classes. */
+    readonly clearClasses: Signal<string>;
+    /** Computed overflow badge classes. */
+    readonly overflowBadgeClasses: Signal<string>;
+    private onChange;
+    private onTouched;
+    constructor();
+    writeValue(value: T | T[] | null): void;
+    registerOnChange(fn: (value: T | T[] | null) => void): void;
+    registerOnTouched(fn: () => void): void;
+    setDisabledState(isDisabled: boolean): void;
+    /**
+     * Called when the form field container is clicked.
+     * Implements FormFieldControl.
+     */
+    onContainerClick(event: MouseEvent): void;
+    /**
+     * Sets the describedBy IDs from the form field.
+     * Called by the parent form field component.
+     */
+    setDescribedByIds(ids: string): void;
+    /**
+     * Sets the appearance for styling.
+     * Called by the parent form field component.
+     */
+    setAppearance(appearance: FormFieldAppearance): void;
+    /** Opens the dropdown panel. */
+    open(): void;
+    /** Closes the dropdown panel. */
+    close(): void;
+    /** Toggles the dropdown panel. */
+    toggle(): void;
+    /** Clears the selection. */
+    clear(event?: Event): void;
+    /** Checks if a value is selected. */
+    isSelected(value: T): boolean;
+    /** Checks if an option ID is the active one. */
+    isActive(optionId: string): boolean;
+    protected onTriggerKeydown(event: KeyboardEvent): void;
+    protected onPanelKeydown(event: KeyboardEvent): void;
+    protected onSearchChange(query: string): void;
+    protected onSearchKeyNav(event: KeyboardEvent): void;
+    protected onTriggerFocus(): void;
+    protected onTriggerBlur(): void;
+    protected onOptionHover(optionId: string): void;
+    protected selectOption(value: T): void;
+    protected removeValue(value: T): void;
+    protected trackByValue(item: T, _index: number): unknown;
+    protected getGlobalIndex(groupKey: string, localIndex: number): number;
+    private createOverlay;
+    private destroyOverlay;
+    /**
+     * Returns overlay width configuration based on panelWidth setting.
+     * - 'trigger': min-width equals host, can grow wider
+     * - 'auto': no width constraint
+     * - specific value: exact width
+     */
+    private getPanelWidthConfig;
+    private updateValue;
+    private toggleMultipleValue;
+    private navigateOptions;
+    private navigateToFirst;
+    private navigateToLast;
+    private selectActiveOption;
+    private flattenGroupedOptions;
+    private typeAhead;
+    private announce;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ComDropdown<any>, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<ComDropdown<any>, "com-dropdown", ["comDropdown"], { "options": { "alias": "options"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "searchable": { "alias": "searchable"; "required": false; "isSignal": true; }; "searchPlaceholder": { "alias": "searchPlaceholder"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "clearable": { "alias": "clearable"; "required": false; "isSignal": true; }; "compareWith": { "alias": "compareWith"; "required": false; "isSignal": true; }; "displayWith": { "alias": "displayWith"; "required": false; "isSignal": true; }; "filterWith": { "alias": "filterWith"; "required": false; "isSignal": true; }; "groupBy": { "alias": "groupBy"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "state": { "alias": "state"; "required": false; "isSignal": true; }; "userClass": { "alias": "class"; "required": false; "isSignal": true; }; "panelClass": { "alias": "panelClass"; "required": false; "isSignal": true; }; "maxHeight": { "alias": "maxHeight"; "required": false; "isSignal": true; }; "panelWidth": { "alias": "panelWidth"; "required": false; "isSignal": true; }; "searchDebounceMs": { "alias": "searchDebounceMs"; "required": false; "isSignal": true; }; "virtualScrollThreshold": { "alias": "virtualScrollThreshold"; "required": false; "isSignal": true; }; "maxVisibleTags": { "alias": "maxVisibleTags"; "required": false; "isSignal": true; }; "errorStateMatcher": { "alias": "errorStateMatcher"; "required": false; "isSignal": true; }; }, { "valueChange": "valueChange"; "searchChange": "searchChange"; "opened": "opened"; "closed": "closed"; }, ["optionTemplate", "selectedTemplate", "emptyTemplate", "groupTemplate", "tagTemplate"], never, true, never>;
+}
+
+/**
+ * A single option in the dropdown list.
+ * Implements CDK's Highlightable interface for keyboard navigation.
+ *
+ * @example
+ * ```html
+ * <com-dropdown-option
+ *   [value]="user"
+ *   [selected]="isSelected(user)"
+ *   [disabled]="user.inactive"
+ *   (select)="onSelect(user)"
+ * />
+ * ```
+ *
+ * @tokens `--color-popover-foreground`, `--color-muted`, `--color-primary-subtle`,
+ *         `--color-primary-subtle-foreground`, `--color-disabled-foreground`
+ */
+declare class ComDropdownOption<T> {
+    /** Reference to the option element for focus management. */
+    private readonly optionRef;
+    /** The value this option represents. */
+    readonly value: InputSignal<T>;
+    /** Display text for this option (when no template is provided). */
+    readonly displayText: InputSignal<string>;
+    /** Unique identifier for this option. */
+    readonly id: InputSignal<string>;
+    /** Index of this option in the list. */
+    readonly index: InputSignal<number>;
+    /** Whether this option is currently selected. */
+    readonly selected: InputSignal<boolean>;
+    /** Whether this option is currently active (keyboard focused). */
+    readonly active: InputSignal<boolean>;
+    /** Whether this option is disabled. */
+    readonly disabled: InputSignal<boolean>;
+    /** Size variant for styling. */
+    readonly size: InputSignal<DropdownSize>;
+    /** Custom template for rendering the option content. */
+    readonly optionTemplate: InputSignal<TemplateRef<ComDropdownOptionContext<T>> | null>;
+    /** Additional CSS classes to apply. */
+    readonly userClass: InputSignal<string>;
+    /** Emitted when the option is selected. */
+    readonly select: OutputEmitterRef<T>;
+    /** Emitted when the mouse enters the option. */
+    readonly hover: OutputEmitterRef<T>;
+    /** Computed option state for CVA styling. */
+    protected readonly optionState: Signal<'default' | 'active' | 'selected' | 'selected-active' | 'disabled'>;
+    /** Computed CSS classes for the option. */
+    protected readonly optionClasses: Signal<string>;
+    /** Template context for custom option templates. */
+    protected readonly templateContext: Signal<ComDropdownOptionContext<T>>;
+    protected onOptionClick(event: MouseEvent): void;
+    protected onMouseEnter(): void;
+    /** Scrolls this option into view. */
+    scrollIntoView(): void;
+    /** Focuses this option element. */
+    focus(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ComDropdownOption<any>, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<ComDropdownOption<any>, "com-dropdown-option", ["comDropdownOption"], { "value": { "alias": "value"; "required": true; "isSignal": true; }; "displayText": { "alias": "displayText"; "required": false; "isSignal": true; }; "id": { "alias": "id"; "required": true; "isSignal": true; }; "index": { "alias": "index"; "required": false; "isSignal": true; }; "selected": { "alias": "selected"; "required": false; "isSignal": true; }; "active": { "alias": "active"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "optionTemplate": { "alias": "optionTemplate"; "required": false; "isSignal": true; }; "userClass": { "alias": "class"; "required": false; "isSignal": true; }; }, { "select": "select"; "hover": "hover"; }, never, never, true, never>;
+}
+
+/**
+ * The overlay panel containing the dropdown options.
+ * Supports virtual scrolling for large lists.
+ *
+ * @example
+ * ```html
+ * <com-dropdown-panel
+ *   [options]="filteredOptions()"
+ *   [maxHeight]="'300px'"
+ *   [virtualScrollEnabled]="true"
+ * >
+ *   <ng-content />
+ * </com-dropdown-panel>
+ * ```
+ *
+ * @tokens `--color-popover`, `--color-popover-foreground`, `--color-border-subtle`,
+ *         `--color-muted-foreground`, `--radius-overlay`
+ */
+declare class ComDropdownPanel<T> {
+    /** Reference to the panel element. */
+    private readonly panelRef;
+    /** Reference to the virtual scroll viewport (when enabled). */
+    readonly viewport: Signal<CdkVirtualScrollViewport | undefined>;
+    /** Unique identifier for the panel. */
+    readonly panelId: InputSignal<string>;
+    /** The processed options to display. */
+    readonly options: InputSignal<ComDropdownProcessedOption<T>[]>;
+    /** Maximum height of the panel. */
+    readonly maxHeight: InputSignal<string>;
+    /** Whether multiple selection is enabled. */
+    readonly multiselectable: InputSignal<boolean>;
+    /** Size variant for styling. */
+    readonly size: InputSignal<DropdownSize>;
+    /** Additional CSS classes to apply to the panel. */
+    readonly panelClass: InputSignal<string>;
+    /** Whether virtual scrolling is enabled. */
+    readonly virtualScrollEnabled: InputSignal<boolean>;
+    /** Item size for virtual scrolling (in pixels). */
+    readonly itemSize: InputSignal<number>;
+    /** The current search query (for empty state context). */
+    readonly searchQuery: InputSignal<string>;
+    /** Custom empty state text. */
+    readonly emptyText: InputSignal<string>;
+    /** Template for rendering each option. */
+    readonly optionTemplate: InputSignal<TemplateRef<{
+        $implicit: ComDropdownProcessedOption<T>;
+        index: number;
+    }>>;
+    /** Custom template for the empty state. */
+    readonly emptyTemplate: InputSignal<TemplateRef<ComDropdownEmptyContext> | null>;
+    /** Emitted when the panel is scrolled. */
+    readonly scrolled: OutputEmitterRef<void>;
+    /** Whether to show the empty state. */
+    protected readonly showEmpty: Signal<boolean>;
+    /** Computed CSS classes for the panel. */
+    protected readonly panelClasses: Signal<string>;
+    /** Computed CSS classes for the empty state. */
+    protected readonly emptyClasses: Signal<string>;
+    /** Template context for the empty state. */
+    protected readonly emptyContext: Signal<ComDropdownEmptyContext>;
+    /** Track function for options. */
+    protected trackByFn(_index: number, option: ComDropdownProcessedOption<T>): string;
+    /** Scrolls to a specific index. */
+    scrollToIndex(index: number): void;
+    /** Scrolls an option into view. */
+    scrollOptionIntoView(optionElement: HTMLElement): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ComDropdownPanel<any>, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<ComDropdownPanel<any>, "com-dropdown-panel", ["comDropdownPanel"], { "panelId": { "alias": "panelId"; "required": false; "isSignal": true; }; "options": { "alias": "options"; "required": false; "isSignal": true; }; "maxHeight": { "alias": "maxHeight"; "required": false; "isSignal": true; }; "multiselectable": { "alias": "multiselectable"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "panelClass": { "alias": "panelClass"; "required": false; "isSignal": true; }; "virtualScrollEnabled": { "alias": "virtualScrollEnabled"; "required": false; "isSignal": true; }; "itemSize": { "alias": "itemSize"; "required": false; "isSignal": true; }; "searchQuery": { "alias": "searchQuery"; "required": false; "isSignal": true; }; "emptyText": { "alias": "emptyText"; "required": false; "isSignal": true; }; "optionTemplate": { "alias": "optionTemplate"; "required": true; "isSignal": true; }; "emptyTemplate": { "alias": "emptyTemplate"; "required": false; "isSignal": true; }; }, { "scrolled": "scrolled"; }, never, ["[comDropdownSearch]"], true, never>;
+}
+
+/**
+ * Search input component for filtering dropdown options.
+ * Includes debouncing for better performance.
+ *
+ * @example
+ * ```html
+ * <com-dropdown-search
+ *   [placeholder]="'Search...'"
+ *   [debounceTime]="300"
+ *   (searchChange)="onSearch($event)"
+ * />
+ * ```
+ *
+ * @tokens `--color-border-subtle`, `--color-input-placeholder`, `--color-disabled-foreground`,
+ *         `--color-ring`, `--radius-interactive-sm`
+ */
+declare class ComDropdownSearch implements OnInit {
+    private readonly destroyRef;
+    /** Reference to the input element. */
+    private readonly inputRef;
+    /** Subject for debounced search. */
+    private readonly searchSubject;
+    /** Current internal search value. */
+    private readonly internalValue;
+    /** Placeholder text for the search input. */
+    readonly placeholder: InputSignal<string>;
+    /** Aria label for accessibility. */
+    readonly ariaLabel: InputSignal<string>;
+    /** Whether the search input is disabled. */
+    readonly disabled: InputSignal<boolean>;
+    /** Debounce time in milliseconds. */
+    readonly debounceMs: InputSignal<number>;
+    /** Size variant for styling. */
+    readonly size: InputSignal<DropdownSize>;
+    /** Additional CSS classes to apply. */
+    readonly userClass: InputSignal<string>;
+    /** Emitted when the search value changes (after debounce). */
+    readonly searchChange: OutputEmitterRef<string>;
+    /** Emitted when a navigation key is pressed (for focus management). */
+    readonly keyNav: OutputEmitterRef<KeyboardEvent>;
+    /** Whether to show the clear button. */
+    protected readonly showClear: Signal<boolean>;
+    /** Computed CSS classes for the search input. */
+    protected readonly searchClasses: Signal<string>;
+    ngOnInit(): void;
+    protected onInput(event: Event): void;
+    protected onKeydown(event: KeyboardEvent): void;
+    protected clearSearch(): void;
+    /** Focuses the search input. */
+    focus(): void;
+    /** Gets the current search value. */
+    getValue(): string;
+    /** Sets the search value programmatically. */
+    setValue(value: string): void;
+    /** Clears the search input. */
+    clear(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ComDropdownSearch, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<ComDropdownSearch, "com-dropdown-search", ["comDropdownSearch"], { "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "debounceMs": { "alias": "debounceMs"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "userClass": { "alias": "class"; "required": false; "isSignal": true; }; }, { "searchChange": "searchChange"; "keyNav": "keyNav"; }, never, never, true, never>;
+}
+
+/**
+ * Tag component for displaying selected items in multi-select mode.
+ * Includes a remove button for deselection.
+ *
+ * @example
+ * ```html
+ * <com-dropdown-tag
+ *   [value]="user"
+ *   [displayText]="user.name"
+ *   (remove)="onRemove(user)"
+ * />
+ * ```
+ *
+ * @tokens `--color-muted`, `--color-muted-foreground`, `--color-muted-hover`,
+ *         `--color-primary-subtle`, `--color-primary-subtle-foreground`,
+ *         `--color-ring`, `--radius-tag`, `--radius-interactive-sm`
+ */
+declare class ComDropdownTag<T> {
+    /** The value this tag represents. */
+    readonly value: InputSignal<T>;
+    /** Display text for this tag. */
+    readonly displayText: InputSignal<string>;
+    /** Index of this tag in the list. */
+    readonly index: InputSignal<number>;
+    /** Whether the tag (and its remove button) is disabled. */
+    readonly disabled: InputSignal<boolean>;
+    /** Size variant for styling. */
+    readonly size: InputSignal<DropdownSize>;
+    /** Tag variant for styling. */
+    readonly variant: InputSignal<'default' | 'primary'>;
+    /** Additional CSS classes for the tag. */
+    readonly userClass: InputSignal<string>;
+    /** Custom template for rendering the tag. */
+    readonly tagTemplate: InputSignal<TemplateRef<ComDropdownTagContext<T>> | null>;
+    /** Emitted when the remove button is clicked. */
+    readonly remove: OutputEmitterRef<T>;
+    /** Computed CSS classes for the tag. */
+    protected readonly tagClasses: Signal<string>;
+    /** Computed CSS classes for the remove button. */
+    protected readonly removeClasses: Signal<string>;
+    /** Template context for custom tag templates. */
+    protected readonly templateContext: Signal<ComDropdownTagContext<T>>;
+    protected onRemove(event: Event): void;
+    private emitRemove;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ComDropdownTag<any>, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<ComDropdownTag<any>, "com-dropdown-tag", ["comDropdownTag"], { "value": { "alias": "value"; "required": true; "isSignal": true; }; "displayText": { "alias": "displayText"; "required": false; "isSignal": true; }; "index": { "alias": "index"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "userClass": { "alias": "class"; "required": false; "isSignal": true; }; "tagTemplate": { "alias": "tagTemplate"; "required": false; "isSignal": true; }; }, { "remove": "remove"; }, never, never, true, never>;
+}
+
+/**
+ * Group header component for categorized dropdown options.
+ *
+ * @example
+ * ```html
+ * <com-dropdown-group
+ *   [label]="'Fruits'"
+ *   [count]="5"
+ * />
+ * ```
+ *
+ * @tokens `--color-muted-foreground`
+ */
+declare class ComDropdownGroup {
+    /** The group label/key. */
+    readonly label: InputSignal<string>;
+    /** The number of options in this group. */
+    readonly count: InputSignal<number>;
+    /** Whether the group is expanded (for collapsible groups). */
+    readonly expanded: InputSignal<boolean>;
+    /** Whether to show the count badge. */
+    readonly showCount: InputSignal<boolean>;
+    /** Size variant for styling. */
+    readonly size: InputSignal<DropdownSize>;
+    /** Additional CSS classes for the group header. */
+    readonly userClass: InputSignal<string>;
+    /** Custom template for rendering the group header. */
+    readonly groupTemplate: InputSignal<TemplateRef<ComDropdownGroupContext> | null>;
+    /** Computed CSS classes for the group header. */
+    protected readonly groupClasses: Signal<string>;
+    /** Template context for custom group templates. */
+    protected readonly templateContext: Signal<ComDropdownGroupContext>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ComDropdownGroup, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<ComDropdownGroup, "com-dropdown-group", ["comDropdownGroup"], { "label": { "alias": "label"; "required": true; "isSignal": true; }; "count": { "alias": "count"; "required": false; "isSignal": true; }; "expanded": { "alias": "expanded"; "required": false; "isSignal": true; }; "showCount": { "alias": "showCount"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "userClass": { "alias": "class"; "required": false; "isSignal": true; }; "groupTemplate": { "alias": "groupTemplate"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+export { ComDropdown, ComDropdownEmptyTpl, ComDropdownGroup, ComDropdownGroupTpl, ComDropdownOption, ComDropdownOptionTpl, ComDropdownPanel, ComDropdownSearch, ComDropdownSelectedTpl, ComDropdownTag, ComDropdownTagTpl, defaultCompareWith, defaultDisplayWith, defaultFilterWith, dropdownChevronVariants, dropdownClearVariants, dropdownEmptyVariants, dropdownGroupVariants, dropdownOptionVariants, dropdownOverflowBadgeVariants, dropdownPanelVariants, dropdownSearchVariants, dropdownTagRemoveVariants, dropdownTagVariants, dropdownTriggerVariants, generateDropdownId };
+export type { ComDropdownEmptyContext, ComDropdownGroupContext, ComDropdownGroup$1 as ComDropdownGroupData, ComDropdownOptionContext, ComDropdownPanelWidth, ComDropdownPosition, ComDropdownProcessedOption, ComDropdownSelectedContext, ComDropdownTagContext, DropdownChevronVariants, DropdownClearVariants, DropdownEmptyVariants, DropdownGroupVariants, DropdownOptionVariants, DropdownOverflowBadgeVariants, DropdownPanelVariants, DropdownSearchVariants, DropdownSize, DropdownState, DropdownTagRemoveVariants, DropdownTagVariants, DropdownTriggerVariants, DropdownVariant };