@praxisui/stepper

@praxisui/stepper

🔰 Exemplos / Quickstart

Para ver esta biblioteca em funcionamento em uma aplicação completa, utilize o projeto de exemplo (Quickstart):

• Repositório: https://github.com/codexrodrigues/praxis-ui-quickstart
• O Quickstart demonstra a integração das bibliotecas @praxisui/* em um app Angular, incluindo instalação, configuração e uso em telas reais.

Componente stepper standalone com integração opcional ao @praxisui/dynamic-form, suporte a ícones Material Icons/Symbols e editor de configuração embutido.

Instalação

Instale a biblioteca junto com as dependências pares (peer dependencies) exigidas pelo componente e pelo editor de configuração:

npm i @praxisui/stepper \
      @praxisui/core @praxisui/dynamic-form @praxisui/settings-panel \
      @praxisui/list @praxisui/files-upload @praxisui/page-builder

Peer dependencies (Angular v20):

• @angular/core ^20.0.0
• @angular/common ^20.0.0
• @angular/material ^20.0.0
• @angular/cdk ^20.0.0
• @praxisui/core ^0.0.1
• @praxisui/dynamic-form ^0.0.1
• @praxisui/settings-panel ^0.0.1
• @praxisui/list ^0.0.1
• @praxisui/files-upload ^0.0.1
• @praxisui/page-builder ^0.0.1

Quick Start

Uso básico

import { Component } from '@angular/core';
import { PraxisStepper } from '@praxisui/stepper';

@Component({
  selector: 'app-onboarding',
  standalone: true,
  imports: [PraxisStepper],
  template: `
    <praxis-stepper [config]="config" [editModeEnabled]="true"></praxis-stepper>
  `,
})
export class OnboardingComponent {
  config = {
    orientation: 'horizontal',
    headerPosition: 'top',
    linear: true,
    steps: [
      { id: 'profile', label: 'Perfil' },
      { id: 'confirm', label: 'Confirmação' },
    ],
    navigation: { nextLabel: 'Avançar', prevLabel: 'Voltar' },
  } as const;
}

Publishing the Library

Após gerar os artefatos com o Angular Package Format (APF) via ng build @praxisui/stepper, você pode publicar no npm:

# Build de produção a partir do monorepo (recomendado)
cd ../../
npm run build:praxis-stepper

# Publicação manual (diretório de saída da lib)
cd dist/praxis-stepper
npm publish --access public

Observação: a publicação automatizada via CI está documentada no README do workspace e publica todas as libs em dist/ (incluindo @praxisui/stepper).

Integração com Dynamic Form (por etapa)

import { Component } from '@angular/core';
import { PraxisStepper } from '@praxisui/stepper';

@Component({
  selector: 'app-cadastro',
  standalone: true,
  imports: [PraxisStepper],
  template: `<praxis-stepper [config]="config"></praxis-stepper>`,
})
export class CadastroComponent {
  config = {
    linear: true,
    steps: [
      {
        id: 'dados',
        label: 'Dados do Cliente',
        form: {
          resourcePath: 'human-resources/funcionarios',
          mode: 'create',
          // ou forneça FormConfig diretamente
          // config: { sections: [...] }
        },
      },
      {
        id: 'endereco',
        label: 'Endereço',
        form: { resourcePath: 'enderecos', mode: 'create' },
      },
    ],
  };
}

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.

<praxis-stepper
  [config]="config"
  [serverValidate]="validateStep"
></praxis-stepper>

validateStep = async ({ step, formGroup, formData }) => {
  // Chamada remota opcional
  const ok = await Promise.resolve(true);
  return { ok };
};

API Surface

• Componentes: PraxisStepper, PraxisStepperConfigEditor
• Tipos: StepperMetadata, StepConfig, StepOrientation, StepHeaderPosition
• Eventos: selectedIndexChange, selectionChange, widgetEvent, animationDone
• Veja: projects/praxis-stepper/src/public-api.ts

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.

Conjuntos de Ícones (Material Icons vs Material Symbols)

O Angular Material, por padrão, usa o conjunto “Material Icons” (ligature). Ícones como repeat funcionam imediatamente. Já ícones como counter_1 pertencem ao “Material Symbols” e precisam de fonte + classe próprias.

Ativar Material Symbols (Outlined)

No seu app host (ex.: src/styles.scss ou projects/<app>/src/styles.scss), adicione:

@import url('https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0');

.material-symbols-outlined {
  font-family: 'Material Symbols Outlined';
  font-weight: normal;
  font-style: normal;
  font-size: 24px; /* tamanho padrão do ícone */
  line-height: 1;
  display: inline-block;
  -webkit-font-feature-settings: 'liga';
  -webkit-font-smoothing: antialiased;
  font-variation-settings: 'FILL' 0, 'wght' 400, 'GRAD' 0, 'opsz' 24;
}

Se preferir Rounded/Sharp, importe a família correspondente e use .material-symbols-rounded ou .material-symbols-sharp.

Selecionar o conjunto no editor do Stepper

Na aba “Aparência” do editor:

• Selecione “Conjunto de ícones”:
  • “Material Icons (padrão)” para ícones clássicos (ex.: repeat, looks_one).
  • “Material Symbols (Outlined/Rounded/Sharp)” para ícones como counter_1, replace_image etc.
• Escolha os ícones para estados: número, concluído, edição, erro. O preview reflete o conjunto selecionado.

O componente aplica a classe (material-symbols-*) quando um conjunto Symbols é escolhido, exibindo corretamente os nomes selecionados.

Tokens de Estilo com mat.stepper-overrides

Para personalizações visuais (cores, tipografia, densidade), use os tokens do Angular Material. No editor, a aba “Aparência” permite editar tokens e copia um snippet SCSS pronto:

:root {
  @include mat.stepper-overrides((
    container-color: var(--md-sys-color-surface),
    header-label-text-color: var(--md-sys-color-on-surface),
    header-height: 48px,
  ));
}

Cole o snippet no arquivo de tema do seu app. Você pode trocar :root por uma classe para escopo local.

Dicas de Uso

• Altura do cabeçalho / Tamanho do texto / Peso do texto: edite pelos campos rápidos — o editor converte automaticamente para tokens (header-height, header-label-text-size, header-label-text-weight).
• Ícones pelo site do Google: copie o nome do ícone em https://fonts.google.com/icons e cole no picker. Não é possível capturar automaticamente a seleção do site.
• Em Material Symbols, nomes como counter_1, replace_image exigem que o conjunto esteja corretamente importado e selecionado no editor.

Exemplo Mínimo de Configuração

config = {
  orientation: 'horizontal',
  headerPosition: 'top',
  steps: [
    { id: 's1', label: 'Dados' },
    { id: 's2', label: 'Confirmação' },
  ],
  appearance: {
    iconsSet: 'material-symbols-outlined',
    icons: { number: 'counter_1', done: 'check', edit: 'edit', error: 'error' },
    tokens: { 'header-height': '48px' },
  },
};

Com isso, os ícones e estilos do cabeçalho do stepper serão aplicados como esperado.

Compatibilidade

• @praxisui/stepper 0.0.x → Angular 20.x
• Formato de módulo: ESM2022

Licença

Apache-2.0 – veja o LICENSE empacotado com esta biblioteca ou o arquivo LICENSE na raiz do repositório.