@praxisui/stepper 1.0.0-beta.48 → 1.0.0-beta.52

package/README.md

@@ -1,3 +1,45 @@
+---
+title: "Stepper"
+slug: "stepper-overview"
+description: "Visao geral do @praxisui/stepper com fluxo multi-etapas, persistencia por stepperId, integracao com dynamic-form e editor embutido."
+doc_type: "reference"
+document_kind: "component-overview"
+component: "stepper"
+category: "components"
+audience:
+  - "frontend"
+  - "host"
+  - "architect"
+level: "intermediate"
+status: "active"
+owner: "praxis-ui"
+tags:
+  - "stepper"
+  - "wizard"
+  - "dynamic-form"
+  - "settings-panel"
+  - "metadata"
+order: 36
+icon: "list-todo"
+toc: true
+sidebar: true
+search_boost: 1.0
+reading_time: 12
+estimated_setup_time: 20
+version: "1.0"
+related_docs:
+  - "stepper-api-reference"
+  - "host-stepper-integration"
+  - "consumer-integration-quickstart"
+  - "host-integration-guide"
+keywords:
+  - "praxis stepper"
+  - "wizard form"
+  - "stepper metadata"
+  - "stepperId persistence"
+last_updated: "2026-03-07"
+---
+
 # @praxisui/stepper
 
 ## 🔰 Exemplos / Quickstart
@@ -112,7 +154,7 @@ export class CadastroComponent {
       {
         id: 'endereco',
         label: 'Endereço',
-        form: { resourcePath: 'enderecos', mode: 'create' },
+        form: { resourcePath: 'human-resources/enderecos', mode: 'create' },
       },
     ],
   };
