feat(user-guide): implementa serviço po-user-guide

Adiciona o PoUserGuideService para criação e controle de guias de usuário na aplicação.

O novo serviço permite configurar passos, definir opções globais e iniciar a execução de um guia de forma encadeada. Também disponibiliza eventos reativos para acompanhar o ciclo de vida do guia, como início, troca de passo e finalização.

Inclui a estrutura base do serviço, opções de configuração, definição dos passos e integração com o módulo de serviços do PO-UI.

Fixes DTHFUI-12986

Author: pedrodominguesp

.gitignore

@@ -25,6 +25,7 @@ speed-measure-plugin.json
 .settings/
 *.sublime-workspace
 .vscode
+.kiro
 
 # IDE - VSCode
 .vscode

package.json

@@ -81,6 +81,7 @@
     "@capacitor/network": "^5.0.7",
     "@po-ui/style": "21.17.0",
     "custom-idle-queue": "4.0.0",
+    "driver.js": "^1.4.0",
     "echarts": "^5.6.0",
     "http-status-codes": "^2.3.0",
     "localforage": "1.10.0",
@@ -124,6 +125,7 @@
     "eslint-plugin-prefer-arrow": "latest",
     "eslint-plugin-react": "latest",
     "eslint-plugin-sonarjs": "latest",
+    "fast-check": "4.8.0",
     "gulp": "^5.0.1",
     "gulp-clean": "^0.4.0",
     "gulp-tap": "^2.0.0",

projects/portal/docs/templates/samples/index.template.html

@@ -18,7 +18,7 @@
       <div>
         {% for script in doc.scripts %}
         <label class="doc-label-path">{$ script.path $}</label>
-        <pre appCodeHighlight class="typescript">{$ script.fileContents | escape | replace("{", "&#123;") | replace("@", "&#64;") | replace('}', "&#125;") $}</pre> 
+        <pre appCodeHighlight class="typescript">{$ script.fileContents | escape | replace('{{', "&#123; &#123;") | replace('}}', "&#125; &#125;") | replace("{", "&#123;") | replace("@", "&#64;") | replace('}', "&#125;") $}</pre>
         {% endfor %}
       </div>
     </po-tab>
@@ -27,7 +27,7 @@
       <div>
         {% for stylesheet in doc.stylesheets %}
         <label class="doc-label-path">{$ stylesheet.path $}</label>
-        <pre appCodeHighlight class="css">{$ stylesheet.fileContents | escape | replace("{", "&#123;") | replace("@", "&#64;") | replace('}', "&#125;") $}</pre> {% endfor %}
+        <pre appCodeHighlight class="css">{$ stylesheet.fileContents | escape | replace('{{', "&#123; &#123;") | replace('}}', "&#125; &#125;") | replace("{", "&#123;") | replace("@", "&#64;") | replace('}', "&#125;") $}</pre> {% endfor %}
       </div>
     </po-tab>
     {%- endif -%}
@@ -36,7 +36,7 @@
       <div>
         {% for test in doc.tests %}
         <label class="doc-label-path">{$ test.path $}</label>
-        <pre appCodeHighlight class="test">{$ test.fileContents | escape | replace("{", "&#123;") | replace("@", "&#64;") | replace('}', "&#125;") $}</pre> {% endfor %}
+        <pre appCodeHighlight class="test">{$ test.fileContents | escape | replace('{{', "&#123; &#123;") | replace('}}', "&#125; &#125;") | replace("{", "&#123;") | replace("@", "&#64;") | replace('}', "&#125;") $}</pre> {% endfor %}
       </div>
     </po-tab>
     {%- endif -%}

projects/ui/ng-package.json

@@ -4,5 +4,5 @@
   "lib": {
     "entryFile": "./src/public-api.ts"
   },
-  "allowedNonPeerDependencies": ["@angular/cdk", "@po-ui/style", "@po-ui/ng-schematics", "echarts"]
+  "allowedNonPeerDependencies": ["@angular/cdk", "@po-ui/style", "@po-ui/ng-schematics", "echarts", "driver.js"]
 }

projects/ui/package.json

@@ -24,6 +24,7 @@
     "@angular/cdk": "~21.2.4",
     "@po-ui/style": "0.0.0-PLACEHOLDER",
     "@po-ui/ng-schematics": "0.0.0-PLACEHOLDER",
+    "driver.js": "^1.4.0",
     "echarts": "^5.6.0",
     "tslib": "^2.6.2"
   },

projects/ui/src/lib/services/index.ts

@@ -11,3 +11,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';

projects/ui/src/lib/services/po-theme/helpers/types/po-theme-dark-defaults.constant.ts

@@ -218,6 +218,7 @@ const poThemeDefaultDarkValues = {
     '--color-black-alpha-10': 'rgba(255, 255, 255, 0.1)',
     '--color-black-alpha-15': 'rgba(255, 255, 255, 0.15)',
     '--color-black-alpha-30': 'rgba(255, 255, 255, 0.3)',
+    '--color-po-user-guide-overlay': 'var(--color-neutral-light-20)',
     '--color-primary-light-80': 'color-mix(in srgb, var(--color-brand-02-base) 80%, black)',
     '--color-primary-light-95': 'color-mix(in srgb, var(--color-brand-02-base) 95%, black)',
     '--color-primary-alpha-50': 'color-mix(in srgb, var(--color-brand-02-base) 50%, white)',

projects/ui/src/lib/services/po-user-guide/enums/index.ts

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

projects/ui/src/lib/services/po-user-guide/enums/po-user-guide-alignment.enum.ts

@@ -0,0 +1,20 @@
+/**
+ * @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 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'
+}

projects/ui/src/lib/services/po-user-guide/enums/po-user-guide-position.enum.ts

@@ -0,0 +1,29 @@
+/**
+ * @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 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'
+}