@acontplus/ng-components 2.1.8 → 2.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acontplus/ng-components",
-  "version": "2.1.8",
+  "version": "2.1.10",
   "description": "Comprehensive Angular Material UI component library featuring dynamic Tabulator tables, theme toggle with dark mode, dialog wrappers, autocomplete components, cards, buttons, icons, input chips, spinners, directives, pipes, and SCSS styling utilities.",
   "peerDependencies": {
     "@acontplus/ui-kit": "^1.0.2",

package/types/acontplus-ng-components.d.ts

@@ -503,7 +503,7 @@ declare class DynamicSelect implements OnInit, OnDestroy {
     clearable: _angular_core.InputSignal<boolean>;
     searchable: _angular_core.InputSignal<boolean>;
     virtualScroll: _angular_core.InputSignal<boolean>;
-    dropdownPosition: _angular_core.InputSignal<"auto" | "bottom" | "top">;
+    dropdownPosition: _angular_core.InputSignal<"top" | "bottom" | "auto">;
     closeOnSelect: _angular_core.InputSignal<boolean>;
     hideSelected: _angular_core.InputSignal<boolean>;
     multiple: _angular_core.InputSignal<boolean>;
@@ -1899,7 +1899,7 @@ type AcpPopoverPosition = [AcpPopoverPositionStart, AcpPopoverPositionEnd];
 /** Popover's trigger event. */
 type AcpPopoverTriggerEvent = 'click' | 'hover' | 'none';
 /** Reason why the popover was closed. */
-type PopoverCloseReason = void | 'click' | 'keydown' | 'tab';
+type PopoverCloseReason = void | 'click' | 'keydown' | 'tab' | 'programmatic';
 
 /**
  * Interface for a custom popover panel that can be used with `acpPopoverTriggerFor`.
@@ -1958,6 +1958,7 @@ declare const ACP_POPOVER_DEFAULT_OPTIONS: InjectionToken<AcpPopoverDefaultOptio
  * various positioning options. It's built on top of Angular CDK Overlay
  * and provides a flexible way to display contextual information.
  *
+ * ## Basic Usage
  * @example
  * ```html
  * <acp-popover #popover="acpPopover" [position]="['below', 'after']">
@@ -1966,6 +1967,62 @@ declare const ACP_POPOVER_DEFAULT_OPTIONS: InjectionToken<AcpPopoverDefaultOptio
  *
  * <button [acpPopoverTriggerFor]="popover">Show popover</button>
  * ```
+ *
+ * ## Closing Explicitly
+ *
+ * ### 1. Close from within popover content:
+ * @example
+ * ```html
+ * <acp-popover #popover="acpPopover">
+ *   <div>
+ *     <p>Popover content</p>
+ *     <button (click)="popover.close()">Close</button>
+ *     <button (click)="popover.close('user-action')">Close with reason</button>
+ *   </div>
+ * </acp-popover>
+ * ```
+ *
+ * ### 2. Close from component using ViewChild:
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <acp-popover #popover="acpPopover">
+ *       <div>Content with external close</div>
+ *     </acp-popover>
+ *     <button [acpPopoverTriggerFor]="popover">Open</button>
+ *     <button (click)="closePopover()">Close from outside</button>
+ *   `
+ * })
+ * export class MyComponent {
+ *   @ViewChild('popover') popover!: AcpPopover;
+ *
+ *   closePopover() {
+ *     this.popover.close('programmatic');
+ *   }
+ * }
+ * ```
+ *
+ * ### 3. Close using trigger reference:
+ * @example
+ * ```html
+ * <acp-popover #popover="acpPopover">
+ *   <div>Popover content</div>
+ * </acp-popover>
+ *
+ * <button [acpPopoverTriggerFor]="popover" #trigger="acpPopoverTrigger">
+ *   Show popover
+ * </button>
+ * <button (click)="trigger.closePopover()">Close via trigger</button>
+ * <button (click)="trigger.closePopoverWithReason('external')">Close with reason</button>
+ * ```
+ *
+ * ## Automatic Closing
+ * The popover automatically closes on:
+ * - ESC key press
+ * - Click outside (backdrop) when `closeOnBackdropClick` is true
+ * - Mouse leave after delay when `triggerEvent` is 'hover'
+ * - Click on panel when `closeOnPanelClick` is true
  */
 declare class AcpPopover implements AcpPopoverPanel, OnInit, OnDestroy {
     private _changeDetectorRef;
@@ -2056,6 +2113,11 @@ declare class AcpPopover implements AcpPopoverPanel, OnInit, OnDestroy {
     set classList(classes: string);
     /** Event emitted when the popover is closed. */
     closed: EventEmitter<PopoverCloseReason>;
+    /**
+     * Programmatically closes the popover.
+     * @param reason Optional reason for closing
+     */
+    close(reason?: PopoverCloseReason): void;
     /** @docs-private */
     templateRef: TemplateRef<any>;
     /**
@@ -2163,6 +2225,7 @@ declare const ACP_POPOVER_SCROLL_STRATEGY: InjectionToken<() => ScrollStrategy>;
  * The trigger handles various events (click, hover) and manages the popover's lifecycle,
  * including opening, closing, positioning, and focus management.
  *
+ * ## Basic Usage
  * @example
  * ```html
  * <acp-popover #popover="acpPopover">
@@ -2173,6 +2236,33 @@ declare const ACP_POPOVER_SCROLL_STRATEGY: InjectionToken<() => ScrollStrategy>;
  *   Show popover
  * </button>
  * ```
+ *
+ * ## Programmatic Control
+ * @example
+ * ```html
+ * <acp-popover #popover="acpPopover">
+ *   <div>Popover content</div>
+ * </acp-popover>
+ *
+ * <button [acpPopoverTriggerFor]="popover" #trigger="acpPopoverTrigger">
+ *   Toggle popover
+ * </button>
+ *
+ * <!-- Programmatic control -->
+ * <button (click)="trigger.openPopover()">Open</button>
+ * <button (click)="trigger.closePopover()">Close</button>
+ * <button (click)="trigger.closePopoverWithReason('manual')">Close with reason</button>
+ * <button (click)="trigger.togglePopover()">Toggle</button>
+ * ```
+ *
+ * ## Custom Target
+ * @example
+ * ```html
+ * <div acpPopoverTarget #target="acpPopoverTarget">Target element</div>
+ * <button [acpPopoverTriggerFor]="popover" [targetElement]="target">
+ *   Trigger (popover appears at target)
+ * </button>
+ * ```
  */
 declare class AcpPopoverTrigger implements AfterContentInit, OnDestroy {
     private _overlay;
@@ -2251,6 +2341,11 @@ declare class AcpPopoverTrigger implements AfterContentInit, OnDestroy {
     openPopover(): void;
     /** Closes the popover. */
     closePopover(): void;
+    /**
+     * Programmatically closes the popover with a specific reason.
+     * @param reason The reason for closing
+     */
+    closePopoverWithReason(reason: PopoverCloseReason): void;
     /**
      * Focuses the popover trigger.
      * @param origin Source of the popover trigger's focus.