@po-ui/ng-components 21.17.0 → 21.18.0

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

@@ -1,7 +1,7 @@
 import { CdkDragDrop } from '@angular/cdk/drag-drop';
 import { CdkVirtualScrollViewport } from '@angular/cdk/scrolling';
 import { DecimalPipe } from '@angular/common';
-import { AfterViewInit, ChangeDetectorRef, DoCheck, ElementRef, IterableDiffers, OnDestroy, OnInit, QueryList, Renderer2, TemplateRef } from '@angular/core';
+import { AfterViewChecked, AfterViewInit, ChangeDetectorRef, DoCheck, ElementRef, IterableDiffers, OnDestroy, OnInit, QueryList, Renderer2, TemplateRef } from '@angular/core';
 import { PoDateService } from '../../services/po-date/po-date.service';
 import { PoLanguageService } from '../../services/po-language/po-language.service';
 import { PoNotificationService } from '../../services/po-notification/po-notification.service';
@@ -69,13 +69,18 @@ import { PoTableColumnSpacing } from './enums/po-table-spacing.enum';
  *  <file name="sample-po-table-draggable/sample-po-table-draggable.component.ts"> </file>
  * </example>
  */
-export declare class PoTableComponent extends PoTableBaseComponent implements AfterViewInit, DoCheck, OnDestroy, OnInit {
+export declare class PoTableComponent extends PoTableBaseComponent implements AfterViewChecked, AfterViewInit, DoCheck, OnDestroy, OnInit {
+    private readonly renderer;
     private readonly changeDetector;
     private readonly decimalPipe;
     private readonly defaultService;
     tableRowTemplate: PoTableRowTemplateDirective;
     tableCellTemplate: PoTableCellTemplateDirective;
     tableColumnTemplates: QueryList<PoTableColumnTemplateDirective>;
+    virtualScrollWrapper: ElementRef;
+    headerScrollContainer: ElementRef;
+    headerTableElement: ElementRef;
+    bodyTableElement: ElementRef;
     noColumnsHeader: any;
     poPopupComponent: PoPopupComponent;
     modalDelete: PoModalComponent;
@@ -104,9 +109,10 @@ export declare class PoTableComponent extends PoTableBaseComponent implements Af
     idRadio: string;
     inputFieldValue: string;
     JSON: JSON;
-    newOrderColumns: Array<PoTableColumn>;
     sizeLoading: string;
     headerWidth: number;
+    headerTableScrollWidth: number;
+    computedColumnWidths: Array<string>;
     close: PoModalAction;
     confirm: PoModalAction;
     private _columnManagerTarget;
@@ -118,6 +124,20 @@ export declare class PoTableComponent extends PoTableBaseComponent implements Af
     private scrollEvent$;
     private subscriptionScrollEvent;
     private readonly subscriptionService;
+    private resizeObserver;
+    private scrollSyncListener;
+    private containerScrollSyncListener;
+    private virtualScrollOverflowConfigured;
+    private syncScheduled;
+    private lastColumnsKey;
+    private lastHeaderHeight;
+    private readonly SELECTOR_BODY_ROW;
+    private readonly SELECTOR_HEADER_CELLS;
+    private readonly SELECTOR_HEADER_MAIN_CELLS;
+    private readonly SELECTOR_BODY_CELLS;
+    private readonly SELECTOR_BODY_MAIN_CELLS;
+    private readonly SELECTOR_CDK_CONTENT_WRAPPER;
+    private readonly SELECTOR_FIXED_INNER_CONTAINER;
     private readonly clickListener;
     private readonly resizeListener;
     set columnManagerTarget(value: ElementRef);
@@ -139,10 +159,11 @@ export declare class PoTableComponent extends PoTableBaseComponent implements Af
     get hasVisibleSubtitleColumns(): boolean;
     get isSingleAction(): boolean;
     get isDraggable(): boolean;
-    get inverseOfTranslation(): string;
     ngOnInit(): void;
     changeHeaderWidth(): void;
     ngAfterViewInit(): void;
+    ngAfterViewChecked(): void;
+    private shouldScheduleVirtualScrollColumnSyncWithoutWidths;
     showMoreInfiniteScroll({ target }: {
         target: any;
     }): void;
@@ -298,4 +319,14 @@ export declare class PoTableComponent extends PoTableBaseComponent implements Af
     private setTableOpacity;
     private verifyChangeHeightInFooter;
     private toggleSelect;
+    private configureVirtualScrollOverflow;
+    private applyVirtualScrollStyles;
+    private registerScrollSyncListeners;
+    private syncHeaderScrollLeft;
+    private setupColumnWidthSync;
+    private clearColumnWidths;
+    private removeCellWidthStyles;
+    private syncColumnWidths;
+    private measureCellWidths;
+    private syncHeaderTableWidth;
 }

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

@@ -1,6 +1,6 @@
-import { AfterViewInit, AfterViewChecked, ElementRef, EventEmitter, OnChanges, OnDestroy, OnInit, QueryList, SimpleChanges } from '@angular/core';
-import { PoButtonComponent } from '../po-button/po-button.component';
+import { OnInit, OnChanges, OnDestroy, QueryList, ElementRef, EventEmitter, SimpleChanges, AfterViewInit, AfterViewChecked } from '@angular/core';
 import { PoTimerBaseComponent } from './po-timer-base.component';
+import { PoButtonComponent } from '../po-button/po-button.component';
 /** Tipo dos eixos das colunas. */
 type PoTimerColumnType = 'hour' | 'minute' | 'second' | 'period';
 /**

package/lib/services/index.d.ts

@@ -10,3 +10,4 @@ export * from './po-i18n/index';
 export * from './po-media-query/index';
 export * from './po-notification/index';
 export * from './po-theme/index';
+export * from './po-user-guide/index';

package/lib/services/po-theme/helpers/types/po-theme-dark-defaults-AA.constant.d.ts

@@ -85,6 +85,7 @@ declare const poThemeDefaultDarkValuesAA: {
         '--color-black-alpha-10': string;
         '--color-black-alpha-15': string;
         '--color-black-alpha-30': string;
+        '--color-po-user-guide-overlay': string;
         '--color-primary-light-80': string;
         '--color-primary-light-95': string;
         '--color-primary-alpha-50': string;

package/lib/services/po-theme/helpers/types/po-theme-dark-defaults.constant.d.ts

@@ -89,6 +89,7 @@ declare const poThemeDefaultDarkValues: {
         '--color-black-alpha-10': string;
         '--color-black-alpha-15': string;
         '--color-black-alpha-30': string;
+        '--color-po-user-guide-overlay': string;
         '--color-primary-light-80': string;
         '--color-primary-light-95': string;
         '--color-primary-alpha-50': string;

package/lib/services/po-user-guide/enums/index.d.ts

@@ -0,0 +1,2 @@
+export * from './po-user-guide-alignment.enum';
+export * from './po-user-guide-position.enum';

package/lib/services/po-user-guide/enums/po-user-guide-alignment.enum.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @usedBy PoUserGuideService
+ *
+ * @description
+ *
+ * *Enum* que define o alinhamento do popover do tour ao longo do eixo da posição configurada,
+ * utilizado na propriedade `align` de `PoUserGuideStep`.
+ *
+ * > Quando o valor não é informado, é aplicado o padrão `PoUserGuideAlignment.Start`.
+ */
+export declare enum PoUserGuideAlignment {
+    /** O popover é alinhado ao início do eixo da posição (topo ou esquerda, conforme a `PoUserGuidePosition`). */
+    Start = "start",
+    /** O popover é alinhado ao centro do eixo da posição. */
+    Center = "center",
+    /** O popover é alinhado ao final do eixo da posição (rodapé ou direita, conforme a `PoUserGuidePosition`). */
+    End = "end"
+}

package/lib/services/po-user-guide/enums/po-user-guide-position.enum.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @usedBy PoUserGuideService
+ *
+ * @description
+ *
+ * *Enum* que define a posição preferida do popover do tour em relação ao elemento destacado,
+ * utilizado na propriedade `position` de `PoUserGuideStep`.
+ *
+ * > Quando o valor não é informado, é aplicado o padrão `PoUserGuidePosition.Auto`.
+ */
+export declare enum PoUserGuidePosition {
+    /** O popover é renderizado acima do elemento destacado. */
+    Top = "top",
+    /** O popover é renderizado à direita do elemento destacado. */
+    Right = "right",
+    /** O popover é renderizado abaixo do elemento destacado. */
+    Bottom = "bottom",
+    /** O popover é renderizado à esquerda do elemento destacado. */
+    Left = "left",
+    /** O popover é renderizado sobreposto ao elemento destacado. */
+    Over = "over",
+    /** A posição é calculada automaticamente conforme o espaço disponível na viewport. */
+    Auto = "auto"
+}

package/lib/services/po-user-guide/index.d.ts

@@ -0,0 +1,6 @@
+export * from './po-user-guide-base.service';
+export * from './enums/index';
+export * from './interfaces/index';
+export * from './po-user-guide.literals';
+export * from './po-user-guide.module';
+export * from './po-user-guide.service';

package/lib/services/po-user-guide/interfaces/index.d.ts

@@ -0,0 +1,6 @@
+export * from './po-user-guide-end-event.interface';
+export * from './po-user-guide-literals.interface';
+export * from './po-user-guide-options.interface';
+export * from './po-user-guide-start-event.interface';
+export * from './po-user-guide-step-change-event.interface';
+export * from './po-user-guide-step.interface';

package/lib/services/po-user-guide/interfaces/po-user-guide-end-event.interface.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @usedBy PoUserGuideService
+ *
+ * @description
+ *
+ * Interface que descreve o evento emitido pelo `PoUserGuideService` no encerramento da execução de um tour guiado.
+ *
+ * É publicado no `Observable` `PoUserGuideService.tourEnd$` exatamente uma vez por execução, sempre após a
+ * emissão do último `PoUserGuideStepChangeEvent` em `PoUserGuideService.stepChange$` e após a limpeza do estado
+ * interno do serviço.
+ *
+ * As aplicações consumidoras podem assinar `tourEnd$` para registrar telemetria de conclusão ou de
+ * abandono do tour, executar limpezas de UI ou disparar lógica de negócio dependente do encerramento
+ * da jornada do usuário.
+ */
+export interface PoUserGuideEndEvent {
+    /**
+     * @description
+     *
+     * Motivo do encerramento do tour.
+     *
+     * Valores aceitos:
+     *
+     * - `completed`: o usuário avançou além do último passo do tour, concluindo a jornada por completo.
+     * - `closed`: o tour foi encerrado antes da conclusão, seja pelo usuário (tecla `Esc`, botão "Fechar"
+     *   ou clique fora do popover quando `PoUserGuideOptions.allowClose` está habilitado) ou pela aplicação
+     *   consumidora através das chamadas a `PoUserGuideService.close` ou `PoUserGuideService.exit`.
+     */
+    reason: 'completed' | 'closed';
+    /**
+     * @description
+     *
+     * Índice, com base zero, do último passo ativo antes do encerramento do tour.
+     *
+     * Quando `reason` é `'completed'`, corresponde ao índice do último passo da lista (`totalSteps - 1`).
+     * Quando `reason` é `'closed'`, corresponde ao índice do passo que estava em exibição
+     * no momento do encerramento.
+     */
+    lastIndex: number;
+    /**
+     * @description
+     *
+     * Total de passos configurados no tour, equivalente ao tamanho do array passado a `PoUserGuideService.setSteps`.
+     */
+    totalSteps: number;
+}

package/lib/services/po-user-guide/interfaces/po-user-guide-literals.interface.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @usedBy PoUserGuideService
+ *
+ * @description
+ *
+ * Interface para definição das literais usadas no `po-user-guide`.
+ */
+export interface PoUserGuideLiterals {
+    /** Label padrão do botão "Próximo" aplicado a todos os passos do tour. */
+    next?: string;
+    /** Label padrão do botão "Anterior" aplicado a todos os passos do tour. */
+    previous?: string;
+    /** Label padrão do botão "Finalizar" aplicado ao último passo do tour. */
+    done?: string;
+    /** Label padrão do botão "Fechar" (X) exibido no canto do popover do tour. */
+    close?: string;
+    /** Template padrão do texto de progresso exibido no popover (ex: `{ {current} } de { {total} }`). */
+    progressTemplate?: string;
+}

package/lib/services/po-user-guide/interfaces/po-user-guide-options.interface.d.ts

@@ -0,0 +1,195 @@
+import { PoUserGuideLiterals } from './po-user-guide-literals.interface';
+import { PoUserGuideStepChangeEvent } from './po-user-guide-step-change-event.interface';
+/**
+ * @usedBy PoUserGuideService
+ *
+ * @description
+ *
+ * Interface que descreve as opções globais de configuração do tour guiado executado pelo `PoUserGuideService`.
+ *
+ * Os valores informados são aplicados a toda a execução do tour e podem ser sobrescritos pontualmente
+ * em cada `PoUserGuideStep` através das propriedades específicas de *labels* (`nextLabel`, `previousLabel`,
+ * `doneLabel`) — neste caso, o valor declarado no passo prevalece sobre o valor declarado nas opções globais.
+ *
+ */
+export interface PoUserGuideOptions {
+    /**
+     * @optional
+     *
+     * @description
+     *
+     * Permite que o usuário encerre o tour clicando fora do popover ou utilizando o botão "Fechar" (X).
+     *
+     * Quando definido como `false`, o tour somente pode ser encerrado de forma programática (por exemplo,
+     * através do método `close()` do `PoUserGuideService`) ou ao avançar além do último passo.
+     *
+     * @default `true`
+     */
+    allowClose?: boolean;
+    /**
+     * @optional
+     *
+     * @description
+     *
+     * Quando `true`, mantém a rolagem da página totalmente livre durante o tour.
+     *
+     * O valor padrão `false` (ou a omissão da propriedade) preserva o comportamento padrão de
+     * bloqueio: a rolagem do `document.documentElement` e do `document.body` é desabilitada
+     * enquanto o tour estiver ativo e restaurada integralmente ao seu término.
+     *
+     * @default `false`
+     */
+    allowScroll?: boolean;
+    /**
+     * @optional
+     *
+     * @description
+     *
+     * Exibe o indicador textual de progresso do tour no popover (por exemplo, `1 de 5`).
+     *
+     * O texto pode ser personalizado através da propriedade `progressTemplate`.
+     *
+     * @default `true`
+     */
+    showProgress?: boolean;
+    /**
+     * @optional
+     *
+     * @description
+     *
+     * Habilita/desabilita o controle do tour por teclado (valor padrão: `true`).
+     * Se configurado como `false`, o controle por teclado é desabilitado.
+     *
+     * Quando ativo, são interpretadas as seguintes teclas:
+     *
+     * - `Esc`: encerra o tour (equivalente a `close()`).
+     * - `→` (seta para a direita) ou `Enter`: avança para o próximo passo (equivalente a `next()`).
+     * - `←` (seta para a esquerda): retrocede para o passo anterior (equivalente a `previous()`).
+     *
+     * @default `true`
+     */
+    keyboardControl?: boolean;
+    /**
+     * @optional
+     *
+     * @description
+     *
+     * Define a opacidade do *overlay* que escurece a página ao redor do elemento destacado.
+     *
+     * O valor deve estar contido no intervalo `[0, 1]`, sendo `0` totalmente transparente e `1` totalmente opaco.
+     * Valores fora deste intervalo são ajustados (*clamped*) para os limites mais próximos.
+     *
+     * @default `0.7`
+     */
+    overlayOpacity?: number;
+    /**
+     * @optional
+     *
+     * @description
+     *
+     * *Label* padrão do botão "Próximo" aplicado a todos os passos do tour.
+     *
+     * Pode ser sobrescrito individualmente por passo através de `PoUserGuideStep.nextLabel`.
+     *
+     * @default `Próximo`
+     */
+    nextLabel?: string;
+    /**
+     * @optional
+     *
+     * @description
+     *
+     * *Label* padrão do botão "Anterior" aplicado a todos os passos do tour.
+     *
+     * Pode ser sobrescrito individualmente por passo através de `PoUserGuideStep.previousLabel`.
+     *
+     * @default `Anterior`
+     */
+    previousLabel?: string;
+    /**
+     * @optional
+     *
+     * @description
+     *
+     * *Label* padrão do botão "Finalizar" aplicado ao último passo do tour.
+     *
+     * Pode ser sobrescrito individualmente por passo através de `PoUserGuideStep.doneLabel`.
+     *
+     * @default `Finalizar`
+     */
+    doneLabel?: string;
+    /**
+     * @optional
+     *
+     * @description
+     *
+     * *Label* padrão do botão "Fechar" (X) exibido no canto do popover do tour.
+     *
+     * @default `Fechar`
+     */
+    closeLabel?: string;
+    /**
+     * @optional
+     *
+     * @description
+     *
+     * Template do texto de progresso exibido no popover quando `showProgress` está habilitado.
+     *
+     * Aceita os seguintes *placeholders*, que são substituídos em tempo de renderização:
+     *
+     * - `current`: número do passo atual, com base 1 (ou seja, o primeiro passo é exibido como `1`).
+     * - `total`: número total de passos do tour.
+     *
+     * Quando o template informado não contém nenhum dos *placeholders* suportados, o texto é exibido
+     * literalmente e um aviso é registrado em `console.warn`.
+     *
+     * @default `{ {current} } de { {total} }`
+     */
+    progressTemplate?: string;
+    /**
+     * @optional
+     *
+     * @description
+     *
+     * Classe CSS adicional aplicada ao elemento raiz do popover do tour.
+     *
+     * Útil para customizações pontuais sem alterar o tema global do PO UI. A classe padrão `po-user-guide-popover`
+     * é sempre aplicada e preservada — o valor informado é concatenado a ela.
+     */
+    popoverClass?: string;
+    /**
+     * @optional
+     *
+     * @description
+     *
+     * Objeto com as literais usadas no `po-user-guide`.
+     *
+     * Permite customizar os textos dos botões de navegação e o template de progresso do tour.
+     * Quando omitido, as literais são traduzidas automaticamente de acordo com o idioma do
+     * [`PoI18nService`](/documentation/po-i18n) ou do browser.
+     *
+     * Exemplo passando apenas as literais que deseja customizar:
+     *
+     * ```
+     *  const customLiterals: PoUserGuideLiterals = {
+     *    next: 'Avançar',
+     *    done: 'Concluir'
+     *  };
+     * ```
+     */
+    literals?: PoUserGuideLiterals;
+    /**
+     * @optional
+     *
+     * @description
+     *
+     * Função de *callback* invocada a cada mudança de passo durante a execução do tour.
+     *
+     * Recebe como argumento um evento `PoUserGuideStepChangeEvent` contendo o passo ativo, seu índice, a direção
+     * da transição (`'next'`, `'previous'`, `'goto'` ou `'start'`) e o total de passos do tour.
+     *
+     * O *callback* é executado antes da emissão do evento correspondente em `PoUserGuideService.stepChange$`,
+     * permitindo a aplicação consumidora reagir à transição antes que outros assinantes do `Observable` sejam notificados.
+     */
+    onStepChange?: (event: PoUserGuideStepChangeEvent) => void;
+}

package/lib/services/po-user-guide/interfaces/po-user-guide-start-event.interface.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @usedBy PoUserGuideService
+ *
+ * @description
+ *
+ * Interface que descreve o evento emitido pelo `PoUserGuideService` no início da execução de um tour guiado.
+ *
+ * É publicado no `Observable` `PoUserGuideService.tourStart$` exatamente uma vez por execução, imediatamente
+ * após a configuração da instância do tour e antes da emissão do primeiro `PoUserGuideStepChangeEvent` em
+ * `PoUserGuideService.stepChange$`.
+ *
+ * As aplicações consumidoras podem assinar `tourStart$` para registrar telemetria do início do tour,
+ * exibir mensagens contextuais ou disparar lógica de negócio dependente do início da jornada do usuário.
+ */
+export interface PoUserGuideStartEvent {
+    /**
+     * @description
+     *
+     * Total de passos configurados no tour, equivalente ao tamanho do array passado a `PoUserGuideService.setSteps`.
+     */
+    totalSteps: number;
+    /**
+     * @description
+     *
+     * Índice do passo inicial do tour, com base zero.
+     *
+     * Corresponde ao argumento `startIndex` informado a `PoUserGuideService.start`. Quando o método é invocado
+     * sem argumentos, o valor é `0`.
+     */
+    startIndex: number;
+    /**
+     * @description
+     *
+     * Marca de tempo, em milissegundos, do momento de emissão do evento, obtida a partir de `Date.now()`.
+     *
+     * Útil para correlacionar o início do tour com outros eventos de telemetria da aplicação.
+     */
+    timestamp: number;
+}

package/lib/services/po-user-guide/interfaces/po-user-guide-step-change-event.interface.d.ts

@@ -0,0 +1,54 @@
+import { PoUserGuideStep } from './po-user-guide-step.interface';
+/**
+ * @usedBy PoUserGuideService
+ *
+ * @description
+ *
+ * Interface que descreve o evento emitido pelo `PoUserGuideService` a cada mudança de passo durante a execução do tour.
+ *
+ * É publicado no `Observable` `PoUserGuideService.stepChange$` toda vez que o passo ativo é alterado, seja por
+ * interação do usuário (cliques nos botões "Próximo"/"Anterior" ou navegação por teclado) ou por chamada
+ * programática aos métodos `next`, `previous`, `goTo` e `start` do `PoUserGuideService`.
+ *
+ * As aplicações consumidoras podem assinar `stepChange$` para reagir à navegação do usuário, atualizar a
+ * UI conforme o passo ativo, registrar telemetria de progresso ou disparar lógica de negócio contextual.
+ */
+export interface PoUserGuideStepChangeEvent {
+    /**
+     * @description
+     *
+     * Passo do tour que se tornou ativo após a transição.
+     *
+     * Corresponde ao elemento da lista `steps` (configurada via `PoUserGuideService.setSteps`) cujo índice é
+     * igual ao valor de `index` neste evento.
+     */
+    step: PoUserGuideStep;
+    /**
+     * @description
+     *
+     * Índice, com base zero, do passo ativo após a transição.
+     *
+     * Está sempre contido no intervalo `[0, totalSteps - 1]`.
+     */
+    index: number;
+    /**
+     * @description
+     *
+     * Direção da transição que originou a mudança de passo.
+     *
+     * Valores aceitos:
+     *
+     * - `next`: a transição foi originada pelo método `PoUserGuideService.next` ou pelo botão "Próximo" do popover.
+     * - `previous`: a transição foi originada pelo método `PoUserGuideService.previous` ou pelo botão "Anterior" do popover.
+     * - `goto`: a transição foi originada pela chamada ao método `PoUserGuideService.goTo` com um índice arbitrário.
+     * - `start`: a transição corresponde à exibição do primeiro passo logo após a inicialização do tour
+     *   pelo método `PoUserGuideService.start`.
+     */
+    direction: 'next' | 'previous' | 'goto' | 'start';
+    /**
+     * @description
+     *
+     * Total de passos configurados no tour, equivalente ao tamanho do array passado a `PoUserGuideService.setSteps`.
+     */
+    totalSteps: number;
+}