@po-ui/ng-components 20.2.1 → 20.4.0

package/lib/components/po-helper/po-helper-base.component.d.ts

@@ -0,0 +1,109 @@
+import { PoHelperOptions } from './interfaces/po-helper.interface';
+/**
+ * @description
+ *
+ * O componente `po-helper` exibe um ícone de ajuda ou informação ao lado de campos, botões ou outros elementos, permitindo ao usuário acessar conteúdos explicativos em um popover.
+ *
+ * Principais funcionalidades:
+ * - Exibe ícone de ajuda (`help`) ou informação (`info`) conforme configuração.
+ * - Permite definir título, conteúdo e ações no popover via propriedade `p-helper`.
+ * - Suporte a acessibilidade: navegação por teclado, atributos ARIA e leitura do conteúdo por leitores de tela.
+ * - Controle do tamanho do componente via propriedade `p-size` (`small` ou `medium`).
+ * - Permite customizar ações no rodapé do popover.
+ *
+ * Exemplo de uso:
+ * ```html
+ * <po-helper
+ *   [p-helper]="{ title: 'Ajuda', content: 'Texto explicativo', type: 'help' }"
+ *   [p-size]="'medium'"
+ * ></po-helper>
+ * ```
+ *
+ * Também é possível passar apenas uma string para o conteúdo:
+ * ```html
+ * <po-helper p-helper="Texto explicativo"></po-helper>
+ * ```
+ *
+ * A propriedade `p-helper` aceita um objeto do tipo `PoHelperOptions`:
+ * ```typescript
+ * interface PoHelperOptions {
+ *   title?: string;
+ *   content: string;
+ *   type?: 'help' | 'info';
+ *   eventOnClick?: Function;
+ *   footerAction?: { label: string; action: Function };
+ * }
+ * ```
+ *
+ * > **Importante:** A propriedade `footerAction` não pode ser utilizada quando o tipo do helper for `info`, pois o ícone de informação é destinado apenas para exibir informações estáticas sem ações adicionais.
+ *
+ * #### Tokens customizáveis
+ *
+ * É possível alterar o estilo do componente usando os seguintes tokens (CSS):
+ *
+ * > Para maiores informações, acesse o guia [Personalizando o Tema Padrão com Tokens CSS](https://po-ui.io/guides/theme-customization).
+ *
+ * | Propriedade                                | Descrição                                                     | Valor Padrão                                      |
+ * |--------------------------------------------|---------------------------------------------------------------|---------------------------------------------------|
+ * | `--color`                                  | Cor principal do ícone                                        | `var(--color-action-default)`                     |
+ * | `--border-color-hover`                     | Cor da borda no estado hover                                  | `var(--color-brand-01-darkest)`                   |
+ * | `--background-pressed`                     | Cor de background no estado de pressionado&nbsp;              | `var(--color-brand-01-light)`                     |
+ * | `--color-disabled`                         | Cor principal no estado disabled                              | `var(--color-action-disabled)`                    |
+ *
+ */
+export declare class PoHelperBaseComponent {
+    /**
+     * @Input
+     *
+     * @optional
+     *
+     * @description
+     *
+     * Define o conteúdo e as opções do popover de ajuda/informação.
+     *
+     * Aceita uma string simples (exibida como conteúdo) ou um objeto do tipo `PoHelperOptions` para configuração avançada:
+     * - `title`: Título do popover.
+     * - `content`: Conteúdo explicativo exibido no popover.
+     * - `type`: Tipo do ícone (`help` ou `info`).
+     * - `eventOnClick`: Função chamada ao clicar no ícone.
+     * - `footerAction`: Objeto com `label` e `action` para ação customizada no rodapé do popover.
+     *
+     * Exemplo de uso:
+     * ```html
+     * <po-helper p-helper="Texto explicativo"></po-helper>
+     * <po-helper [p-helper]="{ title: 'Ajuda', content: 'Texto', type: 'help' }"></po-helper>
+     * ```
+     *
+     */
+    helper: import("@angular/core").InputSignal<string | PoHelperOptions>;
+    /**
+     * @Input
+     *
+     * @optional
+     *
+     * @description
+     *
+     * Define o tamanho do componente:
+     * - `small`: altura do ícone com seu valor de 16px (disponível apenas para acessibilidade AA).
+     * - `medium`: altura do ícone com seu valor de 24px.
+     *
+     * > Caso a acessibilidade AA não esteja configurada, o tamanho `medium` será mantido.
+     * Para mais detalhes, consulte a documentação do [po-theme](https://po-ui.io/documentation/po-theme).
+     *
+     * @default `medium`
+     */
+    size: import("@angular/core").InputSignal<string>;
+    /**
+     * @Input
+     *
+     * @optional
+     *
+     * @description
+     *
+     * Indica se o helper deve ser exibido no estado desativado, desabilitando interações do usuário.
+     *
+     * @default `false`
+     */
+    disabled: import("@angular/core").InputSignal<boolean>;
+    private transformHelper;
+}

