@govbr-ds/webcomponents 2.4.0 → 2.5.0

package/dist/types/components/upload/upload.d.ts

@@ -5,41 +5,29 @@ import { type FormValidationChangeDetail } from '../../shared/utils/validator';
 import type { BrFeedbackState } from '../global.types';
 import type { UploadErrorDetail, UploadFileDetail, UploadHandler, UploadProgressDetail, UploadValidator } from './upload.types';
 /**
- * O componente `br-upload` é o elemento oficial do GovBR-DS para seleção, anexação e envio de arquivos em formulários, com suporte a seleção múltipla, área de arrastar-e-soltar (drag-and-drop) e acompanhamento de progresso.
+ * O `br-upload` gerencia a seleção e envio de arquivos em formulários, com suporte a arrastar e soltar (drag and drop).
  *
- * ### Para que serve
+ * Defina os tipos aceitos em `accept` e permita múltiplos arquivos com `multiple`. Use a lista de arquivos para exibir o progresso e o botão de exclusão.
  *
- * - **Seleção e anexação de arquivos:** Permite anexar documentos, planilhas, imagens ou outros formatos através do seletor nativo do sistema operacional ou por arrastar e soltar.
- * - **Validação de tipos e tamanhos:** Valida extensões permitidas (`accept`) e tamanho máximo por arquivo (`max-file-size`), informando erros de validação de forma acessível.
- * - **Listagem visual e remoção:** Exibe a lista de arquivos selecionados com nome, tamanho formatado (KB/MB), barra de progresso individual e botão de exclusão.
- * - **Integração com formulários:** Integrado nativamente via `formAssociated`, permitindo submissão tradicional de formulários ou upload assíncrono programático.
+ * ```html
+ * <br-upload label="Enviar documento" accept=".pdf,.png,.jpg" multiple></br-upload>
+ * ```
  *
- * ### Quando utilizar
+ * Em formulários HTML, o componente integra-se via `ElementInternals`, enviando a lista de arquivos no submit nativo.
  *
- * - **Utilize quando:**
- *   - A pessoa usuária precisar enviar comprovantes, relatórios, fotografias ou documentos digitais.
- *   - For necessário limitar e validar os tipos de arquivo e o tamanho máximo antes do envio ao servidor.
- * - **Evite e prefira outro componente quando:**
- *   - A captura for exclusivamente de texto ou URLs externas (prefira `br-input`).
+ * ### Quando usar
  *
- * ### Estrutura e Slots
+ * - Anexar comprovantes, fotos ou documentos em formulários.
  *
- * O `br-upload` possui estrutura rica com múltiplos slots:
- * - `default`: Slot para texto personalizado do botão de upload (padrão: "Selecione o arquivo").
- * - `upload-list`: Slot opcional para substituição da área padrão de listagem de arquivos.
- * - `label`: Slot para personalização do rótulo do campo.
- * - `helper`: Slot para instruções ou restrições de formato/tamanho exibidas abaixo do campo.
- * - `feedback`: Slot para mensagens de validação e erro (como `br-message`).
- * - `loading`: Slot para indicador exibido durante o envio assíncrono dos arquivos.
+ * ### Quando evitar
  *
- * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/upload?tab=designer).
+ * - Campo de texto ou URL de arquivo remoto: use `br-input`.
+ *
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/upload?tab=designer).
  *
-
  * @category Formulários, Dados
  * @status stable
- * @slot default - Texto personalizado para o botão de upload. Se não fornecido, será exibido "Selecione o arquivo" como texto padrão.
- *                 Use este slot para personalizar o texto do botão de acordo com o contexto do upload, por exemplo: "Anexar documentos",
- *                 "Enviar imagens", etc.
+ * @slot default - Conteúdo personalizado do botão de upload, com precedência sobre `buttonLabel` (use a prop para texto simples).
  * @slot upload-list - Permite customizar a área de listagem de arquivos. Se utilizado, substitui a lista padrão gerada pelo componente.
  * @slot label - Rótulo customizado do upload. Quando utilizado, a prop `label` é ignorada.
  * @slot helper - Texto auxiliar exibido abaixo da superfície de seleção.
@@ -121,6 +109,11 @@ export declare class Upload {
      * Rótulo exibido acima do botão de upload.
      */
     label: string;
+    /**
+     * Texto do botão de seleção. Quando omitido, usa "Selecione o arquivo" ou,
+     * com `multiple`, "Selecione o(s) arquivo(s)". O slot padrão tem precedência.
+     */
+    buttonLabel?: string;
     /**
      * Lista de arquivos já enviados (para edição ou pré-visualização).
      * Pode ser uma string JSON ou um array de objetos IUploadFile. Cada item deve ter `name` não vazio e `size` numérico não negativo opcional; itens inválidos são ignorados.
@@ -162,7 +155,7 @@ export declare class Upload {
      * Estado visual: 'info', 'warning', 'danger' ou 'success'. Valores inválidos não aplicam estado.
      */
     state: BrFeedbackState;
-    /** Estado de feedback canônico. Quando informado, tem precedência sobre `state`. */
+    /** Estado de feedback. Quando informado, tem precedência sobre `state`. */
     feedbackState?: BrFeedbackState;
     /**
      * Indica se o componente permite a seleção de múltiplos arquivos.
@@ -221,7 +214,7 @@ export declare class Upload {
      * @deprecated Use `brUploadRemove`.
      */
     brRemove: EventEmitter<IUploadFile>;
