@po-ui/ng-components 21.16.0 → 21.17.0-beta.1

package/lib/services/po-user-guide/po-user-guide-scroll-lock.d.ts

@@ -0,0 +1,55 @@
+export interface ScrollLockSnapshot {
+    scrollX: number;
+    scrollY: number;
+    scrollbarWidth: number;
+    documentElement: {
+        overflow: string;
+        overflowX: string;
+        overflowY: string;
+        position: string;
+        top: string;
+        left: string;
+        width: string;
+        paddingRight: string;
+    };
+    body: {
+        overflow: string;
+        overflowX: string;
+        overflowY: string;
+        position: string;
+        top: string;
+        left: string;
+        width: string;
+        paddingRight: string;
+    };
+}
+export type ScrollLockMode = 'blocked' | 'free';
+export declare const SCROLL_KEYS: ReadonlySet<string>;
+export declare function resolveScrollLockMode(options?: {
+    allowScroll?: unknown;
+} | null): ScrollLockMode;
+/**
+ * @internal
+ *
+ * Classe interna do PoUserGuideService responsável por congelar o scroll do navegador
+ * (`document.documentElement` e `document.body`) durante o
+ * ciclo de vida de um tour conduzido pelo `driver.js` e por restaurar o estado original
+ * de forma síncrona em qualquer caminho de saída.
+ *
+ */
+export declare class PoUserGuideScrollLock {
+    private active;
+    private snapshot;
+    private wheelListener;
+    private touchListener;
+    private keydownListener;
+    isActive(): boolean;
+    lock(): void;
+    unlock(): void;
+    private isBrowser;
+    private captureSnapshot;
+    private applyLockStyles;
+    private restoreSnapshot;
+    private isScrollKey;
+    private isWithinEditableInPopover;
+}

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

@@ -0,0 +1,7 @@
+import { PoUserGuideLiterals } from './interfaces/po-user-guide-literals.interface';
+export declare const poUserGuideLiteralsDefault: {
+    en: PoUserGuideLiterals;
+    es: PoUserGuideLiterals;
+    pt: PoUserGuideLiterals;
+    ru: PoUserGuideLiterals;
+};

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

@@ -0,0 +1,2 @@
+export declare class PoUserGuideModule {
+}

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

