feat(fields): adiciona po-helper com ou sem label

Adiciona o suporte ao uso de po-helper em fields mesmo quando não há label
definido, abrangendo os seguintes componentes:
- po-checkbox
- po-checkbox-group
- po-combo
- po-datepicker
- po-datepicker-range
- po-decimal
- po-email
- po-input
- po-login
- po-lookup
- po-multiselect
- po-number
- po-password
- po-radio-group
- po-select
- po-switch
- po-textarea
- po-upload
- po-url
- po-rich-text

Além disso:
- no po-popover foi tratado todo o fluxo de navegação via teclado quando o
  componente estiver configurado para trabalhar com append-in-body.
- o dynamic form recebeu a propriedade p-helper em todos os fields.

FIXES DTHFUI-11977

Author: pedrodominguesp

projects/templates/src/lib/components/po-page-dynamic-edit/po-page-dynamic-edit.component.ts

@@ -544,7 +544,7 @@ export class PoPageDynamicEditComponent implements OnInit, OnDestroy {
   }
 
   /**
-   * Método que exibe `additionalHelpTooltip` ou executa a ação definida em `additionalHelp`.
+   * Método que exibe `p-helper` ou executa a ação definida em `p-helper{eventOnClick}` ou em `p-additionalHelp`.
    * Para isso, será necessário configurar uma tecla de atalho utilizando o evento `keydown`.
    *
    * ```
@@ -557,7 +557,7 @@ export class PoPageDynamicEditComponent implements OnInit, OnDestroy {
    *    property: 'name',
    *    ...
    *    help: 'Mensagem de ajuda.',
-   *    additionalHelpTooltip: 'Mensagem de ajuda complementar.',
+   *    helper: 'Mensagem de ajuda complementar com o componente po-helper implementado.',
    *    keydown: this.onKeyDown.bind(this, 'name')
    *  },
    * ]

projects/ui/src/lib/components/po-dynamic/po-dynamic-form/interfaces/po-dynamic-form-field.interface.ts

@@ -25,6 +25,7 @@ import { ForceBooleanComponentEnum, ForceOptionComponentEnum } from '../../enums
 
 import { Observable } from 'rxjs';
 import { PoDynamicField } from '../../po-dynamic-field.interface';
+import { PoHelperOptions } from '../../../po-helper';
 
 /**
  * @usedBy PoDynamicFormComponent, PoAdvancedFilterComponent, PoPageDynamicSearchComponent
@@ -38,23 +39,25 @@ import { PoDynamicField } from '../../po-dynamic-field.interface';
 export interface PoDynamicFormField extends PoDynamicField {
   /**
    * Evento disparado ao clicar no ícone de ajuda adicional.
-   * Este evento ativa automaticamente a exibição do ícone de ajuda adicional ao `p-help`.
+   *
+   * > Essa propriedade está depreciada e será removida na versão 23.x.x. Recomendamos utilizar a propriedade p-helper que oferece mais recursos e flexibilidade.
    */
   additionalHelp?: Function;
 
   /**
-   * Exibe um ícone de ajuda adicional ao `p-help`, com o texto desta propriedade no tooltip.
-   * Se o evento `p-additional-help` estiver definido, o tooltip não será exibido.
+   * Exibe um ícone de ajuda adicional, com o texto desta propriedade sendo passado para o popover do componente `po-helper`.
    * **Como boa prática, indica-se utilizar um texto com até 140 caracteres.**
+   *
+   * > Essa propriedade está depreciada e será removida na versão 23.x.x. Recomendamos utilizar a propriedade p-helper que oferece mais recursos e flexibilidade.
    */
   additionalHelpTooltip?: string;
 
   /**
-   * Define que o `listbox` e/ou tooltip (`p-additional-help-tooltip` e/ou `p-error-limit`) serão incluídos no body da
+   * Define que o `listbox` e/ou popover (`p-helper` e/ou `p-error-limit`) serão incluídos no body da
    * página e não dentro do componente. Essa opção é necessária para cenários com containers que possuem scroll ou
    * overflow escondido, garantindo o posicionamento correto de ambos próximo ao elemento.
    *
-   * > Quando utilizado com `p-additional-help-tooltip`, leitores de tela como o NVDA podem não ler o conteúdo do tooltip.
+   * > Quando utilizado com `p-helper`, leitores de tela como o NVDA podem não ler o conteúdo do popover.
    */
   appendBox?: boolean;
 
