@makigamestudio/ui-ionic 0.6.1 → 0.8.0

package/types/makigamestudio-ui-ionic.d.ts

@@ -1,7 +1,17 @@
-import * as _makigamestudio_ui_core from '@makigamestudio/ui-core';
-import { ActionButton, ActionButtonConfig, ActionButtonType } from '@makigamestudio/ui-core';
+import { ActionButton, ActionButtonConfig, ActionButtonType, TooltipPlacement } from '@makigamestudio/ui-core';
 import * as _angular_core from '@angular/core';
-import { Signal } from '@angular/core';
+import { Signal, OnDestroy, TemplateRef } from '@angular/core';
+
+/**
+ * @file IonicColor type
+ * @description Ionic color names for use in components and configs.
+ *
+ * This type centralizes all valid Ionic color names for use in the ui-ionic library.
+ *
+ * @example
+ *   const color: IonicColor = 'primary';
+ */
+type IonicColor = 'primary' | 'secondary' | 'tertiary' | 'success' | 'warning' | 'danger' | 'light' | 'medium' | 'dark';
 
 /**
  * @file Ionic Action Button Types
@@ -47,7 +57,7 @@ type IonicPopoverAlignment = 'start' | 'center' | 'end';
  * const config: IonicActionButtonConfig = {
  *   fill: 'solid',       // Type-checked: 'clear' | 'outline' | 'solid' | 'default'
  *   size: 'large',       // Type-checked: 'small' | 'default' | 'large'
- *   color: 'primary',    // Any string (Ionic color names or custom)
+ *   color: 'primary',    // IonicColor (Ionic color names)
  *   shape: 'round',      // Type-checked: 'round' | undefined
  *   expand: 'block',     // Type-checked: 'block' | 'full' | undefined
  *   dropdownAlignment: 'end'  // Type-checked: 'start' | 'center' | 'end'
@@ -103,7 +113,14 @@ type IonicActionButtonConfig = ActionButtonConfig<IonicButtonFill, IonicButtonSi
  * };
  * ```
  */