package/lib/components/po-helper/po-helper.component.d.ts

@@ -0,0 +1,49 @@
+import { ElementRef, AfterViewInit, OnDestroy, OnChanges, SimpleChanges, ChangeDetectorRef } from '@angular/core';
+import { PoHelperBaseComponent } from './po-helper-base.component';
+import { PoPopoverComponent } from '../po-popover/po-popover.component';
+import { PoButtonComponent } from '../po-button';
+/**
+ * @docsExtends PoHelperBaseComponent
+ *
+ * @example
+ *
+ * <example name="po-helper-basic" title="PO Helper Basic">
+ *  <file name="sample-po-helper-basic/sample-po-helper-basic.component.html"> </file>
+ *  <file name="sample-po-helper-basic/sample-po-helper-basic.component.ts"> </file>
+ * </example>
+ *
+ * <example name="po-helper-labs" title="PO Helper Labs">
+ *  <file name="sample-po-helper-labs/sample-po-helper-labs.component.html"> </file>
+ *  <file name="sample-po-helper-labs/sample-po-helper-labs.component.ts"> </file>
+ * </example>
+ *
+ * <example name="po-helper-sales-performance" title="PO Helper Sales Performance">
+ *  <file name="sample-po-helper-sales-performance/sample-po-helper-sales-performance.component.html"> </file>
+ *  <file name="sample-po-helper-sales-performance/sample-po-helper-sales-performance.component.ts"> </file>
+ * </example>
+ *
+ */
+export declare class PoHelperComponent extends PoHelperBaseComponent implements AfterViewInit, OnDestroy, OnChanges {
+    private readonly cdr;
+    target: ElementRef;
+    popover: PoPopoverComponent;
+    poButton: PoButtonComponent;
+    private static instances;
+    private static idCounter;
+    protected popoverPosition: string;
+    id: string;
+    private boundFocusIn;
+    private readonly poHelperLiterals;
+    constructor(cdr: ChangeDetectorRef);
+    ngAfterViewInit(): void;
+    setPopoverPositionByScreen(): void;
+    ngOnChanges(changes: SimpleChanges): void;
+    ngOnDestroy(): void;
+    openHelperPopover(): void;
+    closeHelperPopover(): void;
+    emitClick(event: MouseEvent): void;
+    onKeyDown(event: KeyboardEvent): void;
+    private handleEmitEvent;
+    closePopoverOnFocusOut(event: FocusEvent): void;
+    protected ariaLabel(): string;
+}

package/lib/components/po-helper/po-helper.module.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @description
+ * Módulo do componente po-helper
+ */
+export declare class PoHelperModule {
+}

package/lib/components/po-label/po-label.component.d.ts

@@ -34,4 +34,17 @@ export declare class PoLabelComponent {
     label?: string;
     /** Indica o tipo do campo vinculado ao label */
     requirement?: string;
+    /**
+     * @optional
+     *
+     * @description
+     *
+     * Habilita a quebra automática do texto. Quando ativada, o texto que excede
+     * o espaço disponível é transferido para a próxima linha em pontos apropriados para uma
+     * leitura clara.
+     *
+     * @default `false`
+     */
+    textWrap: import("@angular/core").InputSignal<boolean>;
+    isRequiredLiteral(value: string): boolean;
 }

package/lib/components/po-popover/po-popover.component.d.ts