@@ -121,6 +163,9 @@ export class CadastroComponent {
 
 Validação: em modo `linear`, o avanço bloqueia quando o formulário da etapa atual é inválido. Para validação remota, forneça `(serverValidate)` ao componente.
 
+Observação sobre `resourcePath`:
+- use o caminho base canônico do recurso, sem `/api`, `/filter` ou `/{id}`. Ex.: `human-resources/funcionarios`.
+
 ```html
 <praxis-stepper stepperId="stepper-demo"
   [config]="config"
@@ -148,7 +193,7 @@ validateStep = async ({ step, formGroup, formData }) => {
 O `PraxisWizardFormComponent` é um wrapper experimental que traduz um JSON de wizard em `StepperMetadata` + `FormConfig` e aplica um layout inspirado no Financial Times.
 
 ```ts
-import { PraxisWizardFormComponent, FT_WIZARD_CONFIG } from '@praxisui/stepper/experimental';
+import { PraxisWizardFormComponent, FT_WIZARD_CONFIG } from '@praxisui/stepper';
 
 @Component({
   selector: 'app-ft-wizard',
@@ -168,6 +213,8 @@ Notas:
 - Cada bloco pode definir `id` (string) para gerar `blockId` estável em runtime; sem `id`, o fallback usa índice posicional.
 - `blocks` e `zones` são mutuamente exclusivos no contrato. Se ambos forem enviados, `zones` tem prioridade no runtime.
 - O wizard faz validação runtime (campos essenciais e exclusividade de `blocks`/`zones`). Em `devMode`, lança erro para facilitar o debug; em produção, emite `console.warn`.
+- A CTA primária reaproveita a validação do `PraxisStepper` interno; em `submit`, a etapa atual também é validada antes da emissão.
+- `cta.action = 'custom'` emite `(customAction)` no wizard para orquestração externa do host.
 - Preset visual recomendado para FT-like: `appearance.preset = 'ft-light'` (aplicado automaticamente no wizard).
 
 ## Tokens de tema (Wizard)
@@ -195,8 +242,8 @@ Tokens disponíveis:
 - A persistência de progresso e preferências usa `CONFIG_STORAGE` (localStorage por padrão).
 - JSON Schema: `projects/praxis-stepper/src/lib/wizard/praxis-wizard-form.schema.json`.
 - Personalização de cor do stepper (sem hardcode): ajuste `--praxis-wizard-accent` no host ou em `:root` para controlar o estado ativo/concluído.
+- `appearance.tokens` aplica variáveis CSS diretamente no host do stepper; use nomes com ou sem prefixo `--`.
 - Para evitar `::ng-deep`, use `stepperClass` e `contentClass` no metadata e aplique estilos em um stylesheet global do app (ou em presets internos da lib).
-- O import `@praxisui/stepper/experimental` é resolvido via `tsconfig` no workspace e não faz parte do pacote público publicado.
 
 ```scss
 :root {

package/fesm2022/praxisui-stepper.mjs

@@ -1,7 +1,7 @@
 import * as i1$1 from '@angular/common';
 import { CommonModule } from '@angular/common';
 import * as i0 from '@angular/core';
-import { Inject, Component, inject, signal, EventEmitter, computed, TemplateRef, Output, Input, ContentChild, ChangeDetectionStrategy, ENVIRONMENT_INITIALIZER, isDevMode, ElementRef, Renderer2, effect, ViewChild } from '@angular/core';
+import { Inject, Component, inject, signal, ElementRef, Renderer2, EventEmitter, computed, TemplateRef, Output, Input, ContentChild, ChangeDetectionStrategy, ENVIRONMENT_INITIALIZER, isDevMode, effect, ViewChild } from '@angular/core';
 import { ActivatedRoute } from '@angular/router';
 import * as i2$1 from '@angular/material/stepper';
 import { MatStepperModule } from '@angular/material/stepper';
@@ -2923,6 +2923,10 @@ class PraxisStepper {
     _selectedIndex = signal(0, ...(ngDevMode ? [{ debugName: "_selectedIndex" }] : []));
     _formGroups = new Map();
     _formValidity = new Map();
+    hostElement = inject((ElementRef));
+    renderer = inject(Renderer2);
+    appliedHeaderClasses = [];
+    appliedTokenNames = [];
     // CTA models for empty state
     primaryCta = { label: 'Configurar Stepper', icon: 'tune', color: 'primary', action: () => this.openEditor() };
     secondaryCtas = [{ label: 'Adicionar etapa inicial', icon: 'add', action: () => this.addFirstStep() }];
@@ -2946,6 +2950,7 @@ class PraxisStepper {
         if (next?.selectedIndex != null)
             this._selectedIndex.set(next.selectedIndex);
         this.persistConfig(next);
+        this.scheduleDomSync();
     }
     set selectedIndexInput(i) {
         if (i != null)
@@ -3010,7 +3015,6 @@ class PraxisStepper {
         return [
             'praxis-stepper',
             cfg?.stepperClass,
-            cfg?.headerClass,
             cfg?.appearance?.themeClass,
             cfg?.appearance?.preset === 'ft-light' ? 'pdx-stepper-ft-light' : null,
         ].filter(Boolean).join(' ');
@@ -3138,6 +3142,7 @@ class PraxisStepper {
                 const sel = typeof cloned.selectedIndex === 'number' ? cloned.selectedIndex : this._selectedIndex();
                 this._selectedIndex.set(this.clampIndex(sel));
                 this.persistConfig(cloned);
+                this.scheduleDomSync();
             }
         };
         ref.applied$.subscribe(apply);
@@ -3149,6 +3154,7 @@ class PraxisStepper {
         const sel = typeof cloned.selectedIndex === 'number' ? cloned.selectedIndex : this._selectedIndex();
         this._selectedIndex.set(this.clampIndex(sel));
         this.persistConfig(cloned);
+        this.scheduleDomSync();
     }
     // CTA helpers
     addFirstStep() {
@@ -3165,9 +3171,13 @@ class PraxisStepper {
         // Seleciona a primeira etapa
         this._selectedIndex.set(0);
         this.persistConfig(next);
+        this.scheduleDomSync();
     }
     // Navegação com validação remota opcional
     async onNext(i) {
+        await this.nextWithValidation(i);
+    }
+    async validateStep(i = this.selectedIndexComputed()) {
         // Em modo linear, bloquear quando inválido
         if (this.linear() && this._formValidity.get(i) === false) {
             const fg = this._formGroups.get(i);
@@ -3175,9 +3185,12 @@ class PraxisStepper {
                 fg.markAllAsTouched();
                 fg.updateValueAndValidity({ emitEvent: true });
             }
-            return;
+            return false;
         }
         const step = this.steps()[i];
+        if (!step) {
+            return true;
+        }
         const fg = this._formGroups.get(i);
         const data = fg?.getRawValue();
         if (this.serverValidate) {
@@ -3187,10 +3200,18 @@ class PraxisStepper {
                 // Atualizar erro visual
                 step.errorMessage = res.errorMessage || (res.formErrors && res.formErrors[0]) || 'Erro de validação';
                 this._formValidity.set(i, false);
-                return;
+                return false;
             }
         }
+        return true;
+    }
+    async nextWithValidation(i = this.selectedIndexComputed()) {
+        const isValid = await this.validateStep(i);
+        if (!isValid) {
+            return false;
+        }
         this.next();
+        return true;
     }
     onPrev() { this.prev(); }
     onAnimationDone() { this.animationDone.emit(); }
@@ -3263,8 +3284,51 @@ class PraxisStepper {
             this._config.set(cloned);
             const sel = typeof cloned.selectedIndex === 'number' ? cloned.selectedIndex : this._selectedIndex();
             this._selectedIndex.set(this.clampIndex(sel));
+            this.scheduleDomSync();
+        });
+    }
+    ngAfterViewInit() {
+        this.scheduleDomSync();
+    }
+    scheduleDomSync() {
+        queueMicrotask(() => {
+            this.syncAppearanceTokens();
+            this.syncHeaderClasses();
         });
     }
+    syncAppearanceTokens() {
+        const host = this.hostElement.nativeElement;
+        const nextTokens = this._config()?.appearance?.tokens ?? {};
+        const nextTokenNames = new Set(Object.keys(nextTokens).map((name) => this.resolveCssTokenName(name)));
+        this.appliedTokenNames
+            .filter((name) => !nextTokenNames.has(name))
+            .forEach((name) => this.renderer.removeStyle(host, name));
+        Object.entries(nextTokens).forEach(([name, value]) => {
+            this.renderer.setStyle(host, this.resolveCssTokenName(name), value);
+        });
+        this.appliedTokenNames = [...nextTokenNames];
+    }
+    syncHeaderClasses() {
+        const host = this.hostElement.nativeElement;
+        const nextClasses = this.parseClassList(this._config()?.headerClass);
+        const targets = host.querySelectorAll('.mat-step-header, .mat-horizontal-stepper-header-container');
+        targets.forEach((target) => {
+            this.appliedHeaderClasses
+                .filter((className) => !nextClasses.includes(className))
+                .forEach((className) => this.renderer.removeClass(target, className));
+            nextClasses.forEach((className) => this.renderer.addClass(target, className));
+        });
+        this.appliedHeaderClasses = nextClasses;
+    }
+    parseClassList(value) {
+        return (value ?? '')
+            .split(/\s+/)
+            .map((className) => className.trim())
+            .filter(Boolean);
+    }
+    resolveCssTokenName(name) {
+        return name.startsWith('--') ? name : `--${name}`;
+    }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.17", ngImport: i0, type: PraxisStepper, deps: [], target: i0.ɵɵFactoryTarget.Component });
     static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "20.3.17", type: PraxisStepper, isStandalone: true, selector: "praxis-stepper", inputs: { stepperId: "stepperId", componentInstanceId: "componentInstanceId", config: "config", selectedIndexInput: "selectedIndexInput", selectedIndex: "selectedIndex", disableRippleInput: "disableRippleInput", editModeEnabled: "editModeEnabled", labelPosition: "labelPosition", color: "color", serverValidate: "serverValidate", stepperContext: "stepperContext" }, outputs: { selectedIndexChange: "selectedIndexChange", widgetEvent: "widgetEvent", stepFormReady: "stepFormReady", stepFormValueChange: "stepFormValueChange", animationDone: "animationDone", selectionChange: "selectionChange" }, host: { properties: { "class": "densityClass()" } }, queries: [{ propertyName: "stepLabelTpl", first: true, predicate: ["stepLabelTpl"], descendants: true, read: TemplateRef }], ngImport: i0, template: `
     <div class="stepper-ai-assistant" *ngIf="editModeEnabled">
@@ -3272,6 +3336,7 @@ class PraxisStepper {
     </div>
     <ng-container *ngIf="steps().length > 0; else emptyState">
     <mat-stepper
+      #stepperRoot
       [linear]="linear()"
       [orientation]="orientation()"
       [headerPosition]="headerPosition()"
@@ -3429,6 +3494,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImpo
     </div>
     <ng-container *ngIf="steps().length > 0; else emptyState">
     <mat-stepper
+      #stepperRoot
       [linear]="linear()"
       [orientation]="orientation()"
       [headerPosition]="headerPosition()"
@@ -3797,22 +3863,20 @@ const PRAXIS_STEPPER_COMPONENT_METADATA = {
     inputs: [
         { name: 'stepperId', type: 'string', label: 'ID do Stepper', description: 'Identificador para persistência (obrigatório)' },
         { name: 'componentInstanceId', type: 'string', label: 'ID da instância', description: 'Identificador opcional para múltiplas instâncias na mesma rota' },
-        { name: 'config', type: 'StepperMetadata', label: 'Configuração', description: 'Configuração JSON com passos e opções' },
+        {
+            name: 'config',
+            type: 'StepperMetadata',
+            label: 'Configuração',
+            description: 'Configuração JSON com passos, aparência, densidade, classes CSS e navegação',
+        },
         { name: 'selectedIndex', type: 'number', label: '[(selectedIndex)] Índice selecionado' },
         { name: 'selectedIndexInput', type: 'number', label: 'Índice selecionado (legacy)' },
         { name: 'disableRippleInput', type: 'boolean', default: false, label: 'Desabilitar ripple' },
         { name: 'editModeEnabled', type: 'boolean', default: false, label: 'Modo de edição', description: 'Exibe controles de edição e assistente AI no runtime' },
         { name: 'labelPosition', type: "'bottom' | 'end'", label: 'Posição do rótulo (horizontal)' },
         { name: 'color', type: 'ThemePalette', label: 'Cor (M2)' },
-        { name: 'appearance', type: '{ themeClass?: string; tokens?: Record<string,string>; icons?: { number?: string; done?: string; edit?: string; error?: string }; iconsSet?: string }', label: 'Aparência (tokens, themeClass, ícones, conjunto)' },
         { name: 'serverValidate', type: '(args) => Promise<{ ok: boolean; fieldErrors?: Record<string,string[]>; formErrors?: string[] }>', label: 'Validação remota (opt-in)' },
-        { name: 'density', type: "'default' | 'comfortable' | 'compact'", label: 'Densidade' },
-        { name: 'stepperClass', type: 'string', label: 'Classe CSS (stepper)' },
-        { name: 'headerClass', type: 'string', label: 'Classe CSS (header)' },
-        { name: 'contentClass', type: 'string', label: 'Classe CSS (conteúdo)' },
         { name: 'stepperContext', type: 'Record<string, any>', label: 'Contexto', description: 'Contexto compartilhado para widgets internos' },
-        { name: 'navigation', type: "{ visible?: boolean; prevLabel?: string; nextLabel?: string; prevIcon?: string; nextIcon?: string; variant?: 'basic'|'flat'|'stroked'|'raised'; color?: ThemePalette; align?: 'start'|'center'|'end'|'space-between' }", label: 'Navegação (botões)'
-        },
     ],
     outputs: [
         { name: 'selectionChange', type: 'any', label: 'Troca de seleção' },
@@ -4534,6 +4598,7 @@ class PraxisWizardFormComponent {
         this._config.set(validateWizardConfig(cfg));
     }
     submit = new EventEmitter();
+    customAction = new EventEmitter();
     _config = signal(null, ...(ngDevMode ? [{ debugName: "_config" }] : []));
     persistedState = signal(null, ...(ngDevMode ? [{ debugName: "persistedState" }] : []));
     selectedIndex = signal(0, ...(ngDevMode ? [{ debugName: "selectedIndex" }] : []));
@@ -4581,17 +4646,29 @@ class PraxisWizardFormComponent {
             return !!this.stepper?.isNextDisabled(this.selectedIndex());
         return false;
     }
-    onPrimaryAction() {
+    async onPrimaryAction() {
         this.focusPrimaryAction();
         const action = this.primaryAction();
         if (action === 'next') {
-            this.stepper?.next();
+            await this.stepper?.nextWithValidation(this.selectedIndex());
             return;
         }
         if (action === 'submit') {
+            const isValid = await this.stepper?.validateStep(this.selectedIndex());
+            if (isValid === false) {
+                return;
+            }
             this.submit.emit({ wizardId: this.wizardId, values: this.collectValues() });
             return;
         }
+        if (action === 'custom') {
+            this.customAction.emit({
+                wizardId: this.wizardId,
+                stepId: this.activeStep()?.id,
+                stepIndex: this.selectedIndex(),
+                values: this.collectValues(),
+            });
+        }
     }
     onSecondaryAction() {
         this.focusSecondaryAction();
@@ -4680,7 +4757,7 @@ class PraxisWizardFormComponent {
         el?.focus();
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.17", ngImport: i0, type: PraxisWizardFormComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "20.3.17", type: PraxisWizardFormComponent, isStandalone: true, selector: "praxis-wizard-form", inputs: { wizardId: "wizardId", editModeEnabled: "editModeEnabled", config: "config" }, outputs: { submit: "submit" }, viewQueries: [{ propertyName: "stepper", first: true, predicate: ["stepper"], descendants: true, static: true }], ngImport: i0, template: `
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "20.3.17", type: PraxisWizardFormComponent, isStandalone: true, selector: "praxis-wizard-form", inputs: { wizardId: "wizardId", editModeEnabled: "editModeEnabled", config: "config" }, outputs: { submit: "submit", customAction: "customAction" }, viewQueries: [{ propertyName: "stepper", first: true, predicate: ["stepper"], descendants: true, static: true }], ngImport: i0, template: `
     <section class="ft-wizard-shell" [attr.data-wizard-id]="wizardId">
       <div class="ft-wizard-header">
         <div class="ft-brand">{{ wizardBrand() }}</div>
@@ -4773,6 +4850,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImpo
                 type: Input
             }], submit: [{
                 type: Output
+            }], customAction: [{
+                type: Output
             }] } });
 function pickPreferenceValues(value, fields) {
     if (!value || !fields || fields.length === 0)