-    /** Evento canônico emitido quando um arquivo existente é removido. */
+    /** Evento emitido quando um arquivo existente é removido. */
     brUploadRemove: EventEmitter<IUploadFile>;
     /** Emitido quando o usuário fecha a caixa de seleção de arquivos sem escolher nada. */
     brUploadCancel: EventEmitter<void>;

package/dist/types/components/wizard/wizard-panel/wizard-panel.d.ts

@@ -1,18 +1,8 @@
 /**
- * Subcomponente individual de `br-wizard`, responsável por encapsular o formulário, campos de entrada ou informações pertencentes a uma etapa específica do fluxo guiado.
+ * Painel de conteúdo de uma etapa individual do `br-wizard`.
  *
- * ### Papel na composição
+ * Defina o título da etapa em `title-text`. Insira os campos e conteúdos dessa fase no slot padrão.
  *
- * - Agrupa todos os campos de formulário e conteúdos daquela etapa.
- * - Informa o título e subtítulo da etapa que serão refletidos na barra de progresso do wizard.
- *
- * ### Regra de uso e relacionamento
- *
- * Deve ser declarado no slot padrão do orquestrador `br-wizard`. O componente pai é quem decide qual painel deve estar visível com base na etapa corrente, coordenando os botões de avançar e voltar. Não deve ser instanciado de forma autônoma fora de um `br-wizard`.
- *
- * Para a documentação completa de design, consulte o [Design System do GovBR](https://www.gov.br/ds/components/wizard?tab=designer).
- *
-
  * @slot default - Slot para o conteúdo da etapa (formulários, campos ou informações da fase atual).
  *
  * @part panel - Wrapper do painel.

package/dist/types/components/wizard/wizard.d.ts

@@ -1,39 +1,35 @@
 import { type EventEmitter } from '../../stencil-public-runtime';
 import type { BrOrientation, BrProgressionType } from '../global.types';
 /**
- * O componente `br-wizard` é o orquestrador completo de fluxos passo a passo do GovBR-DS, desenvolvido para guiar a pessoa usuária através de formulários e tarefas complexas distribuídas em etapas consecutivas.
+ * O `br-wizard` conduz fluxos passo a passo divididos em telas sequenciais com botões de navegação e barra de progresso.
  *
- * ### Para que serve
+ * Insira cada tela com `br-wizard-panel` no slot padrão. Acompanhe a mudança de etapas pelo evento `brStepChange`.
  *
- * - **Condução guiada de processos:** Apresenta um formulário longo dividido em etapas menores e focadas, reduzindo a carga cognitiva e o índice de abandono.
- * - **Barra de progresso e navegação integradas:** Combina o indicador visual de etapas (`step`), os painéis de conteúdo de cada etapa (`br-wizard-panel`) e a barra de ações com botões de "Voltar", "Avançar", "Concluir" e "Cancelar".
- * - **Validação por etapa:** Permite interceptar o avanço de cada passo para validação antes de liberar o próximo painel.
+ * ```html
+ * <br-wizard>
+ *   <br-wizard-panel title-text="Identificação">
+ *     <p>Primeira etapa do cadastro.</p>
+ *   </br-wizard-panel>
+ *   <br-wizard-panel title-text="Endereço">
+ *     <p>Segunda etapa do cadastro.</p>
+ *   </br-wizard-panel>
+ *   <br-wizard-panel title-text="Confirmação">
+ *     <p>Revise os dados antes de enviar.</p>
+ *   </br-wizard-panel>
+ * </br-wizard>
+ * ```
  *
- * ### Quando utilizar
+ * ### Quando usar
  *
- * - **Utilize quando:**
- *   - Houver um processo de cadastro, requerimento, compra ou configuração estruturado em etapas com dependência de sequência.
- *   - For essencial oferecer navegação pré-programada de retorno e avanço com controle de estado.
- * - **Evite e prefira outro componente quando:**
- *   - O objetivo for apenas mostrar o status de um pedido já concluído (use `br-step` simples).
- *   - O usuário puder navegar em qualquer ordem entre as seções da tela (use `br-tab`).
+ * - Formulários extensos com dependência lógica entre etapas.
  *
- * ### Composição e Subcomponentes
+ * ### Quando evitar
  *
- * | Subcomponente | Papel | Regra de uso |
- * | --- | --- | --- |
- * | `br-wizard` | **Orquestrador principal.** Gerencia a barra de progresso, ações de navegação (voltar/avançar), botões de rodapé e controle do painel ativo. | Deve ser o contêiner raiz do fluxo. |
- * | `br-wizard-panel` | **Painel de etapa individual.** Contém os campos e formulários de uma etapa específica. | Declarado dentro do slot padrão do `br-wizard`. |
+ * - Apenas indicar o status de um pedido já realizado: use `br-step`.
+ * - Conteúdos independentes onde a ordem de preenchimento é livre: use `br-tab`.
  *
- * ### Como os subcomponentes se relacionam
+ * Consulte as [diretrizes de design do GovBR](https://www.gov.br/ds/components/wizard?tab=designer).
  *
- * O `br-wizard` gerencia ativamente os elementos `br-wizard-panel` declarados em seu interior:
- * 1. O pai exibe apenas o painel correspondente à etapa atual (`activeStep`), mantendo os demais ocultos.
- * 2. Ao avançar ou retroceder, o `br-wizard` dispara eventos de validação e troca de etapa (`brStepChange`), atualizando simultaneamente o cabeçalho de progresso e as ações do rodapé.
- *
- * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/wizard?tab=designer).
- *
-
  * @category Navegação, Formulários, Progresso
  * @status stable
  * @slot default - Slot para os painéis de etapa (br-wizard-panel) do wizard.