@govbr-ds/webcomponents 2.1.2 → 2.2.0

package/dist/collection/components/wizard/wizard.js

@@ -4,11 +4,46 @@
  */
 import { Host, h, } from "@stencil/core";
 import { generateUniqueId } from "../../shared/utils/id";
+import { findComposedOwner } from "../../shared/utils/ownership";
+import { resolveAllowedPropValue, resolveIntegerPropValue } from "../../shared/utils/props";
 import { UniversalSwipe } from "../../shared/utils/swipe";
+const WIZARD_ORIENTATIONS = ['horizontal', 'vertical'];
+const WIZARD_PROGRESSION_TYPES = ['linear', 'nonlinear'];
 /**
- * Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/wizard?tab=designer).
+ * 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.
  *
- * @category Navegação
+ * ### Para que serve
+ *
+ * - **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.
+ *
+ * ### Quando utilizar
+ *
+ * - **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`).
+ *
+ * ### Composição e Subcomponentes
+ *
+ * | 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`. |
+ *
+ * ### Como os subcomponentes se relacionam
+ *
+ * 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.
  * @slot cancel-button - Conteúdo customizado do botão de cancelar. Quando utilizado, o texto padrão "Cancelar" é substituído.
@@ -49,6 +84,7 @@ export class Wizard {
          * Índice da etapa inicial do wizard.
          * Define qual etapa será exibida ao carregar o componente.
          * A numeração começa em 1 (primeira etapa = 1, segunda = 2, etc).
+         * Valores inválidos usam 1.
          * @deprecated Use `initialIndex`.
          */
         this.initialStep = 1;