@@ -200,6 +203,9 @@ export interface PoDynamicFormField extends PoDynamicField {
   /** Texto de ajuda. */
   help?: string;
 
+  /** Texto simples que será apresentado como auxílio ao campo ou objeto com as definições do po-helper. */
+  helper?: string | PoHelperOptions;
+
   /** Texto exibido quando o valor do componente for *true*. */
   booleanTrue?: string;
 

projects/ui/src/lib/components/po-dynamic/po-dynamic-form/po-dynamic-form-fields/po-dynamic-form-fields.component.html

@@ -30,6 +30,7 @@
         [p-auto-focus]="field.focus"
         [p-format]="field.format"
         [p-help]="field.help"
+        [p-helper]="field.helper"
         [p-iso-format]="field.isoFormat"
         [p-label]="field.label"
         [p-locale]="field.locale"
@@ -61,6 +62,7 @@
         [p-disabled]="isDisabled(field)"
         [p-auto-focus]="field.focus"
         [p-help]="field.help"
+        [p-helper]="field.helper"
         [p-label]="field.label"
         [p-literals]="field.literals"
         [p-max-date]="field.maxValue"
@@ -94,6 +96,7 @@
         [p-error-async-properties]="field.errorAsyncProperties"
         [p-auto-focus]="field.focus"
         [p-help]="field.help"
+        [p-helper]="field.helper"
         [p-label]="field.label"
         [p-mask-format-model]="field.maskFormatModel"
         [p-mask]="field.mask"
@@ -131,6 +134,7 @@
         [p-error-async-properties]="field.errorAsyncProperties"
         [p-auto-focus]="field.focus"
         [p-help]="field.help"
+        [p-helper]="field.helper"
         [p-label]="field.label"
         [p-min]="field.minValue"
         [p-max]="field.maxValue"
@@ -171,6 +175,7 @@
         [p-icon]="field.icon"
         [p-auto-focus]="field.focus"
         [p-help]="field.help"
+        [p-helper]="field.helper"
         [p-label]="field.label"
         [p-locale]="field.locale"
         [p-min]="field.minValue"
@@ -204,6 +209,7 @@
         [p-field-value]="field.fieldValue"
         [p-disabled]="isDisabled(field)"
         [p-help]="field.help"
+        [p-helper]="field.helper"
         [p-label]="field.label"
         [p-optional]="field.optional"
         [p-options]="field.options"
@@ -232,6 +238,7 @@
         [p-auto-focus]="field.focus"
         [p-disabled]="isDisabled(field)"
         [p-help]="field.help"
+        [p-helper]="field.helper"
         [p-label]="field.label"
         [p-optional]="field.optional"
         [p-options]="field.options"
@@ -259,6 +266,7 @@
         [p-field-error-message]="field.errorMessage"
         [p-format-model]="field.formatModel"
         [p-help]="field.help"
+        [p-helper]="field.helper"
         [p-label]="field.label"
         [p-label-off]="field.booleanFalse"
         [p-label-on]="field.booleanTrue"
@@ -283,6 +291,7 @@
         [p-auto-focus]="field.focus"
         [p-disabled]="isDisabled(field)"
         [p-help]="field.help"
+        [p-helper]="field.helper"
         [p-label]="field.label"
         [p-size]="field.size || componentsSize"
         (p-additional-help)="field.additionalHelp?.($event)"
@@ -308,6 +317,7 @@
         [p-filter-params]="field.params"
         [p-filter-service]="field.optionsService"
         [p-help]="field.help"
+        [p-helper]="field.helper"
         [p-infinite-scroll]="field.infiniteScroll"
         [p-infinite-scroll-distance]="field.infiniteScrollDistance || 100"
         [p-label]="field.label"
@@ -356,6 +366,7 @@
         [p-auto-focus]="field.focus"
         [p-auto-height]="field.autoHeight"
         [p-help]="field.help"
+        [p-helper]="field.helper"
         [p-field-format]="field.format"
         [p-infinite-scroll]="field.infiniteScroll"
         [p-label]="field.label"
@@ -390,6 +401,7 @@
         [p-auto-focus]="field.focus"
         [p-disabled]="isDisabled(field)"
         [p-help]="field.help"
+        [p-helper]="field.helper"
         [p-label]="field.label"
         [p-optional]="field.optional"
         [p-options]="field.options"
@@ -416,6 +428,7 @@
         [p-auto-focus]="field.focus"
         [p-auto-height]="field.autoHeight"
         [p-help]="field.help"
+        [p-helper]="field.helper"
         [p-label]="field.label"
         [p-literals]="field.literals"
         [p-optional]="field.optional"
@@ -453,6 +466,7 @@
         [p-disabled]="isDisabled(field)"
         [p-auto-focus]="field.focus"
         [p-help]="field.help"
+        [p-helper]="field.helper"
         [p-label]="field.label"
         [p-maxlength]="field.maxLength"
         [p-minlength]="field.minLength"
@@ -487,6 +501,7 @@
         [p-error-async-properties]="field.errorAsyncProperties"
         [p-auto-focus]="field.focus"
         [p-help]="field.help"
+        [p-helper]="field.helper"
         [p-hide-password-peek]="field.hidePasswordPeek"
         [p-icon]="field.icon"
         [p-label]="field.label"
@@ -524,6 +539,7 @@
         [p-form-field]="field.formField"
         [p-headers]="field.headers"
         [p-help]="field.help"
+        [p-helper]="field.helper"
         [p-hide-restrictions-info]="field.hideRestrictionsInfo"
         [p-hide-select-button]="field.hideSelectButton"
         [p-hide-send-button]="field.hideSendButton"

projects/ui/src/lib/components/po-dynamic/po-dynamic-form/po-dynamic-form.component.ts

@@ -127,7 +127,7 @@ export class PoDynamicFormComponent extends PoDynamicFormBaseComponent implement
   }
 
   /**
-   * Método que exibe `additionalHelpTooltip` ou executa a ação definida em `additionalHelp`.
+   * Método que exibe `p-helper` ou executa a ação definida em `p-helper{eventOnClick}` ou em `p-additionalHelp`.
    * Para isso, será necessário configurar uma tecla de atalho utilizando o evento `keydown`.
    *
    * ```
@@ -140,7 +140,7 @@ export class PoDynamicFormComponent extends PoDynamicFormBaseComponent implement
    *    property: 'name',
    *    ...
    *    help: 'Mensagem de ajuda.',
-   *    additionalHelpTooltip: 'Mensagem de ajuda complementar.',
+   *    helper: 'Mensagem de ajuda complementar com o componente po-helper implementado.',
    *    keydown: this.onKeyDown.bind(this, 'name')
    *  },
    * ]

projects/ui/src/lib/components/po-field/po-checkbox-group/po-checkbox-group-base.component.ts

@@ -53,8 +53,7 @@ export class PoCheckboxGroupBaseComponent implements ControlValueAccessor, Valid
    * @optional
    *
    * @description
-   * Exibe um ícone de ajuda adicional ao `p-help`, com o texto desta propriedade no tooltip.
-   * Se o evento `p-additional-help` estiver definido, o tooltip não será exibido.
+   * Exibe um ícone de ajuda adicional, com o texto desta propriedade sendo passado para o popover do componente `po-helper`.
    * **Como boa prática, indica-se utilizar um texto com até 140 caracteres.**
    * > Requer um recuo mínimo de 8px se o componente estiver próximo à lateral da tela.
    *
@@ -67,11 +66,11 @@ export class PoCheckboxGroupBaseComponent implements ControlValueAccessor, Valid
    *
    * @description
    *
-   * Define que o tooltip (`p-additional-help-tooltip` e/ou `p-error-limit`) será incluído no body da página e não
+   * Define que o popover (`p-helper` e/ou `p-error-limit`) será incluído no body da página e não
    * dentro do componente. Essa opção pode ser necessária em cenários com containers que possuem scroll ou overflow
    * escondido, garantindo o posicionamento correto do tooltip próximo ao elemento.
    *
-   * > Quando utilizado com `p-additional-help-tooltip`, leitores de tela como o NVDA podem não ler o conteúdo do tooltip.
+   * > Quando utilizado com `p-helper`, leitores de tela como o NVDA podem não ler o conteúdo do popover.
    *
    * @default `false`
    */