@@ -1,4 +1,4 @@
-import { AfterViewInit, ElementRef, OnChanges, OnDestroy, Renderer2, SimpleChanges } from '@angular/core';
+import { AfterViewInit, ChangeDetectorRef, ElementRef, OnChanges, OnDestroy, Renderer2, SimpleChanges } from '@angular/core';
 import { PoControlPositionService } from './../../services/po-control-position/po-control-position.service';
 import { PoPopoverBaseComponent } from './po-popover-base.component';
 /**
@@ -24,14 +24,15 @@ import { PoPopoverBaseComponent } from './po-popover-base.component';
  */
 export declare class PoPopoverComponent extends PoPopoverBaseComponent implements AfterViewInit, OnDestroy, OnChanges {
     private renderer;
-    private poControlPosition;
+    private readonly poControlPosition;
+    private readonly cd;
     popoverElement: ElementRef;
     arrowDirection: string;
     timeoutResize: any;
     targetElement: any;
     afterViewInitWasCalled: boolean;
     eventListenerFunction: () => void;
-    constructor(renderer: Renderer2, poControlPosition: PoControlPositionService);
+    constructor(renderer: Renderer2, poControlPosition: PoControlPositionService, cd: ChangeDetectorRef);
     ngOnChanges(changes: SimpleChanges): void;
     ngAfterViewInit(): void;
     initEvents(): void;
@@ -39,6 +40,7 @@ export declare class PoPopoverComponent extends PoPopoverBaseComponent implement
     close(): void;
     debounceResize(): void;
     open(): void;
+    ensurePopoverPosition(): void;
     setOpacity(value: number): void;
     setPopoverPosition(): void;
     setRendererListenInit(): void;

package/lib/services/po-theme/po-theme.service.d.ts

@@ -41,6 +41,7 @@ export declare class PoThemeService {
      * @param {boolean} [persistPreference=true] - (Opcional) Define se a preferência de tema deve ser salva no localStorage para persistência. `true` para salvar, `false` para não salvar.
      */
     setTheme(themeConfig: PoTheme, themeType?: PoThemeTypeEnum, a11yLevel?: PoThemeA11yEnum, persistPreference?: boolean): void;
+    private setDataDefaultSizeHTML;
     /**
      * Retorna o nível de acessibilidade configurado no tema.
      * Se não estiver configurado, retorna `AAA` como padrão.

package/lib/utils/util.d.ts

@@ -1,5 +1,6 @@
 import { PoThemeService } from '../services/po-theme/po-theme.service';
 import { PoThemeA11yEnum } from '../services/po-theme/enum/po-theme-a11y.enum';
+import { ElementRef } from '@angular/core';
 /**
  * Converte e formata os bytes em formato mais legível para o usuário.
  *
@@ -272,3 +273,25 @@ export declare function getA11yDefaultSize(): string;
  * @returns {PoThemeA11yEnum} O nível de acessibilidade, que pode ser `AA` ou `AAA`.
  */
 export declare function getA11yLevel(): PoThemeA11yEnum;
+/**
+ * Realiza a tradução das propriedades de ajuda dos componentes.
+ * Type do Helper default é 'help' e size 'medium'.
+ * @returns Objeto {helperSettings} com as propriedades do helper
+ * @returns Propriedade {hideAdditionalHelp} para controle ao esconder o ícone de ajuda adicional depreciado.
+ */
+export declare function setHelperSettings(label: string, additionalHelpTooltip: string, poHelperComponent?: any, size?: string, onClick?: any): {
+    hideAdditionalHelp: boolean;
+    helperSettings?: any;
+};
+/** Atualiza o estado do tooltip baseado na propriedade scrollWidth e clientWidth do labelElement.
+ * @param isTooltipActive Indica se o tooltip já está ativo
+ * @param labelElement ElementRef do label que será verificado se está com ellipsis
+ * @returns boolean indicando se o tooltip deve ser ativado ou desativado
+ */
+export declare function updateTooltip(isTooltipActive: boolean, labelElement: ElementRef<HTMLElement>): boolean;
+/**
+ * Retorna o elemento label que deve ser medido para verificar se está com ellipsis.
+ * @param labelElement ElementRef do label que será verificado se está com ellipsis
+ * @returns O elemento que deve ser medido para verificar se está com ellipsis.
+ */
+export declare function getMeasurableEl(labelElement: ElementRef<HTMLElement>): Element;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@po-ui/ng-components",
-  "version": "20.2.1",
+  "version": "20.4.0",
   "description": "PO UI - Components",
   "author": "PO UI",
   "license": "MIT",
@@ -22,8 +22,8 @@
   },
   "dependencies": {
     "@angular/cdk": "~20.0.3",
-    "@po-ui/style": "20.2.1",
-    "@po-ui/ng-schematics": "20.2.1",
+    "@po-ui/style": "20.4.0",
+    "@po-ui/ng-schematics": "20.4.0",
     "echarts": "^5.6.0",
     "tslib": "^2.3.0"
   },
@@ -38,7 +38,7 @@
     "@angular/platform-browser-dynamic": "^20",
     "@angular/router": "^20",
     "@angular-devkit/schematics": "^20",
-    "@po-ui/style": "20.2.1",
+    "@po-ui/style": "20.4.0",
     "rxjs": "~7.8.1",
     "zone.js": "~0.15.0"
   },

