feat(components): implementa help adicional ao p-help

Implementa help adicional ao p-help, permitindo exibir um tooltip ou disparar um evento. fixes DTHFUI-10443
po-ui · Jan 23, 2025 · cfc2398 · cfc2398
1 parent a42f2be
commit cfc2398
Show file tree

Hide file tree

Showing 102 changed files with 2,629 additions and 1,008 deletions.
diff --git a/...rc/lib/components/po-page-dynamic-edit/interfaces/po-page-dynamic-edit-field.interface.ts b/...rc/lib/components/po-page-dynamic-edit/interfaces/po-page-dynamic-edit-field.interface.ts
@@ -6,6 +6,8 @@ import { PoDynamicFormField } from '@po-ui/ng-components';
  * @description
  *
  * Interface dos fields usados para compor o template `po-page-dynamic-edit`.
+ * Herda as definições da interface
+ * [PoDynamicFormField](https://po-ui.io/documentation/po-dynamic-form).
  */
 export interface PoPageDynamicEditField extends PoDynamicFormField {
   /** Indica se o campo será duplicado caso seja executada a ação de duplicação. */

diff --git a/...it/samples/sample-po-page-dynamic-edit-user/sample-po-page-dynamic-edit-user.component.ts b/...it/samples/sample-po-page-dynamic-edit-user/sample-po-page-dynamic-edit-user.component.ts
@@ -36,7 +36,14 @@ export class SamplePoPageDynamicEditUserComponent {
     { property: 'name', divider: 'Personal data', required: true },
     { property: 'nickname' },
     { property: 'email', label: 'E-mail' },
-    { property: 'birthdate', label: 'Birth date', type: 'date' },
+    {
+      property: 'birthdate',
+      label: 'Birth date',
+      type: 'date',
+      errorMessage: 'Invalid date.',
+      help: 'Enter or select a valid date.',
+      additionalHelpTooltip: 'Please enter a valid date in the format MMDDYYYY.'
+    },
     { property: 'genre', options: ['female', 'male', 'others'], gridLgColumns: 6 },
     { property: 'nationality' },
     { property: 'birthPlace', label: 'Place of birth' },

diff --git a/projects/ui/src/lib/components/po-dynamic/po-dynamic-form/po-dynamic-form-field.interface.ts b/projects/ui/src/lib/components/po-dynamic/po-dynamic-form/po-dynamic-form-field.interface.ts
@@ -36,6 +36,41 @@ import { PoDynamicField } from '../po-dynamic-field.interface';
  * Interface para definição das propriedades dos campos de entrada que serão criados dinamicamente.
  */
 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`.
+   *
+   * **Componentes compatíveis:** `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-rich-text`, `po-select`, `po-switch`, `po-textarea`, `po-upload`, `po-url`.
+   */
+  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.
+   * **Como boa prática, indica-se utilizar um texto com até 140 caracteres.**
+   *
+   * **Componentes compatíveis:** `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-rich-text`, `po-select`, `po-switch`, `po-textarea`, `po-upload`, `po-url`.
+   */
+  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 
+   * 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.
+   *
+   * > O uso dessa propriedade pode acarretar na perda sequencial da tabulação da página.
+   * Quando utilizado com `p-additional-help-tooltip`, leitores de tela como o NVDA podem não ler o conteúdo do tooltip.
+   * 
+   * **Componentes compatíveis:** `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-rich-text`, `po-select`, `po-switch`, `po-textarea`, `po-upload`, `po-url`.
+   */
+  appendBox?: boolean;
+
   /**
    * Define as colunas para utilização da busca avançada. Usada somente em conjunto com a propriedade `searchService`,
    * essa propriedade deve receber um array de objetos que implementam a interface [`PoLookupColumn`](/documentation/po-lookup).
@@ -298,8 +333,6 @@ export interface PoDynamicFormField extends PoDynamicField {
    */
   errorLimit?: boolean;
 
-  errorAppendBox?: boolean;
-
   /**
    * Função executada para realizar a validação assíncrona personalizada.
    * Executada ao disparar o output `change` ou `change-model`, dependendo do valor da propriedade `triggerMode`.

diff --git a/...s/po-dynamic/po-dynamic-form/po-dynamic-form-fields/po-dynamic-form-fields.component.html b/...s/po-dynamic/po-dynamic-form/po-dynamic-form-fields/po-dynamic-form-fields.component.html
@@ -10,13 +10,14 @@
 <ng-template #poContent let-fields>
   <ng-container *ngFor="let field of fields; trackBy: trackBy">
     <po-divider *ngIf="field?.divider?.trim()" class="po-sm-12" [p-label]="field.divider"> </po-divider>
-
     <po-datepicker
       #component
       *ngIf="compareTo(field.control, 'datepicker')"
       [name]="field.property"
       [(ngModel)]="value[field.property]"
       [ngClass]="field.componentClass"
+      [additionalHelpEventTrigger]="field.additionalHelp ? 'event' : 'noEvent'"
+      [p-additional-help-tooltip]="field.additionalHelpTooltip"
       [p-clean]="field.clean"
       [p-disabled]="isDisabled(field)"
       [p-error-pattern]="field.errorMessage"
@@ -38,6 +39,7 @@
       [p-show-required]="field.showRequired"
       (p-change)="onChangeField(field)"
       [p-placeholder]="field.placeholder"
+      (p-additional-help)="field.additionalHelp?.($event)"
     >
     </po-datepicker>
 
@@ -47,6 +49,8 @@
       [name]="field.property"
       [(ngModel)]="value[field.property]"
       [ngClass]="field.componentClass"
+      [additionalHelpEventTrigger]="field.additionalHelp ? 'event' : 'noEvent'"
+      [p-additional-help-tooltip]="field.additionalHelpTooltip"
       [p-clean]="field.clean"
       [p-disabled]="isDisabled(field)"
       [p-auto-focus]="field.focus"
@@ -62,6 +66,7 @@
       [p-field-error-message]="field.errorMessage"
       [p-error-limit]="field.errorLimit"
       [p-show-required]="field.showRequired"
+      (p-additional-help)="field.additionalHelp?.($event)"
       (p-change)="onChangeField(field)"
     >
     </po-datepicker-range>
@@ -72,6 +77,8 @@
       [name]="field.property"
       [(ngModel)]="value[field.property]"
       [ngClass]="field.componentClass"
+      [additionalHelpEventTrigger]="field.additionalHelp ? 'event' : 'noEvent'"
+      [p-additional-help-tooltip]="field.additionalHelpTooltip"
       [p-clean]="field.clean"
       [p-disabled]="isDisabled(field)"
       [p-error-pattern]="field.errorMessage"
@@ -90,6 +97,7 @@
       [p-required]="field.required"
       [p-required-field-error-message]="field.requiredFieldErrorMessage"
       [p-show-required]="field.showRequired"
+      (p-additional-help)="field.additionalHelp?.($event)"
       (p-change)="onChangeField(field)"
       (p-change-model)="onChangeFieldModel(field)"
       [p-icon]="field.icon"
@@ -104,6 +112,8 @@
       [name]="field.property"
       [(ngModel)]="value[field.property]"
       [ngClass]="field.componentClass"
+      [additionalHelpEventTrigger]="field.additionalHelp ? 'event' : 'noEvent'"
+      [p-additional-help-tooltip]="field.additionalHelpTooltip"
       [p-clean]="field.clean"
       [p-disabled]="isDisabled(field)"
       [p-error-pattern]="field.errorMessage"
@@ -123,6 +133,7 @@
       [p-required]="field.required"
       [p-required-field-error-message]="field.requiredFieldErrorMessage"
       [p-show-required]="field.showRequired"
+      (p-additional-help)="field.additionalHelp?.($event)"
       (p-change)="onChangeField(field)"
       (p-change-model)="onChangeFieldModel(field)"
       [p-icon]="field.icon"
@@ -136,6 +147,8 @@
       [name]="field.property"
       [(ngModel)]="value[field.property]"
       [ngClass]="field.componentClass"
+      [additionalHelpEventTrigger]="field.additionalHelp ? 'event' : 'noEvent'"
+      [p-additional-help-tooltip]="field.additionalHelpTooltip"
       [p-clean]="field.clean"
       [p-error-pattern]="field.errorMessage"
       [p-error-limit]="field.errorLimit"
@@ -158,6 +171,7 @@
       [p-required]="field.required"
       [p-required-field-error-message]="field.requiredFieldErrorMessage"
       [p-show-required]="field.showRequired"
+      (p-additional-help)="field.additionalHelp?.($event)"
       (p-change)="onChangeField(field)"
       (p-change-model)="onChangeFieldModel(field)"
       [p-placeholder]="field.placeholder"
@@ -170,6 +184,8 @@
       [name]="field.property"
       [(ngModel)]="value[field.property]"
       [ngClass]="field.componentClass"
+      [additionalHelpEventTrigger]="field.additionalHelp ? 'event' : 'noEvent'"
+      [p-additional-help-tooltip]="field.additionalHelpTooltip"
       [p-field-label]="field.fieldLabel"
       [p-field-value]="field.fieldValue"
       [p-disabled]="isDisabled(field)"
@@ -181,6 +197,7 @@
       [p-field-error-message]="field.errorMessage"
       [p-error-limit]="field.errorLimit"
       [p-show-required]="field.showRequired"
+      (p-additional-help)="field.additionalHelp?.($event)"
       (p-change)="onChangeField(field)"
       [p-placeholder]="field.placeholder"
       [p-readonly]="field.readonly"
@@ -193,6 +210,8 @@
       [name]="field.property"
       [(ngModel)]="value[field.property]"
       [ngClass]="field.componentClass"
+      [additionalHelpEventTrigger]="field.additionalHelp ? 'event' : 'noEvent'"
+      [p-additional-help-tooltip]="field.additionalHelpTooltip"
       [p-columns]="field.columns || 3"
       [p-auto-focus]="field.focus"
       [p-disabled]="isDisabled(field)"
@@ -204,6 +223,7 @@
       [p-field-error-message]="field.errorMessage"
       [p-error-limit]="field.errorLimit"
       [p-show-required]="field.showRequired"
+      (p-additional-help)="field.additionalHelp?.($event)"
       (p-change)="onChangeField(field)"
     >
     </po-radio-group>
@@ -214,6 +234,8 @@
       [name]="field.property"
       [(ngModel)]="value[field.property]"
       [ngClass]="field.componentClass"
+      [additionalHelpEventTrigger]="field.additionalHelp ? 'event' : 'noEvent'"
+      [p-additional-help-tooltip]="field.additionalHelpTooltip"
       [p-disabled]="isDisabled(field)"
       [p-format-model]="field.formatModel"
       [p-help]="field.help"
@@ -222,6 +244,7 @@
       [p-label-on]="field.booleanTrue"
       [p-label-position]="field.labelPosition"
       [p-hide-label-status]="field.hideLabelStatus"
+      (p-additional-help)="field.additionalHelp?.($event)"
       (p-change)="onChangeField(field)"
     >
     </po-switch>
@@ -232,10 +255,13 @@
       [name]="field.property"
       [(ngModel)]="value[field.property]"
       [ngClass]="field.componentClass"
+      [additionalHelpEventTrigger]="field.additionalHelp ? 'event' : 'noEvent'"
+      [p-additional-help-tooltip]="field.additionalHelpTooltip"
       [p-auto-focus]="field.focus"
       [p-disabled]="isDisabled(field)"
       [p-label]="field.label"
       [p-size]="field.size"
+      (p-additional-help)="field.additionalHelp?.($event)"
       (p-change)="onChangeField(field)"
     >
     </po-checkbox>
@@ -247,6 +273,8 @@
       [(ngModel)]="value[field.property]"
       [ngClass]="field.componentClass"
       p-emit-object-value
+      [additionalHelpEventTrigger]="field.additionalHelp ? 'event' : 'noEvent'"
+      [p-additional-help-tooltip]="field.additionalHelpTooltip"
       [p-auto-focus]="field.focus"
       [p-clean]="field.clean"
       [p-disabled]="isDisabled(field)"
@@ -275,6 +303,7 @@
       [p-disabled-tab-filter]="field.disabledTabFilter"
       [p-debounce-time]="field.debounceTime"
       [p-change-on-enter]="field.changeOnEnter"
+      (p-additional-help)="field.additionalHelp?.($event)"
     >
     </po-combo>
 
@@ -286,6 +315,8 @@
       p-field-label="label"
       p-field-value="value"
       [ngClass]="field.componentClass"
+      [additionalHelpEventTrigger]="field.additionalHelp ? 'event' : 'noEvent'"
+      [p-additional-help-tooltip]="field.additionalHelpTooltip"
       [p-clean]="field.clean"
       [p-columns]="field.columns"
       [p-disabled]="isDisabled(field)"
@@ -310,6 +341,7 @@
       (p-change)="onChangeField(field)"
       [p-placeholder]="field.placeholder"
       [p-advanced-filters]="field.advancedFilters"
+      (p-additional-help)="field.additionalHelp?.($event)"
       (p-change-visible-columns)="field.changeVisibleColumns?.($event)"
       (p-restore-column-manager)="field.columnRestoreManager?.($event)"
     >
@@ -321,6 +353,8 @@
       [name]="field.property"
       [(ngModel)]="value[field.property]"
       [ngClass]="field.componentClass"
+      [additionalHelpEventTrigger]="field.additionalHelp ? 'event' : 'noEvent'"
+      [p-additional-help-tooltip]="field.additionalHelpTooltip"
       [p-columns]="field.columns || 3"
       [p-auto-focus]="field.focus"
       [p-disabled]="isDisabled(field)"
@@ -332,6 +366,7 @@
       [p-show-required]="field.showRequired"
       [p-field-error-message]="field.errorMessage"
       [p-error-limit]="field.errorLimit"
+      (p-additional-help)="field.additionalHelp?.($event)"
       (p-change)="onChangeField(field)"
     >
     </po-checkbox-group>
@@ -342,6 +377,8 @@
       [name]="field.property"
       [(ngModel)]="value[field.property]"
       [ngClass]="field.componentClass"
+      [additionalHelpEventTrigger]="field.additionalHelp ? 'event' : 'noEvent'"
+      [p-additional-help-tooltip]="field.additionalHelpTooltip"
       [p-disabled]="isDisabled(field)"
       [p-auto-focus]="field.focus"
       [p-auto-height]="field.autoHeight"
@@ -365,6 +402,7 @@
       [p-placeholder-search]="field.placeholderSearch"
       [p-hide-search]="field.hideSearch"
       [p-hide-select-all]="field.hideSelectAll"
+      (p-additional-help)="field.additionalHelp?.($event)"
     >
     </po-multiselect>
 
@@ -374,6 +412,8 @@
       [name]="field.property"
       [(ngModel)]="value[field.property]"
       [ngClass]="field.componentClass"
+      [additionalHelpEventTrigger]="field.additionalHelp ? 'event' : 'noEvent'"
+      [p-additional-help-tooltip]="field.additionalHelpTooltip"
       [p-disabled]="isDisabled(field)"
       [p-auto-focus]="field.focus"
       [p-help]="field.help"
@@ -387,6 +427,7 @@
       [p-error-limit]="field.errorLimit"
       [p-show-required]="field.showRequired"
       [p-rows]="field.rows"
+      (p-additional-help)="field.additionalHelp?.($event)"
       (p-change)="onChangeField(field)"
       (p-change-model)="onChangeFieldModel(field)"
       [p-placeholder]="field.placeholder"
@@ -399,6 +440,8 @@
       [name]="field.property"
       [(ngModel)]="value[field.property]"
       [ngClass]="field.componentClass"
+      [additionalHelpEventTrigger]="field.additionalHelp ? 'event' : 'noEvent'"
+      [p-additional-help-tooltip]="field.additionalHelpTooltip"
       [p-clean]="field.clean"
       [p-disabled]="isDisabled(field)"
       [p-error-pattern]="field.errorMessage"
@@ -418,6 +461,7 @@
       [p-required]="field.required"
       [p-required-field-error-message]="field.requiredFieldErrorMessage"
       [p-show-required]="field.showRequired"
+      (p-additional-help)="field.additionalHelp?.($event)"
       (p-change)="onChangeField(field)"
       (p-change-model)="onChangeFieldModel(field)"
       [p-placeholder]="field.placeholder"
@@ -429,6 +473,8 @@
       *ngIf="compareTo(field.control, 'upload')"
       [(ngModel)]="value[field.property]"
       [ngClass]="field.componentClass"
+      [additionalHelpEventTrigger]="field.additionalHelp ? 'event' : 'noEvent'"
+      [p-additional-help-tooltip]="field.additionalHelpTooltip"
       [p-auto-upload]="field.autoUpload"
       [p-directory]="field.directory"
       [p-disabled]="isDisabled(field)"
@@ -453,6 +499,7 @@
       [p-optional]="field.optional"
       [p-required]="field.required"
       [p-show-required]="field.showRequired"
+      (p-additional-help)="field.additionalHelp?.($event)"
       (p-change)="onChangeField(field)"
       (p-change-model)="onChangeFieldModel(field)"
       [p-url]="field.url"

diff --git a/...rm/samples/sample-po-dynamic-form-container/sample-po-dynamic-form-container.component.ts b/...rm/samples/sample-po-dynamic-form-container/sample-po-dynamic-form-container.component.ts
@@ -40,7 +40,9 @@ export class SamplePoDynamicFormContainerComponent implements OnInit {
       gridSmColumns: 12,
       maxValue: '2010-01-01',
       errorMessage: 'The date must be before the year 2010.',
-      order: -1
+      order: -1,
+      help: 'Enter or select a valid date.',
+      additionalHelpTooltip: 'Please enter a valid date in the format MMDDYYYY.'
     },
     { property: 'cpf', label: 'CPF', mask: '999.999.999-99', gridColumns: 6, gridSmColumns: 12, visible: false },
     { property: 'cnpj', label: 'CNPJ', mask: '99.999.999/9999-99', gridColumns: 6, gridSmColumns: 12, visible: false },
@@ -60,7 +62,9 @@ export class SamplePoDynamicFormContainerComponent implements OnInit {
       secret: true,
       pattern: '[a-zA]{5}[Z0-9]{3}',
       errorMessage: 'At least 5 alphabetic and 3 numeric characters are required.',
-      placeholder: 'Type your password'
+      placeholder: 'Type your password',
+      help: 'Password must include a combination of letters and numbers.',
+      additionalHelpTooltip: 'At least 5 alphabetic and 3 numeric characters are required.'
     },
     {
       property: 'rememberSecretKey',
@@ -110,7 +114,9 @@ export class SamplePoDynamicFormContainerComponent implements OnInit {
       container: 'Work data',
       range: true,
       gridColumns: 5,
-      gridSmColumns: 12
+      gridSmColumns: 12,
+      help: 'Enter or select a valid date range.',
+      additionalHelpTooltip: 'Ensure the start date is earlier than or equal to the end date.'
     },
     {
       property: 'entryTime',