@@ -147,10 +146,10 @@ export class PoCheckboxGroupBaseComponent implements ControlValueAccessor, Valid
    *
    * @description
    *
-   * Define as opções do componente de ajuda (po-helper) que será exibido ao lado do label.
+   * Define as opções do componente de ajuda (po-helper) que será exibido ao lado do label quando a propriedade `p-label` for definida, ou, ao lado do componente na ausência da propriedade `p-label`.
+   * > Para mais informações acesse: https://po-ui.io/documentation/po-helper.
    *
-   * > Caso o `p-label` não esteja definido, o componente po-helper não será exibido.
-   * Ao configurar esta propriedade, o antigo ícone de ajuda adicional (`p-additional-help-tooltip` e `p-additional-help`) será ignorado.
+   * > Ao configurar esta propriedade, o antigo ícone de ajuda adicional (`p-additional-help-tooltip` e `p-additional-help`) será ignorado.
    */
   poHelperComponent = input<PoHelperOptions | string>(undefined, { alias: 'p-helper' });
 
@@ -192,7 +191,6 @@ export class PoCheckboxGroupBaseComponent implements ControlValueAccessor, Valid
    *
    * @description
    * Evento disparado ao clicar no ícone de ajuda adicional.
-   * Este evento ativa automaticamente a exibição do ícone de ajuda adicional ao `p-help`.
    *
    * > Essa propriedade está **depreciada** e será removida na versão `23.x.x`. Recomendamos utilizar a propriedade `p-helper` que oferece mais recursos e flexibilidade.
    */

