@praxisui/stepper 1.0.0-beta.30 → 1.0.0-beta.41

package/README.md

@@ -44,7 +44,7 @@ import { PraxisStepper } from '@praxisui/stepper';
   standalone: true,
   imports: [PraxisStepper],
   template: `
-    <praxis-stepper [config]="config" [editModeEnabled]="true"></praxis-stepper>
+    <praxis-stepper stepperId="stepper-demo" [config]="config" [editModeEnabled]="true"></praxis-stepper>
   `,
 })
 export class OnboardingComponent {
@@ -61,6 +61,12 @@ export class OnboardingComponent {
 }
 ```
 
+### Persistência
+
+- `stepperId` é obrigatório para salvar/carregar a configuração.
+- A chave usada no storage é `stepper-config:<component_id>` (via `ComponentKeyService`).
+- Use `componentInstanceId` quando houver múltiplos steppers com o mesmo `stepperId` na mesma rota.
+
 ### Publishing the Library
 
 Após gerar os artefatos com o Angular Package Format (APF) via `ng build @praxisui/stepper`, você pode publicar no npm:
@@ -87,7 +93,7 @@ import { PraxisStepper } from '@praxisui/stepper';
   selector: 'app-cadastro',
   standalone: true,
   imports: [PraxisStepper],
-  template: `<praxis-stepper [config]="config"></praxis-stepper>`,
+  template: `<praxis-stepper stepperId="stepper-demo" [config]="config"></praxis-stepper>`,
 })
 export class CadastroComponent {
   config = {
@@ -116,7 +122,7 @@ 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.
 
 ```html
-<praxis-stepper
+<praxis-stepper stepperId="stepper-demo"
   [config]="config"
   [serverValidate]="validateStep"
 ></praxis-stepper>
@@ -134,9 +140,70 @@ validateStep = async ({ step, formGroup, formData }) => {
 
 - Componentes: `PraxisStepper`, `PraxisStepperConfigEditor`
 - Tipos: `StepperMetadata`, `StepConfig`, `StepOrientation`, `StepHeaderPosition`
-- Eventos: `selectedIndexChange`, `selectionChange`, `widgetEvent`, `animationDone`
+- Eventos: `selectedIndexChange`, `selectionChange`, `widgetEvent`, `animationDone`, `stepFormReady`, `stepFormValueChange`
 - Veja: `projects/praxis-stepper/src/public-api.ts`
 
+## Wizard Form (FT-like) — Experimental
+
+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';
+
+@Component({
+  selector: 'app-ft-wizard',
+  standalone: true,
+  imports: [PraxisWizardFormComponent],
+  template: `<praxis-wizard-form wizardId="ft-demo" [config]="config" />`,
+})
+export class FtWizardDemo {
+  config = FT_WIZARD_CONFIG;
+}
+```
+
+Notas:
+- `widgetsBeforeForm` permite inserir cards/infos antes do formulário em cada etapa.
+- `blocks` (wizard) permite inserir conteúdos editoriais (benefits/content/notice/divider) antes ou depois do formulário.
+- `zones` (wizard) permite separar blocos em `intro`, `body` e `footer` (mapeados para before/after form).
+- 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`.
+- Preset visual recomendado para FT-like: `appearance.preset = 'ft-light'` (aplicado automaticamente no wizard).
+
+## Tokens de tema (Wizard)
+
+O wizard usa **tokens M3** por padrão. Se for necessário sobrescrever algo específico do wizard, use tokens da própria lib, sempre apontando para tokens M3 no tema do host:
+
+```scss
+:root {
+  --praxis-wizard-bg: var(--md-sys-color-surface-container-low);
+  --praxis-wizard-card-bg: var(--md-sys-color-surface);
+  --praxis-wizard-border: var(--md-sys-color-outline-variant);
+  --praxis-wizard-muted: var(--md-sys-color-on-surface-variant);
+  --praxis-wizard-accent: var(--md-sys-color-primary);
+  --praxis-wizard-accent-on: var(--md-sys-color-on-primary);
+}
+```
+
+Tokens disponíveis:
+- `--praxis-wizard-bg`
+- `--praxis-wizard-card-bg`
+- `--praxis-wizard-border`
+- `--praxis-wizard-muted`
+- `--praxis-wizard-accent`
+- `--praxis-wizard-accent-on`
+- 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.
+- 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 {
+  --praxis-wizard-accent: var(--md-sys-color-primary);
+}
+```
+
 # Praxis Stepper — Guia de Estilos e Ícones
 
 Este guia explica como personalizar estilos (tokens) e ícones do cabeçalho do stepper em apps que consomem a lib `@praxisui/stepper`.