-type IonicActionButton<T = void> = ActionButton<T, IonicActionButtonConfig>;
+type IonicActionButton<T = void> = Omit<ActionButton<T, IonicActionButtonConfig>, 'config' | 'tooltipColor' | 'children'> & {
+    /** Optional configuration for button styling. */
+    readonly config?: IonicActionButtonConfig;
+    /** Optional color for the tooltip background. */
+    readonly tooltipColor?: IonicColor;
+    /** Child action buttons for dropdown menus. */
+    readonly children?: readonly IonicActionButton<T>[];
+};
 
 /**
  * Component that renders a list of action buttons for use in popovers/dropdowns.
@@ -131,10 +148,10 @@ type IonicActionButton<T = void> = ActionButton<T, IonicActionButtonConfig>;
  *
  * @usageNotes
  * ### Inputs
- * - `buttons` (required): Array of `ActionButton` objects to display
+ * - `buttons` (required): Array of `IonicActionButton` objects to display
  *
  * ### Outputs
- * - `buttonSelect`: Emits the selected `ActionButton` when clicked
+ * - `buttonSelect`: Emits the selected `IonicActionButton` when clicked
  */
 declare class ActionButtonListComponent {
     /** Reference to ActionButtonType.Dropdown for template comparison. */
@@ -148,38 +165,38 @@ declare class ActionButtonListComponent {
     /** Internal signal to store the Set of currently loading child button IDs. */
     private readonly _loadingChildIdsFromProps;
     /** The list of action buttons to display (when used via template binding). */
-    readonly buttons: _angular_core.InputSignal<readonly ActionButton<void, _makigamestudio_ui_core.ActionButtonConfig<string, string, string, string, string>>[]>;
+    readonly buttons: _angular_core.InputSignal<readonly IonicActionButton[]>;
     /** Emits when a button is selected from the list. */
-    readonly buttonSelect: _angular_core.OutputEmitterRef<ActionButton<void, _makigamestudio_ui_core.ActionButtonConfig<string, string, string, string, string>>>;
+    readonly buttonSelect: _angular_core.OutputEmitterRef<IonicActionButton>;
     /** Computed button list that works with both signal input and componentProps. */
-    protected readonly buttonList: Signal<readonly ActionButton<void, _makigamestudio_ui_core.ActionButtonConfig<string, string, string, string, string>>[]>;
+    protected readonly buttonList: Signal<readonly IonicActionButton[]>;
     /**
      * Setter to capture buttons passed via PopoverController.create({ componentProps }).
      * This is called when Ionic sets the property directly on the component instance.
      */
-    set buttonsFromPopover(value: readonly ActionButton[]);
+    set buttonsFromPopover(value: readonly IonicActionButton[]);
     /**
      * Setter to capture loading child IDs signal passed via PopoverController.create({ componentProps }).
      */
     set loadingChildIds(value: Signal<ReadonlySet<string>>);
     /** Checks if a button can be selected. */
-    protected canSelectButton(button: ActionButton): boolean;
+    protected canSelectButton(button: IonicActionButton): boolean;
     /** Checks if a button should show its loading spinner. */
-    protected shouldShowSpinner(button: ActionButton): boolean;
+    protected shouldShowSpinner(button: IonicActionButton): boolean;
     /**
      * Handles click on a button item.
      * Emits the selected button and dismisses the popover.
      *
      * @param button - The clicked action button
      */
-    protected onButtonClick(button: ActionButton): void;
+    protected onButtonClick(button: IonicActionButton): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<ActionButtonListComponent, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<ActionButtonListComponent, "maki-action-button-list", never, { "buttons": { "alias": "buttons"; "required": false; "isSignal": true; }; }, { "buttonSelect": "buttonSelect"; }, never, never, true, never>;
 }
 
 /**
  * A configurable button component that renders an `ion-button` based on
- * an `ActionButton` configuration object.
+ * an `IonicActionButton` configuration object.
  *
  * Features:
  * - Two button types: Default and Dropdown
@@ -202,26 +219,54 @@ declare class ActionButtonListComponent {
  *
  * <!-- Dropdown button -->
  * <maki-button [button]="menuButton" />
+ *
+ * <!-- Button with tooltip -->
+ * <maki-button [button]="buttonWithTooltip" />
  * ```
  *
  * @example
  * ```typescript
  * // In your component
- * import { ActionButton, ActionButtonType } from '@makigamestudio/ui-core';
+ * import { ActionButtonType } from '@makigamestudio/ui-core';
  * import { IonicActionButton } from '@makigamestudio/ui-ionic';
+ * import { TemplateRef, ViewChild } from '@angular/core';
  *
- * // Generic ActionButton (loose typing)
- * saveButton: ActionButton = {
+ * // Button with string tooltip
+ * saveButton: IonicActionButton = {
  *   id: 'save',
  *   label: 'Save',
  *   icon: 'save-outline',
  *   type: ActionButtonType.Default,
+ *   tooltip: 'Save your changes',
  *   config: { fill: 'solid', color: 'primary' },
  *   handler: async () => {
  *     await this.saveData();
  *   }
  * };
  *
+ * // Button with colored tooltip
+ * deleteButton: IonicActionButton = {
+ *   id: 'delete',
+ *   icon: 'trash-outline',
+ *   type: ActionButtonType.Default,
+ *   tooltip: 'Permanently delete this item',
+ *   tooltipColor: 'danger',
+ *   config: { fill: 'clear', color: 'danger' },
+ *   handler: () => this.deleteItem()
+ * };
+ *
+ * // Button with template tooltip
+ * @ViewChild('richTooltip') richTooltipTemplate!: TemplateRef<unknown>;
+ *
+ * infoButton: IonicActionButton = {
+ *   id: 'info',
+ *   icon: 'information-circle-outline',
+ *   type: ActionButtonType.Default,
+ *   tooltip: this.richTooltipTemplate,
+ *   tooltipColor: 'primary',
+ *   handler: () => {}
+ * };
+ *
  * // IonicActionButton (strict typing for Ionic-specific config)
  * ionicButton: IonicActionButton = {
  *   id: 'ionic',
@@ -234,7 +279,7 @@ declare class ActionButtonListComponent {
  *   }
  * };
  *
- * menuButton: ActionButton = {
+ * menuButton: IonicActionButton = {
  *   id: 'menu',
  *   label: 'Actions',
  *   type: ActionButtonType.Dropdown,
@@ -248,7 +293,7 @@ declare class ActionButtonListComponent {
  *
  * @usageNotes
  * ### Inputs
- * - `button` (required): The `ActionButton` configuration object
+ * - `button` (required): The `IonicActionButton` configuration object
  *
  * ### Outputs
  * - `buttonClick`: Emits the button configuration when clicked (for non-dropdown buttons)
@@ -274,11 +319,11 @@ declare class ButtonComponent {
     /** Service for handler execution. */
     private readonly handlerService;
     /** The action button configuration. */
-    readonly button: _angular_core.InputSignal<ActionButton<void, _makigamestudio_ui_core.ActionButtonConfig<string, string, string, string, string>>>;
+    readonly button: _angular_core.InputSignal<IonicActionButton>;
     /** Emits when the button is clicked (for non-dropdown buttons). */
-    readonly buttonClick: _angular_core.OutputEmitterRef<ActionButton<void, _makigamestudio_ui_core.ActionButtonConfig<string, string, string, string, string>>>;
+    readonly buttonClick: _angular_core.OutputEmitterRef<IonicActionButton>;
     /** Emits when a child button is selected from a dropdown. */
-    readonly childSelect: _angular_core.OutputEmitterRef<ActionButton<void, _makigamestudio_ui_core.ActionButtonConfig<string, string, string, string, string>>>;
+    readonly childSelect: _angular_core.OutputEmitterRef<IonicActionButton>;
     /** Whether the button is in a loading state. */
     readonly isLoading: _angular_core.Signal<boolean>;
     /** Whether to display the loading spinner. */
@@ -310,5 +355,244 @@ declare class ButtonComponent {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<ButtonComponent, "maki-button", never, { "button": { "alias": "button"; "required": true; "isSignal": true; }; }, { "buttonClick": "buttonClick"; "childSelect": "childSelect"; }, never, never, true, never>;
 }
 
-export { ActionButtonListComponent, ButtonComponent };
-export type { IonicActionButton, IonicActionButtonConfig, IonicButtonExpand, IonicButtonFill, IonicButtonShape, IonicButtonSize, IonicPopoverAlignment };
+/**
+ * Directive for displaying contextual tooltips with device-aware behavior.
+ *
+ * The directive automatically adapts its behavior based on device type:
+ * - **Desktop**: Shows tooltip on hover after 500ms delay, hides on mouse leave
+ * - **Mobile**: Shows/hides tooltip on click (suppressed for interactive elements)
+ *
+ * Tooltips are positioned intelligently to avoid viewport overflow, appearing
+ * above or to the left of the element when necessary.
+ *
+ * @usageNotes
+ *
+ * ### Basic String Tooltip
+ * ```html
+ * <button makiTooltip="Click to save">Save</button>
+ * ```
+ *
+ * ### Colored Tooltip
+ * ```html
+ * <ion-button makiTooltip="Permanently delete" makiTooltipColor="danger">
+ *   Delete
+ * </ion-button>
+ * ```
+ *
+ * ### Template Tooltip
+ * ```html
+ * <ng-template #richTooltip>
+ *   <div class="custom-tooltip">
+ *     <h4>Title</h4>
+ *     <p>Description</p>
+ *   </div>
+ * </ng-template>
+ * <div [makiTooltip]="richTooltip">Hover for details</div>
+ * ```
+ *
+ * ### Live Updates with Signals
+ * ```html
+ * <span [makiTooltip]="statusTooltip()">Hover</span>
+ * ```
+ * ```typescript
+ * readonly statusTooltip = signal('Status: Ready');
+ *
+ * // Tooltip updates live while open
+ * this.statusTooltip.set('Status: Processing');
+ * ```
+ *
+ * ### Mobile Behavior
+ * On mobile devices, tooltips are suppressed for interactive elements
+ * (button, ion-button, ion-select, a) to avoid interfering with their
+ * primary click handlers.
+ */
+declare class MakiTooltipDirective implements OnDestroy {
+    private readonly el;
+    private readonly renderer;
+    private readonly appRef;
+    private readonly destroyRef;
+    private readonly tooltipService;
+    private readonly scheduler;
+    private readonly deviceDetection;
+    /**
+     * Tooltip content - can be a string or a template reference.
+     *
+     * If the input is signal-driven, an open tooltip will update live
+     * when the signal value changes.
+     *
+     * @example
+     * ```html
+     * <!-- String content -->
+     * <button makiTooltip="Save changes">Save</button>
+     *
+     * <!-- Template content -->
+     * <ng-template #tooltip>Rich content</ng-template>
+     * <div [makiTooltip]="tooltip">Hover</div>
+     * ```
+     */
+    readonly content: _angular_core.InputSignal<string | TemplateRef<unknown>>;
+    /**
+     * Optional color for the tooltip background.
+     * Accepts Ionic color names or null for default styling.
+     *
+     * @example
+     * ```html
+     * <button makiTooltip="Delete" makiTooltipColor="danger">Delete</button>
+     * ```
+     */
+    readonly color: _angular_core.InputSignal<IonicColor | null>;
+    /**
+     * Preferred tooltip placement. If provided, the directive will attempt to
+     * position the tooltip on the specified side before falling back.
+     */
+    readonly position: _angular_core.InputSignal<TooltipPlacement | undefined>;
+    /**
+     * Optional context object for TemplateRef tooltips.
+     * Supports signal inputs so templates can react to changes.
+     * Open tooltips update live as the context signal changes.
+     *
+     * The context is exposed as both named properties and `$implicit`.
+     *
+     * @example
+     * ```html
+     * <ng-template #tooltip let-title="title" let-data>
+     *   <strong>{{ title }}</strong>
+     *   <span>{{ data?.title }}</span>
+     * </ng-template>
+     * <span [makiTooltip]="tooltip" [makiTooltipContext]="{ title: 'Info' }">Hover</span>
+     * ```
+     */
+    readonly context: _angular_core.InputSignal<unknown>;
+    /**
+     * Reference to the tooltip DOM element.
+     */
+    private tooltip;
+    /**
+     * Timeout handle for hover delay.
+     */
+    /**
+     * Reference to the embedded view when using template content.
+     */
+    private viewRef;
+    /**
+     * Tracks the current template reference to detect swaps.
+     */
+    private currentTemplateRef;
+    /**
+     * Cleanup function for document touch listener.
+     */
+    private touchListenerCleanup;
+    /**
+     * Animation frame ID for tooltip follow loop.
+     */
+    private positionAnimationFrame;
+    /**
+     * Timeout handle for fade-out removal.
+     */
+    private fadeTimeout;
+    /**
+     * Scheduler handle for this directive instance (isolated timers).
+     * */
+    private readonly schedulerHandle;
+    /**
+     * Indicates whether the directive has been destroyed.
+     */
+    private isDestroyed;
+    /**
+     * Latest resolved TemplateRef context.
+     */
+    private latestTemplateContext;
+    constructor();
+    /**
+     * Shows tooltip on mouse enter (desktop only).
+     * Adds a 500ms delay to avoid showing tooltips during quick mouse movements.
+     */
+    protected onMouseEnter(): void;
+    protected onMouseLeave(): void;
+    /**
+     * Toggles tooltip on click (all devices).
+     * On mobile, skips interactive elements. On desktop, acts as a toggle.
+     */
+    protected onClick(): void;
+    /**
+     * Checks if tooltip can be shown using TooltipService logic.
+     *
+     * @returns `true` if tooltip can be shown, `false` otherwise
+     */
+    private canShowTooltip;
+    private resolveTemplateContext;
+    private unwrapSignal;
+    /**
+     * Clears the hover timeout if it exists.
+     */
+    /**
+     * Creates and displays the tooltip element.
+     *
+     * The tooltip is created as a fixed-position element appended to the document body.
+     * Content can be either plain text or a rendered template.
+     */
+    private showTooltip;
+    /**
+     * Positions the tooltip using TooltipService calculations.
+     */
+    private positionTooltip;
+    /**
+     * Adds a document-level touch listener to hide tooltip on any touch outside.
+     * Only used on mobile devices.
+     */
+    private addDocumentTouchListener;
+    /**
+     * Removes the document-level touch listener.
+     */
+    private removeDocumentTouchListener;
+    /**
+     * Removes the tooltip from the DOM and cleans up resources.
+     */
+    private hideTooltip;
+    private clearFadeTimeout;
+    private updateTooltipContent;
+    private updateTemplateContent;
+    private updateStringContent;
+    private clearTooltipContent;
+    /**
+     * Añade listeners de interacción al tooltip para mantenerlo abierto mientras se interactúa.
+     */
+    private addTooltipInteractionListeners;
+    /**
+     * Elimina listeners de interacción del tooltip.
+     */
+    private removeTooltipInteractionListeners;
+    /**
+     * Handler: mouse entra en el tooltip (desktop).
+     */
+    private readonly onTooltipMouseEnter;
+    /**
+     * Handler: mouse sale del tooltip (desktop).
+     */
+    private readonly onTooltipMouseLeave;
+    /**
+     * Handler: touchstart en el tooltip (mobile).
+     */
+    private readonly onTooltipTouchStart;
+    /**
+     * Handler: touchend en el tooltip (mobile).
+     */
+    private readonly onTooltipTouchEnd;
+    /**
+     * Starts a high-performance animation frame loop to keep the tooltip positioned with its trigger.
+     */
+    private startTooltipFollowLoop;
+    /**
+     * Stops the animation frame loop for tooltip positioning.
+     */
+    private stopTooltipFollowLoop;
+    /**
+     * Cleanup on directive destruction.
+     */
+    ngOnDestroy(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MakiTooltipDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MakiTooltipDirective, "[makiTooltip]", never, { "content": { "alias": "makiTooltip"; "required": true; "isSignal": true; }; "color": { "alias": "makiTooltipColor"; "required": false; "isSignal": true; }; "position": { "alias": "makiTooltipPosition"; "required": false; "isSignal": true; }; "context": { "alias": "makiTooltipContext"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+export { ActionButtonListComponent, ButtonComponent, MakiTooltipDirective };
+export type { IonicActionButton, IonicActionButtonConfig, IonicButtonExpand, IonicButtonFill, IonicButtonShape, IonicButtonSize, IonicColor, IonicPopoverAlignment };