package/schematics/ng-add/index.js

@@ -18,7 +18,7 @@ function default_1(options) {
 }
 function addPoPackageAndInstall() {
     return (tree, context) => {
-        (0, package_config_1.addPackageToPackageJson)(tree, '@po-ui/ng-components', '20.2.1');
+        (0, package_config_1.addPackageToPackageJson)(tree, '@po-ui/ng-components', '20.4.0');
         // install packages
         context.addTask(new tasks_1.NodePackageInstallTask());
     };

package/schematics/ng-update/v14/index.js

@@ -6,7 +6,7 @@ const tasks_1 = require("@angular-devkit/schematics/tasks");
 const package_config_1 = require("@po-ui/ng-schematics/package-config");
 const changes_1 = require("./changes");
 function default_1() {
-    return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('20.2.1', changes_1.updateDepedenciesVersion), postUpdate()]);
+    return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('20.4.0', changes_1.updateDepedenciesVersion), postUpdate()]);
 }
 function postUpdate() {
     return (_, context) => {

package/schematics/ng-update/v15/index.js

@@ -11,7 +11,7 @@ const changes_1 = require("./changes");
 const httpClientModuleName = 'HttpClientModule';
 const httpClientModuleSourcePath = '@angular/common/http';
 function default_1() {
-    return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('20.2.1', changes_1.updateDepedenciesVersion), createUpgradeRule(), postUpdate()]);
+    return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('20.4.0', changes_1.updateDepedenciesVersion), createUpgradeRule(), postUpdate()]);
 }
 function postUpdate() {
     return (_, context) => {

package/schematics/ng-update/v16/index.js

@@ -6,7 +6,7 @@ const tasks_1 = require("@angular-devkit/schematics/tasks");
 const package_config_1 = require("@po-ui/ng-schematics/package-config");
 const changes_1 = require("./changes");
 function default_1() {
-    return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('20.2.1', changes_1.updateDepedenciesVersion), postUpdate()]);
+    return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('20.4.0', changes_1.updateDepedenciesVersion), postUpdate()]);
 }
 function postUpdate() {
     return (_, context) => {

package/schematics/ng-update/v17/index.js

@@ -6,7 +6,7 @@ const tasks_1 = require("@angular-devkit/schematics/tasks");
 const package_config_1 = require("@po-ui/ng-schematics/package-config");
 const changes_1 = require("./changes");
 function default_1() {
-    return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('20.2.1', changes_1.updateDepedenciesVersion), postUpdate()]);
+    return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('20.4.0', changes_1.updateDepedenciesVersion), postUpdate()]);
 }
 function postUpdate() {
     return (_, context) => {

package/schematics/ng-update/v18/index.js

@@ -40,11 +40,11 @@ function main(options) {
             configureNewIcon.toLowerCase() === 'y' ||
             configureNewIcon.toLowerCase() === 'sim' ||
             configureNewIcon.toLowerCase() === '') {
-            return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('20.2.1', changes_1.updateDepedenciesVersion), createUpgradeRule(), postUpdate()]);
+            return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('20.4.0', changes_1.updateDepedenciesVersion), createUpgradeRule(), postUpdate()]);
         }
         else {
             return (0, schematics_1.chain)([
-                (0, package_config_1.updatePackageJson)('20.2.1', changes_1.updateDepedenciesVersion),
+                (0, package_config_1.updatePackageJson)('20.4.0', changes_1.updateDepedenciesVersion),
                 addImportOnly(options, [IconsDictionaryName, poIconDictionary], poModuleSourcePath),
                 addProviderToAppModule(options, newProviderDictionary),
                 updateAppConfigFileRule(),

package/schematics/ng-update/v19/index.js

@@ -40,11 +40,11 @@ function main(options) {
             configureNewIcon.toLowerCase() === 'y' ||
             configureNewIcon.toLowerCase() === 'sim' ||
             configureNewIcon.toLowerCase() === '') {
-            return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('20.2.1', changes_1.updateDepedenciesVersion), createUpgradeRule(), postUpdate()]);
+            return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('20.4.0', changes_1.updateDepedenciesVersion), createUpgradeRule(), postUpdate()]);
         }
         else {
             return (0, schematics_1.chain)([
-                (0, package_config_1.updatePackageJson)('20.2.1', changes_1.updateDepedenciesVersion),
+                (0, package_config_1.updatePackageJson)('20.4.0', changes_1.updateDepedenciesVersion),
                 addImportOnly(options, [IconsDictionaryName, poIconDictionary], poModuleSourcePath),
                 addProviderToAppModule(options, newProviderDictionary),
                 updateAppConfigFileRule(),

package/schematics/ng-update/v2/index.js

@@ -10,7 +10,7 @@ const package_config_1 = require("@po-ui/ng-schematics/package-config");
 const changes_1 = require("./changes");
 function updateToV2() {
     return (0, schematics_1.chain)([
-        updatePackageJson('20.2.1', changes_1.dependeciesChanges),
+        updatePackageJson('20.4.0', changes_1.dependeciesChanges),
         (0, replace_1.replaceInFile)('tslint.json', changes_1.tsLintReplaces),
         (0, replace_1.replaceInFile)('angular.json', changes_1.angularJsonReplaces),
         createUpgradeRule(),

package/schematics/ng-update/v20/index.js

@@ -40,11 +40,11 @@ function main(options) {
             configureNewIcon.toLowerCase() === 'y' ||
             configureNewIcon.toLowerCase() === 'sim' ||
             configureNewIcon.toLowerCase() === '') {
-            return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('20.2.1', changes_1.updateDepedenciesVersion), createUpgradeRule(), postUpdate()]);
+            return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('20.4.0', changes_1.updateDepedenciesVersion), createUpgradeRule(), postUpdate()]);
         }
         else {
             return (0, schematics_1.chain)([
-                (0, package_config_1.updatePackageJson)('20.2.1', changes_1.updateDepedenciesVersion),
+                (0, package_config_1.updatePackageJson)('20.4.0', changes_1.updateDepedenciesVersion),
                 addImportOnly(options, [IconsDictionaryName, poIconDictionary], poModuleSourcePath),
                 addProviderToAppModule(options, newProviderDictionary),
                 updateAppConfigFileRule(),

package/schematics/ng-update/v3/index.js

@@ -7,7 +7,7 @@ const project_1 = require("@po-ui/ng-schematics/project");
 const package_config_1 = require("@po-ui/ng-schematics/package-config");
 const changes_1 = require("./changes");
 function updateToV3() {
-    return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('20.2.1', changes_1.updateDepedenciesVersion), createUpgradeRule(), postUpdate()]);
+    return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('20.4.0', changes_1.updateDepedenciesVersion), createUpgradeRule(), postUpdate()]);
 }
 function postUpdate() {
     return (_, context) => {

package/schematics/ng-update/v4/index.js

@@ -7,7 +7,7 @@ const project_1 = require("@po-ui/ng-schematics/project");
 const package_config_1 = require("@po-ui/ng-schematics/package-config");
 const changes_1 = require("./changes");
 function default_1() {
-    return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('20.2.1', changes_1.updateDepedenciesVersion), createUpgradeRule(), postUpdate()]);
+    return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('20.4.0', changes_1.updateDepedenciesVersion), createUpgradeRule(), postUpdate()]);
 }
 function postUpdate() {
     return (_, context) => {

package/schematics/ng-update/v5/index.js

@@ -7,7 +7,7 @@ const project_1 = require("@po-ui/ng-schematics/project");
 const package_config_1 = require("@po-ui/ng-schematics/package-config");
 const changes_1 = require("./changes");
 function default_1() {
-    return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('20.2.1', changes_1.updateDepedenciesVersion), createUpgradeRule(), postUpdate()]);
+    return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('20.4.0', changes_1.updateDepedenciesVersion), createUpgradeRule(), postUpdate()]);
 }
 function postUpdate() {
     return (_, context) => {

package/schematics/ng-update/v6/index.js

@@ -6,7 +6,7 @@ const tasks_1 = require("@angular-devkit/schematics/tasks");
 const package_config_1 = require("@po-ui/ng-schematics/package-config");
 const changes_1 = require("./changes");
 function default_1() {
-    return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('20.2.1', changes_1.updateDepedenciesVersion), postUpdate()]);
+    return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('20.4.0', changes_1.updateDepedenciesVersion), postUpdate()]);
 }
 function postUpdate() {
     return (_, context) => {