@@ -0,0 +1,174 @@
+import { DomSanitizer } from '@angular/platform-browser';
+import { PoLanguageService } from '../../services/po-language/po-language.service';
+import { PoUserGuideBaseService } from './po-user-guide-base.service';
+import { PoUserGuideOptions, PoUserGuideStep } from './interfaces';
+/**
+ * @docsExtends PoUserGuideBaseService
+ *
+ * @example
+ *
+ * <example name="po-user-guide-basic" title="PO User Guide Basic">
+ *  <file name="sample-po-user-guide-basic/sample-po-user-guide-basic.component.html"> </file>
+ *  <file name="sample-po-user-guide-basic/sample-po-user-guide-basic.component.ts"> </file>
+ * </example>
+ *
+ * <example name="po-user-guide-labs" title="PO User Guide Labs">
+ *  <file name="sample-po-user-guide-labs/sample-po-user-guide-labs.component.html"> </file>
+ *  <file name="sample-po-user-guide-labs/sample-po-user-guide-labs.component.ts"> </file>
+ * </example>
+ *
+ * <example name="po-user-guide-onboarding" title="PO User Guide - Onboarding">
+ *  <file name="sample-po-user-guide-onboarding/sample-po-user-guide-onboarding.component.html"> </file>
+ *  <file name="sample-po-user-guide-onboarding/sample-po-user-guide-onboarding.component.ts"> </file>
+ * </example>
+ */
+export declare class PoUserGuideService extends PoUserGuideBaseService {
+    private readonly sanitizer;
+    private driverFactoryCache;
+    private driverInstance;
+    private pendingEndReason;
+    private readonly scrollLock;
+    private activeScrollLockEnabled;
+    private static stylesInjected;
+    constructor(languageService: PoLanguageService, sanitizer: DomSanitizer);
+    private isBrowser;
+    protected importDriver(): Promise<any>;
+    private loadDriverFactory;
+    private injectStyles;
+    private sanitizeText;
+    private mapStepsToDriveSteps;
+    private handlePopoverRender;
+    private focusPopoverDescription;
+    private applyDoneButtonLabel;
+    private applyPoButtonStyles;
+    /**
+     * Substitui o `&times;` nativo do Driver.js pelo ícone de fechar do PO UI (`ICON_CLOSE`).
+     *
+     * O ícone é referenciado pela classe da fonte (`an an-x`) via `AnimaliaIconDictionary`,
+     * evitando duplicar o codepoint da fonte Animalia diretamente no CSS.
+     */
+    private applyCloseButtonIcon;
+    private buildDriverConfig;
+    private handleHighlightStarted;
+    private resolveActiveIndex;
+    private resolveShowButtons;
+    private handleDestroyed;
+    private handleCloseClick;
+    /**
+     * @description
+     *
+     * Configura a lista de passos que serão exibidos durante a execução do tour guiado.
+     *
+     * @param {Array<PoUserGuideStep>} steps Lista de passos do tour a ser configurada. Deve conter ao menos um
+     * passo válido com a propriedade `content` definida.
+     *
+     * @returns {this} A própria instância do serviço, possibilitando o encadeamento fluente de chamadas.
+     *
+     * @throws {Error} Quando `steps` é `null`, `undefined`, não é um `Array`, está vazio, contém um passo
+     * inválido, contém um passo sem a propriedade `content` definida ou contém um passo cujo `element` é
+     * uma string com sintaxe de seletor CSS inválida.
+     */
+    setSteps(steps: Array<PoUserGuideStep>): this;
+    /**
+     * @description
+     *
+     * Configura as opções globais que serão aplicadas durante a execução do tour guiado.
+     *
+     * @param {PoUserGuideOptions} [options] Objeto com as opções globais do tour a ser configurado. Quando
+     * omitido ou `undefined`, apenas os valores padrão do PO UI são aplicados.
+     *
+     * @returns {this} A própria instância do serviço, possibilitando o encadeamento fluente de chamadas.
+     */
+    setOptions(options?: PoUserGuideOptions): this;
+    /**
+     * @description
+     *
+     * Inicia a execução do tour previamente configurado por meio de `setSteps` e, opcionalmente, `setOptions`.
+     *
+     * @override
+     *
+     * @param {number} [startIndex=0] Índice, com base zero, do passo a partir do qual o tour deve iniciar.
+     * Deve ser um inteiro contido no intervalo `[0, steps.length - 1]`.
+     *
+     * @throws {Error} Quando a lista de passos ainda não foi configurada via `setSteps` ou está vazia.
+     * @throws {Error} Quando `startIndex` não é um número inteiro contido em `[0, steps.length - 1]`.
+     *
+     * @returns {Promise<void>} `Promise` que é resolvida quando o tour é iniciado com sucesso e
+     * rejeitada com um `Error` de mensagem padronizada quando ocorre falha na carga da dependência
+     * `driver.js` ou na inicialização do tour.
+     */
+    start(startIndex?: number): Promise<void>;
+    /**
+     * @description
+     *
+     * Encerra o tour em execução, disparando, em sequência, o ciclo de limpeza de estado e a emissão de
+     * `tourEnd$`.
+     *
+     * @override
+     */
+    close(): void;
+    /**
+     * @description
+     *
+     * Encerra o tour em execução.
+     *
+     * @override
+     */
+    exit(): void;
+    /**
+     * @description
+     *
+     * Avança o tour em execução para o próximo passo.
+     *
+     * @override
+     */
+    next(): void;
+    /**
+     * @description
+     *
+     * Retrocede o tour em execução para o passo anterior.
+     *
+     * @override
+     */
+    previous(): void;
+    /**
+     * @description
+     *
+     * Move o tour diretamente para o passo identificado pelo `index` informado, que deve ser um número inteiro contido em `[0, steps.length - 1]`. Se o tour ainda não estiver em execução, o método inicia o tour a partir do passo indicado por `index`.
+     *
+     * @override
+     *
+     * @param {number} index Índice, com base zero, do passo de destino. Deve ser um inteiro contido
+     * em `[0, steps.length - 1]`.
+     *
+     * @throws {Error} Quando `index` não é um número inteiro contido em `[0, steps.length - 1]`.
+     */
+    goTo(index: number): void;
+    /**
+     * @description
+     *
+     * Indica se há um tour em execução no momento da consulta.
+     *
+     * @returns {boolean} `true` quando existe um tour em execução; `false` em qualquer outro caso (antes do primeiro `start()`,
+     * após `close()`/`exit()` ou após o encerramento natural do tour).
+     */
+    isActive(): boolean;
+    /**
+     * @description
+     *
+     * Retorna o `PoUserGuideStep` correspondente ao passo ativo no momento da consulta.
+     *
+     * @returns {PoUserGuideStep | null} O passo ativo, quando há um tour em execução; `null` em qualquer
+     * outro caso.
+     */
+    getCurrentStep(): PoUserGuideStep | null;
+    /**
+     * @description
+     *
+     * Retorna o índice, com base zero, do passo ativo no momento da consulta.
+     *
+     * @returns {number} O índice, com base zero, do passo ativo, contido em `[0, steps.length - 1]`,
+     * quando há um tour em execução; `-1` em qualquer outro caso.
+     */
+    getCurrentIndex(): number;
+}