@@ -99,10 +135,6 @@ export class Wizard {
          * Tempo de espera para limpar mensagens aria-live (em ms).
          */
         this.ARIA_LIVE_CLEANUP_DELAY = 5000;
-        /**
-         * Seletor de elementos focáveis dentro dos painéis.
-         */
-        this.FOCUSABLE_SELECTOR = 'br-button, button, [href], br-item, br-input, input, br-select, select, br-textarea, textarea, [tabindex]:not([tabindex="-1"])';
         /**
          * Handler de resize da janela.
          * Alterna entre modos mobile/desktop e configura/limpa gestos swipe.
@@ -159,6 +191,20 @@ export class Wizard {
             this.brWizardCancel.emit();
         };
     }
+    get effectiveOrientation() {
+        return resolveAllowedPropValue(this.el, 'orientation', this.orientation, WIZARD_ORIENTATIONS, 'horizontal');
+    }
+    get effectiveProgressionType() {
+        return resolveAllowedPropValue(this.el, 'progressionType', this.progressionType, WIZARD_PROGRESSION_TYPES, 'nonlinear');
+    }
+    get effectiveInitialIndex() {
+        return resolveIntegerPropValue(this.el, 'initialIndex', this.initialIndex, 0, Number.MAX_SAFE_INTEGER, 0, {
+            allowUndefined: true,
+        });
+    }
+    get effectiveInitialStep() {
+        return resolveIntegerPropValue(this.el, 'initialStep', this.initialStep, 1, Number.MAX_SAFE_INTEGER, 1);
+    }
     /**
      * Observa mudanças no tipo de progressão.
      * Atualiza a navegação dos painéis quando muda entre linear/nonlinear.
@@ -219,7 +265,8 @@ export class Wizard {
      * Lifecycle: inicializa painéis antes da renderização.
      */
     componentWillLoad() {
-        this.panels = Array.from(this.el.querySelectorAll('br-wizard-panel'));
+        const panels = Array.from(this.el.children).filter((panel) => panel.tagName.toLowerCase() === 'br-wizard-panel' && findComposedOwner(panel, 'br-wizard') === this.el);
+        this.setPanels(panels);
         this.setInitialStep();
     }
     /**
@@ -231,9 +278,7 @@ export class Wizard {
         if (slot !== null && typeof slot !== 'undefined') {
             const assignedElements = slot.assignedElements();
             const slotPanels = assignedElements.filter((el) => el.tagName.toLowerCase() === 'br-wizard-panel');
-            if (slotPanels.length > 0) {
-                this.panels = slotPanels;
-            }
+            this.setPanels(slotPanels);
         }
         await this.syncWithBrStep();
         this.updatePanels();
@@ -375,7 +420,7 @@ export class Wizard {
          * No modo linear, não é permitido pular para etapas futuras não visitadas.
          * É possível voltar, mas não avançar além da próxima etapa sequencial.
          */
-        if (this.progressionType === 'linear') {
+        if (this.effectiveProgressionType === 'linear') {
             if (targetStep > this.currentStep + 1) {
                 const message = `Não é possível pular etapas. Complete a etapa ${this.currentStep + 1} antes de avançar.`;
                 this.announceToScreenReader(message);
@@ -455,7 +500,18 @@ export class Wizard {
      */
     discoverPanelsFromSlot(slot) {
         const assignedElements = slot.assignedElements();
-        this.panels = assignedElements.filter((el) => el.tagName.toLowerCase() === 'br-wizard-panel');
+        const panels = assignedElements.filter((el) => el.tagName.toLowerCase() === 'br-wizard-panel');
+        this.setPanels(panels);
+    }
+    /**
+     * Atualiza a lista de painéis somente quando a composição realmente mudou.
+     * Evita uma re-renderização redundante durante `componentDidLoad()`.
+     */
+    setPanels(nextPanels) {
+        const panelsDidNotChange = this.panels.length === nextPanels.length && this.panels.every((panel, index) => panel === nextPanels[index]);
+        if (!panelsDidNotChange) {
+            this.panels = nextPanels;
+        }
     }
     /**
      * Atualiza estados de todos os painéis.
@@ -475,7 +531,7 @@ export class Wizard {
      * Garante que o valor esteja dentro dos limites válidos.
      */
     setInitialStep() {
-        const initialStep = this.initialIndex === undefined ? this.initialStep : this.initialIndex + 1;
+        const initialStep = this.effectiveInitialIndex === undefined ? this.effectiveInitialStep : this.effectiveInitialIndex + 1;
         this.currentStep = Math.max(1, Math.min(initialStep, this.panels.length));
         this.step = this.currentStep;
         this.el.setAttribute('step', String(this.currentStep));
@@ -533,13 +589,7 @@ export class Wizard {
             const activePanel = this.panels[this.currentStep - 1];
             if (typeof activePanel === 'undefined')
                 return;
-            const panelElement = activePanel.shadowRoot?.querySelector('.wizard-panel-content');
-            if (typeof panelElement === 'undefined' || panelElement === null)
-                return;
-            const focusableElements = panelElement.querySelectorAll(this.FOCUSABLE_SELECTOR);
-            if (focusableElements.length > 0) {
-                focusableElements[0].focus();
-            }
+            void activePanel.focusFirst?.();
         });
     }
     /**
@@ -547,10 +597,12 @@ export class Wizard {
      * Ativa listeners de resize e configura gestos swipe.
      */
     setupMobileDetection() {
+        if (typeof window === 'undefined')
+            return;
         this.isMobile = window.innerWidth <= 992;
         window.addEventListener('resize', this.handleResize);
         if (this.isMobile) {
-            if (this.orientation === 'vertical') {
+            if (this.effectiveOrientation === 'vertical') {
                 this.collapsed = true;
             }
             this.setupSwipeListeners();
@@ -560,6 +612,8 @@ export class Wizard {
      * Remove listeners de detecção mobile.
      */
     cleanupMobileDetection() {
+        if (typeof window === 'undefined')
+            return;
         window.removeEventListener('resize', this.handleResize);
     }
     /**
@@ -572,9 +626,9 @@ export class Wizard {
             this.progressBarRef = this.el.shadowRoot?.querySelector('.wizard-progress') || null;
             this.formRef = this.el.shadowRoot?.querySelector('.wizard-form') || null;
             if (this.progressBarRef !== null) {
-                const direction = this.orientation === 'horizontal' ? 'vertical' : 'horizontal';
+                const direction = this.effectiveOrientation === 'horizontal' ? 'vertical' : 'horizontal';
                 this.progressBarSwipe = new UniversalSwipe(this.progressBarRef, { direction });
-                if (this.orientation === 'horizontal') {
+                if (this.effectiveOrientation === 'horizontal') {
                     this.progressBarSwipe.on('SWIPE_DOWN', () => this.expandSteps());
                     this.progressBarSwipe.on('SWIPE_UP', () => this.collapseSteps());
                 }
@@ -639,7 +693,7 @@ export class Wizard {
         if (this.panels.length === 0) {
             return null;
         }
-        return (h("div", { class: "wizard-progress", part: "progress" }, h("br-step", { ref: (el) => (this.stepRef = el), "initial-step": String(this.currentStep - 1), layout: this.orientation, "label-position": this.orientation === 'vertical' ? 'bottom' : 'bottom', "progression-type": this.progressionType, mode: "step" }, this.panels.map((panel, index) => {
+        return (h("div", { class: "wizard-progress", part: "progress" }, h("br-step", { ref: (el) => (this.stepRef = el), "initial-step": String(this.currentStep - 1), layout: this.effectiveOrientation, "label-position": this.effectiveOrientation === 'vertical' ? 'bottom' : 'bottom', "progression-type": this.effectiveProgressionType, mode: "step" }, this.panels.map((panel, index) => {
             const label = panel.getAttribute('label') || '';
             return (h("br-step-item", { key: panel.id || panel.getAttribute('custom-id') || `wizard-panel-${index}`, label: label }));
         }))));
@@ -677,14 +731,14 @@ export class Wizard {
      */
     render() {
         const hostClass = this.getHostClassMap();
-        const verticalAttr = this.orientation === 'vertical' ? { vertical: '' } : {};
+        const verticalAttr = this.effectiveOrientation === 'vertical' ? { vertical: '' } : {};
         const collapsedAttr = this.collapsed ? { collapsed: '' } : {};
         const activePanelAttr = { active: '' };
         // Atributos ARIA para o painel ativo
         const totalSteps = this.panels.length;
         const currentPanel = this.panels[this.currentStep - 1];
         const stepLabel = currentPanel?.getAttribute('label') || `Etapa ${this.currentStep}`;
-        return (h(Host, { key: 'f01acdc3c90053109123a756711e0d37b2dc77d7', class: hostClass, ...verticalAttr, ...collapsedAttr, step: String(this.currentStep) }, this.renderAriaLiveRegion(), this.renderProgress(), h("div", { key: '7c79f3c8404807e951b85f9916e42c16a964a41d', class: "wizard-form", role: "region", "aria-label": `Wizard: ${stepLabel}`, part: "form" }, h("div", { key: '21e0bf5935d80f9b6f40d1bcd1783de6cc771298', class: "wizard-panel", ...activePanelAttr, role: "group", "aria-label": `${stepLabel}, etapa ${this.currentStep} de ${totalSteps}`, part: "panel" }, this.renderPanelContent(), this.renderPanelButtons()))));
+        return (h(Host, { key: '8f6e16ef5793134ee1779ef9aa357a060e33427c', class: hostClass, ...verticalAttr, ...collapsedAttr, step: String(this.currentStep) }, this.renderAriaLiveRegion(), this.renderProgress(), h("div", { key: 'b397f55be52767ed373fdce1aa6be828663f1753', class: "wizard-form", role: "region", "aria-label": `Wizard: ${stepLabel}`, part: "form" }, h("div", { key: '8400cdcecae5888fe3e6faeadcf650ae9a13ea17', class: "wizard-panel", ...activePanelAttr, role: "group", "aria-label": `${stepLabel}, etapa ${this.currentStep} de ${totalSteps}`, part: "panel" }, this.renderPanelContent(), this.renderPanelButtons()))));
     }
     static get is() { return "br-wizard"; }
     static get encapsulation() { return "shadow"; }
@@ -735,7 +789,7 @@ export class Wizard {
                             "name": "deprecated",
                             "text": "Use `initialIndex`."
                         }],
-                    "text": "\u00CDndice da etapa inicial do wizard.\nDefine qual etapa ser\u00E1 exibida ao carregar o componente.\nA numera\u00E7\u00E3o come\u00E7a em 1 (primeira etapa = 1, segunda = 2, etc)."
+                    "text": "\u00CDndice da etapa inicial do wizard.\nDefine qual etapa ser\u00E1 exibida ao carregar o componente.\nA numera\u00E7\u00E3o come\u00E7a em 1 (primeira etapa = 1, segunda = 2, etc).\nValores inv\u00E1lidos usam 1."
                 },
                 "getter": false,
                 "setter": false,
@@ -755,7 +809,7 @@ export class Wizard {
                 "optional": true,
                 "docs": {
                     "tags": [],
-                    "text": "\u00CDndice inicial zero-based. Quando informado, tem preced\u00EAncia sobre `initialStep`."
+                    "text": "\u00CDndice inicial zero-based. Quando informado, tem preced\u00EAncia sobre `initialStep`; valores inv\u00E1lidos usam 0."
                 },
                 "getter": false,
                 "setter": false,

package/dist/collection/pages/scripts/component-controls-core.js

@@ -0,0 +1,95 @@
+(() => {
+  const MANAGED_CSS_START = '/* playground-controls:start */';
+  const MANAGED_CSS_END = '/* playground-controls:end */';
+
+  const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+  const parseHtml = (html) => new DOMParser().parseFromString(html || '', 'text/html');
+
+  const serializeBody = (doc, booleanAttributes = []) => {
+    let html = doc.body.innerHTML.trim();
+    booleanAttributes.forEach((attribute) => {
+      html = html.replace(new RegExp(`\\s${escapeRegExp(attribute)}=""(?=\\s|>)`, 'gi'), ` ${attribute}`);
+    });
+    return html;
+  };
+
+  const normalizeControlValue = (value) =>
+    value === undefined || value === null || value === 'null' ? '' : String(value);
+
+  const getTargetElement = (doc, instance) =>
+    Array.from(doc.body.querySelectorAll(instance.tag))[instance.index] || null;
+
+  const findInstances = (html, components) => {
+    const doc = parseHtml(html);
+    const knownTags = new Set(components.map((component) => component.tag));
+    const counters = new Map();
+
+    return Array.from(doc.body.querySelectorAll('*'))
+      .filter((element) => knownTags.has(element.tagName.toLowerCase()))
+      .map((element) => {
+        const tag = element.tagName.toLowerCase();
+        const index = counters.get(tag) || 0;
+        counters.set(tag, index + 1);
+        return {
+          tag,
+          index,
+          label: counters.get(tag) > 1 ? `${tag} #${index + 1}` : tag,
+        };
+      });
+  };
+
+  const getSlotValue = (element, slotName) => {
+    if (!element) return '';
+    if (slotName === 'default') return element.innerHTML.trim();
+    return element.querySelector(`[slot="${slotName}"]`)?.innerHTML.trim() || '';
+  };
+
+  const getPropertyValue = (element, prop) => {
+    if (!element) return '';
+    const propName = prop.fieldName || prop.attribute;
+    const value = element[propName] !== undefined ? element[propName] : element.getAttribute(prop.attribute);
+    return value === null || value === undefined ? '' : String(value);
+  };
+
+  const updateProperty = (target, prop, value) => {
+    if (prop.control === 'checkbox') {
+      if (value) target.setAttribute(prop.attribute, '');
+      else target.removeAttribute(prop.attribute);
+      return;
+    }
+
+    const normalized = normalizeControlValue(value);
+    if (normalized.trim().length > 0) target.setAttribute(prop.attribute, normalized);
+    else target.removeAttribute(prop.attribute);
+  };
+
+  const getBooleanAttributes = (definition) =>
+    definition.props.filter(({ control }) => control === 'checkbox').map(({ attribute }) => attribute);
+
+  const updateManagedCss = (currentCss, tag, partValues, scopeSelector = '') => {
+    const selectorPrefix = scopeSelector.trim();
+    const rules = Object.entries(partValues)
+      .map(([part, value]) => [part, normalizeControlValue(value).trim()])
+      .filter(([, value]) => value.length > 0)
+      .map(([part, value]) => `${selectorPrefix ? `${selectorPrefix} ` : ''}${tag}::part(${part}) {\n  ${value}\n}`)
+      .join('\n\n');
+    const block = rules ? `${MANAGED_CSS_START}\n${rules}\n${MANAGED_CSS_END}` : '';
+    const pattern = new RegExp(`\\n?${escapeRegExp(MANAGED_CSS_START)}[\\s\\S]*?${escapeRegExp(MANAGED_CSS_END)}\\n?`);
+    const withoutBlock = currentCss.replace(pattern, '').trimEnd();
+    return block ? `${withoutBlock}${withoutBlock ? '\n\n' : ''}${block}` : withoutBlock;
+  };
+
+  window.WBCComponentControlsCore = Object.freeze({
+    findInstances,
+    getBooleanAttributes,
+    getPropertyValue,
+    getSlotValue,
+    getTargetElement,
+    normalizeControlValue,
+    parseHtml,
+    serializeBody,
+    updateManagedCss,
+    updateProperty,
+  });
+})();