projects/ui/src/lib/components/po-field/po-checkbox-group/po-checkbox-group.component.html

@@ -1,11 +1,12 @@
+@let poHelper = setHelper(label, additionalHelpTooltip);
 <po-field-container
   [p-disabled]="disabled"
   [p-label]="label"
   [p-optional]="optional"
   [p-required]="required"
   [p-show-required]="showRequired"
-  [p-helper]="setHelper(this.label, this.additionalHelpTooltip).helperSettings"
-  [p-show-helper]="displayAdditionalHelp"
+  [p-helper]="label ? poHelper.helperSettings : undefined"
+  [p-show-helper]="label ? displayAdditionalHelp : undefined"
   [p-text-wrap]="labelTextWrap()"
 >
   <div class="po-field-container-content" [attr.name]="name">
@@ -33,18 +34,29 @@
         }
       </ul>
     </div>
-
+  </div>
+  <div class="po-row po-footer-group">
     <po-field-container-bottom
       [p-additional-help-tooltip]="getAdditionalHelpTooltip()"
       [p-append-in-body]="appendBox"
       [p-help]="help"
       [p-disabled]="disabled"
       [p-error-limit]="errorLimit"
       [p-error-pattern]="getErrorPattern()"
-      [p-hide-additional-help-by-label]="setHelper(this.label, this.additionalHelpTooltip).hideAdditionalHelp"
+      [p-hide-additional-help-by-label]="poHelper.hideAdditionalHelp"
       [p-show-additional-help]="displayAdditionalHelp"
       [p-show-additional-help-icon]="showAdditionalHelpIcon()"
       (p-additional-help)="emitAdditionalHelp()"
     ></po-field-container-bottom>
+    @if ((!label && poHelperComponent()) || (!label && poHelper.hideAdditionalHelp)) {
+      <po-helper
+        #helperEl
+        [p-size]="size"
+        [p-helper]="poHelper.helperSettings"
+        [p-disabled]="disabled"
+        [p-append-in-body]="appendBox"
+      >
+      </po-helper>
+    }
   </div>
 </po-field-container>