package/lib/utils/safe-text-parser.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Parser seguro de tags de formatação (`<b>`, `<strong>`, `<i>`, `<em>`, `<u>`).
+ * Não utiliza `innerHTML`. Tags fora da whitelist são removidas (proteção XSS).
+ */
+/** Fragmento de texto com flags de formatação. */
+export interface PoTextFragment {
+    text: string;
+    bold: boolean;
+    italic: boolean;
+    underline: boolean;
+}
+/** Tags de formatação suportadas. */
+export type PoFormattingTag = 'b' | 'i' | 'u' | 'strong' | 'em';
+/**
+ * Faz o parsing seguro de uma string com tags de formatação.
+ *
+ * O consumidor declara quais tags aceita via `allowedTags` (obrigatório).
+ * Tags não listadas são removidas. Tags aninhadas são suportadas.
+ *
+ * @param content String com possíveis tags de formatação.
+ * @param allowedTags Tags permitidas pelo consumidor.
+ */
+export declare function parseSafeText(content: string, allowedTags: Array<PoFormattingTag>): Array<PoTextFragment>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@po-ui/ng-components",
-  "version": "21.16.0",
+  "version": "21.17.0-beta.1",
   "description": "PO UI - Components",
   "author": "PO UI",
   "license": "MIT",
@@ -22,8 +22,9 @@
   },
   "dependencies": {
     "@angular/cdk": "~21.2.4",
-    "@po-ui/style": "21.16.0",
-    "@po-ui/ng-schematics": "21.16.0",
+    "@po-ui/style": "21.17.0-beta.1",
+    "@po-ui/ng-schematics": "21.17.0-beta.1",
+    "driver.js": "~1.4.0",
     "echarts": "^5.6.0",
     "tslib": "^2.6.2"
   },
@@ -38,7 +39,7 @@
     "@angular/platform-browser-dynamic": "^21",
     "@angular/router": "^21",
     "@angular-devkit/schematics": "^21",
-    "@po-ui/style": "21.16.0",
+    "@po-ui/style": "21.17.0-beta.1",
     "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', '21.16.0');
