feat(page-default): habilita ação p-refresh no header

projects/ui/src/lib/components/po-helper/interfaces/po-helper-custom-action.interface.ts

@@ -0,0 +1,18 @@
+/**
+ * @docsPrivate
+ *
+ * @description
+ *
+ * Interface interna para configuração de ações customizadas no po-helper.
+ * Utilizada exclusivamente para repasse de configuração entre os componentes de página (po-page-default, po-page-header) e o po-helper.
+ */
+export interface PoHelperCustomAction {
+  /** Ícone a ser exibido no botão. */
+  icon: string;
+
+  /** Label de acessibilidade para o botão. */
+  ariaLabel?: string;
+
+  /** Função callback a ser executada ao clicar no botão. */
+  action: Function;
+}

projects/ui/src/lib/components/po-helper/po-helper-base.component.spec.ts

@@ -1,6 +1,7 @@
 import { ComponentFixture, TestBed } from '@angular/core/testing';
 import { PoHelperBaseComponent } from './po-helper-base.component';
 import { PoHelperOptions } from './interfaces/po-helper.interface';
+import { PoHelperCustomAction } from './interfaces/po-helper-custom-action.interface';
 
 describe('PoHelperBaseComponent:', () => {
   let component: PoHelperBaseComponent;
@@ -34,6 +35,42 @@ describe('PoHelperBaseComponent:', () => {
       fixture.componentRef.setInput('p-helper', options);
       expect(component.helper()).toEqual(options);
     });
+
+    describe('p-custom-action:', () => {
+      it('should have customAction input with undefined as default value', () => {
+        expect(component.customAction()).toBeUndefined();
+      });
+
+      it('should accept a valid PoHelperCustomAction object', () => {
+        const action: PoHelperCustomAction = {
+          icon: 'ICON_REFRESH',
+          ariaLabel: 'Refresh',
+          action: () => {}
+        };
+        fixture.componentRef.setInput('p-custom-action', action);
+        expect(component.customAction()).toEqual(action);
+      });
+
+      it('should accept a PoHelperCustomAction without ariaLabel', () => {
+        const action: PoHelperCustomAction = {
+          icon: 'ICON_REFRESH',
+          action: () => {}
+        };
+        fixture.componentRef.setInput('p-custom-action', action);
+        expect(component.customAction()).toEqual(action);
+        expect(component.customAction().ariaLabel).toBeUndefined();
+      });
+
+      it('should accept undefined value', () => {
+        fixture.componentRef.setInput('p-custom-action', undefined);
+        expect(component.customAction()).toBeUndefined();
+      });
+
+      it('should accept null value', () => {
+        fixture.componentRef.setInput('p-custom-action', null);
+        expect(component.customAction()).toBeNull();
+      });
+    });
   });
 
   describe('transformHelper:', () => {

projects/ui/src/lib/components/po-helper/po-helper-base.component.ts

@@ -1,7 +1,9 @@
 import { Component, HostBinding, input } from '@angular/core';
-import { PoHelperOptions } from './interfaces/po-helper.interface';
+
 import { validateSizeFn } from '../../utils/util';
 import { PoFieldSize } from '../../enums/po-field-size.enum';
+import { PoHelperOptions } from './interfaces/po-helper.interface';
+import { PoHelperCustomAction } from './interfaces/po-helper-custom-action.interface';
 /**
  * @description
  *
@@ -86,6 +88,9 @@ export class PoHelperBaseComponent {
     transform: this.transformHelper.bind(this)
   });
 
+  /** @docsPrivate */
+  customAction = input<PoHelperCustomAction>(undefined, { alias: 'p-custom-action' });
+
   /**
    * @optional
    *

projects/ui/src/lib/components/po-helper/po-helper.component.html

@@ -1,52 +1,68 @@
-<div
-  class="po-helper-container po-helper-target"
-  #target
-  [attr.tabindex]="disabled() ? null : 0"
-  role="button"
-  [attr.aria-label]="ariaLabel()"
-  [attr.aria-haspopup]="'dialog'"
-  [attr.aria-expanded]="!popover.isHidden"
-  [attr.aria-controls]="'popover-content-' + id"
-  [attr.aria-describedby]="!popover.isHidden ? 'popover-content-' + id : null"
-  [class.po-helper-disabled]="disabled()"
-  (keydown)="onKeyDown($event)"
-  (click)="openHelperPopover(); emitClick($event)"
->
-  <po-icon [p-icon]="helper()?.type === 'info' ? 'ICON_INFO' : 'ICON_HELP'"></po-icon>
-  <po-popover
-    #popover
-    [p-position]="popoverPosition"
-    [p-target]="target"
-    [p-title]="helper()?.title"
-    [p-append-in-body]="appendBox()"
-    [p-offset]="8"
-    p-custom-classes="po-helper-popover"
-    p-trigger="function"
-    (p-close)="handleClose()"
-    (p-open)="handleOpen()"
+@if (customAction()) {
+  <div
+    class="po-helper-container po-helper-target"
+    [class.po-helper-refresh-animating]="refreshAnimating"
+    [attr.tabindex]="0"
+    role="button"
+    [attr.aria-label]="customAction().ariaLabel || ''"
+    (keydown.enter)="executeCustomAction($event)"
+    (keydown.space)="executeCustomAction($event)"
+    (click)="executeCustomAction($event)"
+    (animationend)="onRefreshAnimationEnd()"
   >
-    <div [id]="'popover-content-' + id" role="dialog" aria-modal="false" tabindex="-1">
-      <span class="po-helper-content-text">
-        @for (fragment of contentFragments(); track $index) {
-          <span
-            [class.po-text-bold]="fragment.bold"
-            [class.po-text-italic]="fragment.italic"
-            [class.po-text-underline]="fragment.underline"
-            >{{ fragment.text }}</span
+    <po-icon [p-icon]="customAction().icon"></po-icon>
+  </div>
+} @else {
+  <div
+    class="po-helper-container po-helper-target"
+    #target
+    [attr.tabindex]="disabled() ? null : 0"
+    role="button"
+    [attr.aria-label]="ariaLabel()"
+    [attr.aria-haspopup]="'dialog'"
+    [attr.aria-expanded]="!popover.isHidden"
+    [attr.aria-controls]="'popover-content-' + id"
+    [attr.aria-describedby]="!popover.isHidden ? 'popover-content-' + id : null"
+    [class.po-helper-disabled]="disabled()"
+    (keydown)="onKeyDown($event)"
+    (click)="openHelperPopover(); emitClick($event)"
+  >
+    <po-icon [p-icon]="helper()?.type === 'info' ? 'ICON_INFO' : 'ICON_HELP'"></po-icon>
+    <po-popover
+      #popover
+      [p-position]="popoverPosition"
+      [p-target]="target"
+      [p-title]="helper()?.title"
+      [p-append-in-body]="appendBox()"
+      [p-offset]="8"
+      p-custom-classes="po-helper-popover"
+      p-trigger="function"
+      (p-close)="handleClose()"
+      (p-open)="handleOpen()"
+    >
+      <div [id]="'popover-content-' + id" role="dialog" aria-modal="false" tabindex="-1">
+        <span class="po-helper-content-text">
+          @for (fragment of contentFragments(); track $index) {
+            <span
+              [class.po-text-bold]="fragment.bold"
+              [class.po-text-italic]="fragment.italic"
+              [class.po-text-underline]="fragment.underline"
+              >{{ fragment.text }}</span
+            >
+          }
+        </span>
+        @if (helper()?.type === 'help' && helper()?.footerAction) {
+          <po-divider></po-divider>
+          <po-link
+            class="po-helper-footer-action-link"
+            (keydown.enter)="$event.stopPropagation()"
+            (keydown.space)="$event.stopPropagation()"
+            (p-action)="helper()?.footerAction?.action()"
+            [p-label]="helper()?.footerAction?.label"
           >
+          </po-link>
         }
-      </span>
-      @if (helper()?.type === 'help' && helper()?.footerAction) {
-        <po-divider></po-divider>
-        <po-link
-          class="po-helper-footer-action-link"
-          (keydown.enter)="$event.stopPropagation()"
-          (keydown.space)="$event.stopPropagation()"
-          (p-action)="helper()?.footerAction?.action()"
-          [p-label]="helper()?.footerAction?.label"
-        >
-        </po-link>
-      }
-    </div>
-  </po-popover>
-</div>
+      </div>
+    </po-popover>
+  </div>
+}

projects/ui/src/lib/components/po-helper/po-helper.component.spec.ts

@@ -609,4 +609,80 @@ describe('PoHelperComponent', () => {
       expect(component['contentFragments']()).toEqual([]);
     });
   });
+
+  describe('executeCustomAction:', () => {
+    it('should call action function from customAction', () => {
+      const actionSpy = jasmine.createSpy('action');
+      (component as any).customAction = () => ({ icon: 'ICON_REFRESH', action: actionSpy });
+
+      const event = new MouseEvent('click', { bubbles: true, cancelable: true });
+      spyOn(event, 'preventDefault');
+      spyOn(event, 'stopPropagation');
+
+      component.executeCustomAction(event);
+
+      expect(event.preventDefault).toHaveBeenCalled();
+      expect(event.stopPropagation).toHaveBeenCalled();
+      expect(actionSpy).toHaveBeenCalled();
+    });
+
+    it('should set refreshAnimating to true when action is called', () => {
+      const actionSpy = jasmine.createSpy('action');
+      (component as any).customAction = () => ({ icon: 'ICON_REFRESH', action: actionSpy });
+
+      const event = new MouseEvent('click');
+      component.executeCustomAction(event);
+
+      expect(component.refreshAnimating).toBeTrue();
+    });
+
+    it('should not call action if customAction is undefined', () => {
+      (component as any).customAction = () => undefined;
+
+      const event = new MouseEvent('click');
+      expect(() => component.executeCustomAction(event)).not.toThrow();
+      expect(component.refreshAnimating).toBeFalse();
+    });
+
+    it('should not call action if action is not a function', () => {
+      (component as any).customAction = () => ({ icon: 'ICON_REFRESH', action: 'not a function' });
+
+      const event = new MouseEvent('click');
+      expect(() => component.executeCustomAction(event)).not.toThrow();
+      expect(component.refreshAnimating).toBeFalse();
+    });
+
+    it('should reset and retrigger animation on rapid successive clicks', () => {
+      const actionSpy = jasmine.createSpy('action');
+      (component as any).customAction = () => ({ icon: 'ICON_REFRESH', action: actionSpy });
+      const cdrSpy = spyOn(component['cdr'], 'detectChanges');
+
+      const event = new MouseEvent('click');
+
+      // First click
+      component.executeCustomAction(event);
+      expect(component.refreshAnimating).toBeTrue();
+      expect(cdrSpy).not.toHaveBeenCalled();
+
+      // Second click while animation is still running
+      component.executeCustomAction(event);
+      expect(cdrSpy).toHaveBeenCalled();
+      expect(component.refreshAnimating).toBeTrue();
+      expect(actionSpy).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe('onRefreshAnimationEnd:', () => {
+    it('should set refreshAnimating to false', () => {
+      component.refreshAnimating = true;
+      component.onRefreshAnimationEnd();
+      expect(component.refreshAnimating).toBeFalse();
+    });
+  });
+
+  describe('refreshAnimating:', () => {
+    it('should be false by default', () => {
+      expect(component.refreshAnimating).toBeFalse();
+    });
+  });
 });

projects/ui/src/lib/components/po-helper/po-helper.component.ts

@@ -1,18 +1,19 @@
 import {
+  computed,
   Component,
-  ElementRef,
-  ViewChild,
-  AfterViewInit,
   OnDestroy,
   OnChanges,
+  ViewChild,
+  ElementRef,
+  AfterViewInit,
   SimpleChanges,
-  ChangeDetectorRef,
-  computed
+  ChangeDetectorRef
 } from '@angular/core';
+
+import { PoButtonComponent } from '../po-button';
 import { PoHelperBaseComponent } from './po-helper-base.component';
 import { PoHelperOptions } from './interfaces/po-helper.interface';
 import { PoPopoverComponent } from '../po-popover/po-popover.component';
-import { PoButtonComponent } from '../po-button';
 import { parseSafeText, PoTextFragment, PoFormattingTag } from '../../utils/safe-text-parser';
 
 /** Tags de formatação aceitas pelo po-helper. */
@@ -49,6 +50,7 @@ export class PoHelperComponent extends PoHelperBaseComponent implements AfterVie
   @ViewChild('popover', { static: false }) popover: PoPopoverComponent;
   @ViewChild(PoButtonComponent, { read: ElementRef, static: true }) poButton: PoButtonComponent;
 
+  refreshAnimating = false;
   private static instances: Array<PoHelperComponent> = [];
   private static idCounter = 0;
   protected popoverPosition = 'right';
@@ -224,4 +226,22 @@ export class PoHelperComponent extends PoHelperBaseComponent implements AfterVie
       window.removeEventListener('focusin', this.boundFocusIn, true);
     }
   }
+
+  executeCustomAction(event: Event): void {
+    event.preventDefault();
+    event.stopPropagation();
+    const action = this.customAction();
+    if (action && typeof action.action === 'function') {
+      if (this.refreshAnimating) {
+        this.refreshAnimating = false;
+        this.cdr.detectChanges();
+      }
+      this.refreshAnimating = true;
+      action.action();
+    }
+  }
+
+  onRefreshAnimationEnd(): void {
+    this.refreshAnimating = false;
+  }
 }