+        (0, package_config_1.addPackageToPackageJson)(tree, '@po-ui/ng-components', '21.17.0-beta.1');
         // 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)('21.16.0', changes_1.updateDepedenciesVersion), postUpdate()]);
+    return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('21.17.0-beta.1', 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)('21.16.0', changes_1.updateDepedenciesVersion), createUpgradeRule(), postUpdate()]);
+    return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('21.17.0-beta.1', 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)('21.16.0', changes_1.updateDepedenciesVersion), postUpdate()]);
+    return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('21.17.0-beta.1', 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)('21.16.0', changes_1.updateDepedenciesVersion), postUpdate()]);
+    return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('21.17.0-beta.1', 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)('21.16.0', changes_1.updateDepedenciesVersion), createUpgradeRule(), postUpdate()]);
+            return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('21.17.0-beta.1', changes_1.updateDepedenciesVersion), createUpgradeRule(), postUpdate()]);
         }
         else {
             return (0, schematics_1.chain)([
-                (0, package_config_1.updatePackageJson)('21.16.0', changes_1.updateDepedenciesVersion),
+                (0, package_config_1.updatePackageJson)('21.17.0-beta.1', 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)('21.16.0', changes_1.updateDepedenciesVersion), createUpgradeRule(), postUpdate()]);
+            return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('21.17.0-beta.1', changes_1.updateDepedenciesVersion), createUpgradeRule(), postUpdate()]);
         }
         else {
             return (0, schematics_1.chain)([
-                (0, package_config_1.updatePackageJson)('21.16.0', changes_1.updateDepedenciesVersion),
+                (0, package_config_1.updatePackageJson)('21.17.0-beta.1', 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('21.16.0', changes_1.dependeciesChanges),
+        updatePackageJson('21.17.0-beta.1', 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)('21.16.0', changes_1.updateDepedenciesVersion), createUpgradeRule(), postUpdate()]);
+            return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('21.17.0-beta.1', changes_1.updateDepedenciesVersion), createUpgradeRule(), postUpdate()]);
         }
         else {
             return (0, schematics_1.chain)([
-                (0, package_config_1.updatePackageJson)('21.16.0', changes_1.updateDepedenciesVersion),
+                (0, package_config_1.updatePackageJson)('21.17.0-beta.1', changes_1.updateDepedenciesVersion),
                 addImportOnly(options, [IconsDictionaryName, poIconDictionary], poModuleSourcePath),
                 addProviderToAppModule(options, newProviderDictionary),
                 updateAppConfigFileRule(),

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

@@ -9,7 +9,7 @@ const project_1 = require("@po-ui/ng-schematics/project");
 const changes_1 = require("./changes");
 function main() {
     return tslib_1.__awaiter(this, void 0, void 0, function* () {
-        return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('21.16.0', changes_1.updateDepedenciesVersion), createUpgradeRule(), postUpdate()]);
+        return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('21.17.0-beta.1', changes_1.updateDepedenciesVersion), createUpgradeRule(), postUpdate()]);
     });
 }
 function default_1() {

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)('21.16.0', changes_1.updateDepedenciesVersion), createUpgradeRule(), postUpdate()]);
+    return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('21.17.0-beta.1', 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)('21.16.0', changes_1.updateDepedenciesVersion), createUpgradeRule(), postUpdate()]);
+    return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('21.17.0-beta.1', 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)('21.16.0', changes_1.updateDepedenciesVersion), createUpgradeRule(), postUpdate()]);
+    return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('21.17.0-beta.1', 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)('21.16.0', changes_1.updateDepedenciesVersion), postUpdate()]);
+    return (0, schematics_1.chain)([(0, package_config_1.updatePackageJson)('21.17.0-beta.1', changes_1.updateDepedenciesVersion), postUpdate()]);
 }
 function postUpdate() {
     return (_, context) => {