@design.estate/dees-catalog 9.5.0 → 9.6.0

package/ts_web/elements/00group-layout/dees-stepper/dees-stepper.ts

@@ -4,9 +4,9 @@ import {
   DeesElement,
   customElement,
   html,
-  css,
   cssManager,
   property,
+  state,
   type TemplateResult,
 } from '@design.estate/dees-element';
 
@@ -14,11 +14,13 @@ import * as domtools from '@design.estate/dees-domtools';
 import { stepperDemo } from './dees-stepper.demo.js';
 import { themeDefaultStyles } from '../../00theme.js';
 import { zIndexRegistry } from '../../00zindex.js';
-import { DeesWindowLayer } from '../../00group-overlay/dees-windowlayer/dees-windowlayer.js';
 import { DeesModal } from '../../00group-overlay/dees-modal/dees-modal.js';
 import type { DeesForm } from '../../00group-form/dees-form/dees-form.js';
 import '../../00group-feedback/dees-progressbar/dees-progressbar.js';
 import '../dees-tile/dees-tile.js';
+import '../../00group-button/dees-button/dees-button.js';
+import '../../00group-utility/dees-icon/dees-icon.js';
+import { stepperStyles } from './styles.js';
 
 export interface IStepProgressState {
   label?: string;
@@ -36,6 +38,7 @@ export interface IStepProgress extends IStepProgressState {
 
 export interface IStep {
   title: string;
+  description?: string;
   content: TemplateResult;
   allowBack?: boolean;
   progressStep?: IStepProgress;
@@ -70,14 +73,12 @@ export class DeesStepper extends DeesElement {
     if (optionsArg.cancelable !== undefined) {
       stepper.cancelable = optionsArg.cancelable;
     }
-    stepper.windowLayer = await DeesWindowLayer.createAndShow({ blur: true });
-    body.append(stepper.windowLayer);
     body.append(stepper);
 
-    // Get z-index for stepper (should be above window layer)
+    // Share overlay ordering with catalog controls opened from this dialog.
     stepper.stepperZIndex = zIndexRegistry.getNextZIndex();
     zIndexRegistry.register(stepper, stepper.stepperZIndex);
-
+    await stepper.updateComplete;
     return stepper;
   }
 
@@ -121,290 +122,46 @@ export class DeesStepper extends DeesElement {
 
   private activeFormSubscription?: { unsubscribe: () => void };
 
-  private windowLayer?: DeesWindowLayer;
+  @state() private accessor stepError = '';
+  @state() private accessor progressRunning = false;
+  @state() private accessor actionPending = false;
+  private resizeObserver?: ResizeObserver;
+  private activeValidationStep?: IStep;
+  private actionStep?: IStep;
+  private destroyPromise?: Promise<void>;
+  private scrollTarget?: number;
+  private scrollInFlight = false;
+  private cancelRequestPending = false;
 
   constructor() {
     super();
+    this.registerStartupFunction(async (signal) => {
+      await this.updateComplete;
+      if (signal.aborted) return;
+      this.destroyPromise = undefined;
+      const dialog = this.shadowRoot?.querySelector('dialog');
+      if (dialog && !dialog.open) dialog.showModal();
+      this.resizeObserver = new ResizeObserver(() => this.positionSelectedStep(false));
+      this.resizeObserver.observe(this.shadowRoot!.querySelector('.stepperContainer')!);
+      for (const tile of this.shadowRoot!.querySelectorAll('.step')) this.resizeObserver.observe(tile);
+      await this.setScrollStatus();
+    });
   }
 
-  public static styles = [
-    themeDefaultStyles,
-    cssManager.defaultStyles,
-    css`
-      /* TODO: Migrate hardcoded values to --dees-* CSS variables */
-      :host {
-        position: absolute;
-        width: 100%;
-        height: 100%;
-        font-family: var(--dees-font-family);
-        color: var(--dees-color-text-primary);
-      }
-
-      /*
-       * In overlay mode the host is "transparent" to layout — the inner
-       * .stepperContainer.overlay is what pins to the viewport and carries the
-       * z-index. Keeping :host unpositioned avoids nesting the stacking context
-       * under an auto-z-index parent (which was trapping .stepperContainer
-       * below DeesWindowLayer's sibling layers). This mirrors how dees-modal
-       * keeps its own :host unpositioned and lets .modalContainer drive layout.
-       */
-      :host([overlay]) {
-        position: static;
-        width: 0;
-        height: 0;
-      }
-
-      .stepperContainer {
-        position: absolute;
-        width: 100%;
-        height: 100%;
-        overflow: hidden;
-      }
-
-      .stepperContainer.overlay {
-        position: fixed;
-        top: 0;
-        left: 0;
-        width: 100vw;
-        height: 100vh;
-      }
-
-      /* Exit animation — reverse of the entry. Tiles slide DOWN + fade out,
-         mirroring the .entrance slide-up. The transition override is needed
-         because dees-tile.step has its own 0.7s transition for step selection
-         which would otherwise make the exit sluggish. */
-      .stepperContainer.predestroy dees-tile.step {
-        transform: translateY(16px);
-        filter: opacity(0);
-        transition: transform 0.25s, filter 0.2s;
-      }
-
-      dees-tile.step {
-        position: relative;
-        pointer-events: none;
-        box-sizing: border-box;
-        width: min(500px, calc(100vw - 32px));
-        max-width: 500px;
-        max-height: calc(100vh - 64px);
-        min-height: min(300px, calc(100vh - 64px));
-        margin: auto;
-        margin-bottom: 20px;
-        filter: opacity(0.55) saturate(0.85);
-        transition: transform 0.7s cubic-bezier(0.87, 0, 0.13, 1), filter 0.7s cubic-bezier(0.87, 0, 0.13, 1);
-        user-select: none;
-      }
-
-      dees-tile.step.selected {
-        pointer-events: all;
-        filter: opacity(1) saturate(1);
-        user-select: auto;
-      }
-
-      dees-tile.step.hiddenStep {
-        filter: opacity(0);
-      }
-
-      dees-tile.step.entrance {
-        transition: transform 0.35s ease, filter 0.35s ease;
-      }
-
-      dees-tile.step.entrance.hiddenStep {
-        transform: translateY(16px);
-      }
-
-      dees-tile.step:last-child {
-        margin-bottom: 100vh;
-      }
-
-      .stepperContainer.overlay dees-tile.step::part(outer) {
-        box-shadow:
-          0 0 0 1px color-mix(in srgb, var(--dees-color-text-primary) 3%, transparent),
-          var(--dees-shadow-lg);
-      }
-
-      .stepperContainer:not(.overlay) dees-tile.step {
-        max-height: calc(100% - 64px);
-        min-height: min(300px, calc(100% - 64px));
-      }
-
-      .step-header {
-        height: 36px;
-        display: flex;
-        align-items: center;
-        justify-content: space-between;
-        padding: 0 8px 0 12px;
-        gap: 12px;
-      }
-
-      .goBack-spacer {
-        width: 1px;
-      }
-
-      .step-header .goBack {
-        display: inline-flex;
-        align-items: center;
-        gap: 6px;
-        height: 24px;
-        padding: 0 8px;
-        font-size: 12px;
-        font-weight: 500;
-        line-height: 1;
-        border: none;
-        background: transparent;
-        color: var(--dees-color-text-muted);
-        border-radius: var(--dees-radius-sm);
-        cursor: pointer;
-        transition:
-          background-color var(--dees-transition-fast) var(--dees-ease-standard),
-          color var(--dees-transition-fast) var(--dees-ease-standard),
-          transform var(--dees-transition-default) var(--dees-ease-standard);
-      }
-
-      .step-header .goBack:hover {
-        background: var(--dees-color-hover);
-        color: var(--dees-color-text-secondary);
-        transform: translateX(-2px);
-      }
-
-      .step-header .goBack:active {
-        background: var(--dees-color-border-default);
-      }
-
-      .step-header .goBack span {
-        transition: transform var(--dees-transition-default) var(--dees-ease-standard);
-        display: inline-block;
-      }
-
-      .step-header .goBack:hover span {
-        transform: translateX(-2px);
-      }
-
-      .step-header .stepCounter {
-        color: var(--dees-color-text-muted);
-        font-size: 12px;
-        font-weight: 500;
-        letter-spacing: -0.01em;
-        padding: 0 8px;
-      }
-
-      .step-body .title {
-        text-align: center;
-        padding-top: 32px;
-        font-family: var(--dees-font-family);
-        font-size: 24px;
-        font-weight: 600;
-        letter-spacing: -0.01em;
-        color: inherit;
-      }
-
-      .step-body .content {
-        padding: 32px;
-      }
-
-      .step-body .content.withProgressStep {
-        padding-top: 20px;
-      }
-
-      .progressStep {
-        padding: 0 24px;
-      }
-
-      /* --- Footer: modal-style bottom buttons --- */
-      .bottomButtons {
-        display: flex;
-        flex-direction: row;
-        justify-content: flex-end;
-        align-items: center;
-        gap: 0;
-        height: 36px;
-        width: 100%;
-        box-sizing: border-box;
-      }
-
-      .bottomButtons .bottomButton {
-        padding: 0 16px;
-        height: 100%;
-        text-align: center;
-        font-size: 12px;
-        font-weight: 500;
-        cursor: pointer;
-        user-select: none;
-        transition:
-          background-color var(--dees-transition-fast) var(--dees-ease-standard),
-          color var(--dees-transition-fast) var(--dees-ease-standard);
-        background: transparent;
-        border: none;
-        color: var(--dees-color-text-muted);
-        white-space: nowrap;
-        display: flex;
-        align-items: center;
-      }
-
-      /* Border-left separator on every button EXCEPT the first one.
-         Uses general sibling so the stepHint (if rendered on the left) does
-         not shift which button counts as "first" and create a phantom border. */
-      .bottomButtons .bottomButton ~ .bottomButton {
-        border-left: 1px solid var(--dees-color-border-subtle);
-      }
-
-      .bottomButtons .bottomButton:hover {
-        background: var(--dees-color-hover);
-        color: var(--dees-color-text-primary);
-      }
-
-      .bottomButtons .bottomButton:active {
-        background: var(--dees-color-border-subtle);
-      }
-
-      .bottomButtons .bottomButton.primary {
-        color: var(--dees-color-link);
-        font-weight: 600;
-      }
-
-      .bottomButtons .bottomButton.primary:hover {
-        background: color-mix(in srgb, var(--dees-color-link) 8%, transparent);
-        color: color-mix(in srgb, var(--dees-color-link) 80%, var(--dees-color-text-primary));
-      }
-
-      .bottomButtons .bottomButton.primary:active {
-        background: color-mix(in srgb, var(--dees-color-link) 12%, transparent);
-      }
-
-      .bottomButtons .bottomButton.disabled {
-        pointer-events: none;
-        opacity: 0.4;
-        cursor: not-allowed;
-      }
-
-      .bottomButtons .bottomButton.disabled:hover {
-        background: transparent;
-        color: var(--dees-color-text-muted);
-      }
-
-      /* Hint shown on the left of the footer when the active step's form has
-         unfilled required fields. Uses margin-right: auto to push right-aligned
-         buttons to the right while keeping the hint flush-left. */
-      .bottomButtons .stepHint {
-        margin-right: auto;
-        padding: 0 16px;
-        font-size: 11px;
-        line-height: 1;
-        letter-spacing: -0.01em;
-        color: var(--dees-color-text-muted);
-        display: flex;
-        align-items: center;
-        user-select: none;
-      }
-    `,
-  ];
+  public static styles = [themeDefaultStyles, cssManager.defaultStyles, stepperStyles];
 
   public render() {
+    const label = this.selectedStep?.title ?? 'Setup';
+    return this.overlay
+      ? html`<dialog class="stepperContainer overlay" aria-label=${label} aria-modal="true"
+          style=${`z-index: ${this.stepperZIndex};`} @cancel=${this.handleDialogCancel}
+          @click=${this.handleOutsideClick}>${this.renderSteps()}</dialog>`
+      : html`<div class="stepperContainer" role="region" aria-label=${label}>${this.renderSteps()}</div>`;
+  }
+
+  private renderSteps() {
+    if (!this.steps.length) return html`<div class="empty">No steps to show.</div>`;
     return html`
-      <div
-        class="stepperContainer ${this.overlay ? 'overlay' : ''}"
-        style=${this.overlay ? `z-index: ${this.stepperZIndex};` : ''}
-        @click=${this.handleOutsideClick}
-      >
         ${this.steps.map((stepArg, stepIndex) => {
           const isSelected = stepArg === this.selectedStep;
           const isHidden =
@@ -413,21 +170,24 @@ export class DeesStepper extends DeesElement {
           const showBackButton = !isFirst && stepArg.allowBack !== false;
           const progressStepState = stepArg.progressStep ? this.getProgressStepState(stepArg) : null;
           return html`<dees-tile
-            class="step ${isSelected ? 'selected' : ''} ${isHidden ? 'hiddenStep' : ''} ${isFirst ? 'entrance' : ''}"
-            overscroll="contain"
+            class="step ${isSelected ? 'selected' : ''} ${isHidden ? 'hiddenStep' : ''}"
+            overscroll="contain" ?inert=${!isSelected} aria-hidden=${!isSelected}
           >
             <div slot="header" class="step-header">
-              ${showBackButton
-                ? html`<div class="goBack" @click=${this.goBack}>
-                    <span><-</span> go to previous step
-                  </div>`
-                : html`<div class="goBack-spacer"></div>`}
-              <div class="stepCounter">
-                Step ${stepIndex + 1} of ${this.steps.length}
-              </div>
+              <ol class="step-rail" aria-label="Progress">${this.steps.map((step, index) => html`
+                <li class="step-marker ${index < stepIndex ? 'complete' : index === stepIndex ? 'current' : ''}"
+                  aria-label=${`${index + 1}. ${step.title}${index < stepIndex ? ', completed' : ''}`}
+                  aria-current=${index === stepIndex ? 'step' : 'false'} title=${step.title}></li>
+              `)}</ol>
+              <span class="step-counter">${stepIndex + 1} of ${this.steps.length}</span>
             </div>
             <div class="step-body">
-              <div class="title">${stepArg.title}</div>
+              <div class="heading-row">
+                <h2 class="title" tabindex="-1">${stepArg.title}</h2>
+                <span class="step-hint" aria-hidden=${!isSelected || this.activeForm === null || this.activeFormValid}
+                  title="Fill in the required fields to continue.">Complete required fields</span>
+              </div>
+              ${stepArg.description ? html`<p class="description">${stepArg.description}</p>` : ''}
               ${stepArg.progressStep && progressStepState ? html`
                 <div class="progressStep">
                   <dees-progressbar
@@ -442,31 +202,32 @@ export class DeesStepper extends DeesElement {
                 </div>
               ` : ''}
               <div class="content ${stepArg.progressStep ? 'withProgressStep' : ''}">${stepArg.content}</div>
+              ${isSelected && this.stepError ? html`<div class="step-error" role="alert">
+                <dees-icon icon="lucide:CircleAlert" iconSize="16"></dees-icon><span>${this.stepError}</span>
+              </div>` : ''}
             </div>
-            <div slot="footer" class="bottomButtons">
-              ${isSelected && this.activeForm !== null && !this.activeFormValid
-                ? html`<div class="stepHint">Complete form to continue</div>`
-                : ''}
+            <div slot="footer" class="step-footer">
+              <div class="bottomButtons">
+              ${showBackButton ? html`<dees-button class="back-action" type="ghost" text="Back"
+                icon="lucide:ChevronLeft" .disabled=${this.actionPending} @clicked=${this.goBack}></dees-button>`
+                : html`<span class="footer-spacer"></span>`}
               ${this.cancelable
-                ? html`<div
-                    class="bottomButton"
-                    @click=${() => this.handleCancelRequest()}
-                  >Cancel</div>`
+                ? html`<dees-button type="ghost" text="Cancel" @clicked=${this.handleCancelRequest}></dees-button>`
                 : ''}
+              ${isSelected && this.stepError && stepArg.validationFunc
+                ? html`<dees-button type="accent" text="Try again" icon="lucide:RotateCw" @clicked=${this.retryStep}></dees-button>` : ''}
               ${stepArg.menuOptions?.map((actionArg, actionIndex) => {
                 const isPrimary = actionIndex === stepArg.menuOptions!.length - 1;
-                const isDisabled = isPrimary && this.activeForm !== null && !this.activeFormValid;
-                return html`
-                  <div
-                    class="bottomButton ${isPrimary ? 'primary' : ''} ${isDisabled ? 'disabled' : ''}"
-                    @click=${() => this.handleMenuOptionClick(actionArg, isPrimary)}
-                  >${actionArg.name}</div>
-                `;
+                const isDisabled = this.actionPending || (isPrimary && (!this.activeFormValid || this.progressRunning || (!!this.stepError && !!stepArg.progressStep)));
+                return html`<dees-button class="step-action" .text=${actionArg.name}
+                  .icon=${actionArg.iconName ?? ''} .type=${isPrimary ? 'accent' : 'secondary'}
+                  .disabled=${isDisabled} .status=${isPrimary && this.actionPending ? 'pending' : 'normal'}
+                  @clicked=${() => this.handleMenuOptionClick(actionArg, isPrimary)}></dees-button>`;
               }) ?? ''}
+              </div>
             </div>
           </dees-tile>`;
         })}
-      </div>
     `;
   }
 
@@ -474,74 +235,88 @@ export class DeesStepper extends DeesElement {
     return this.steps.findIndex((stepArg2) => stepArg === stepArg2);
   };
 
-  public async firstUpdated() {
-    await this.domtoolsPromise;
-    await this.domtools.convenience.smartdelay.delayFor(0);
-    if (!this.steps.length) {
-      return;
+  protected willUpdate(changed: Map<PropertyKey, unknown>) {
+    if (changed.has('steps') && !this.steps.includes(this.selectedStep)) this.selectedStep = this.steps[0];
+    if (changed.has('selectedStep') || changed.has('steps')) {
+      if (this.activeValidationStep !== this.selectedStep) {
+        this.activeValidationStep?.abortController?.abort();
+        if (this.activeValidationStep) this.activeValidationStep.validationFuncCalled = false;
+        this.activeValidationStep = this.selectedStep;
+        this.stepError = '';
+        this.progressRunning = false;
+        this.actionPending = false;
+        this.actionStep = undefined;
+        this.prepareStepForActivation(this.selectedStep);
+      }
     }
-    this.prepareStepForActivation(this.steps[0]);
-    this.selectedStep = this.steps[0];
-    await this.updateComplete;
-    await this.setScrollStatus();
-    // Remove entrance class after initial animation completes
-    await this.domtools.convenience.smartdelay.delayFor(350);
-    this.shadowRoot!.querySelector('.step.entrance')?.classList.remove('entrance');
   }
 
   public async updated(changedProperties: Map<string | number | symbol, unknown>) {
-    if (!changedProperties.has('selectedStep') && !changedProperties.has('steps')) {
-      return;
+    if (changedProperties.has('overlay')) {
+      this.scroller?.destroy();
+      this.scroller = undefined!;
+      this.scrollTarget = undefined;
+      this.scrollInFlight = false;
     }
-
+    const dialog = this.shadowRoot?.querySelector('dialog');
+    if (dialog && !dialog.open && this.isConnected) dialog.showModal();
+    if (!changedProperties.has('selectedStep') && !changedProperties.has('steps') && !changedProperties.has('overlay')) return;
     await this.setScrollStatus();
+    if (!this.isConnected) return;
+    if (changedProperties.has('steps') || changedProperties.has('overlay')) {
+      this.resizeObserver?.disconnect();
+      this.resizeObserver?.observe(this.shadowRoot!.querySelector('.stepperContainer')!);
+      for (const tile of this.shadowRoot!.querySelectorAll('.step')) this.resizeObserver?.observe(tile);
+    }
+    if (this.overlay || this.shadowRoot?.activeElement) {
+      this.shadowRoot?.querySelector<HTMLElement>('.selected .title')?.focus({ preventScroll: true });
+    }
   }
 
   public scroller!: typeof domtools.plugins.SweetScroll.prototype;
 
   public async setScrollStatus() {
-    const stepperContainer = this.shadowRoot!.querySelector('.stepperContainer') as HTMLElement;
-    const selectedStepElement = this.shadowRoot!.querySelector('.selected') as HTMLElement;
-    if (!selectedStepElement) {
-      return;
-    }
+    const step = this.selectedStep;
+    const selectedStepElement = this.shadowRoot?.querySelector<HTMLElement>('.step.selected');
+    if (!selectedStepElement || !this.isConnected) return;
+    const form = selectedStepElement.querySelector('dees-form');
+    await form?.updateComplete;
+    if (!this.isConnected || step !== this.selectedStep) return;
     this.scanActiveForm(selectedStepElement);
-    if (!stepperContainer.style.paddingTop) {
-      stepperContainer.style.paddingTop = `${
-        stepperContainer.offsetHeight / 2 - selectedStepElement.offsetHeight / 2
-      }px`;
+    this.positionSelectedStep(true);
+    if (!step.validationFuncCalled && step.validationFunc) {
+      step.abortController = new AbortController();
+      step.validationFuncCalled = true;
+      void this.runStepValidation(step, selectedStepElement, step.abortController.signal);
     }
-    const scrollPosition =
-      selectedStepElement.offsetTop -
-      stepperContainer.offsetHeight / 2 +
-      selectedStepElement.offsetHeight / 2;
-    await domtools.DomTools.setupDomTools();
+  }
+
+  private positionSelectedStep(animate: boolean) {
+    const container = this.shadowRoot?.querySelector<HTMLElement>('.stepperContainer');
+    const selected = this.shadowRoot?.querySelector<HTMLElement>('.step.selected');
+    const first = this.shadowRoot?.querySelector<HTMLElement>('.step');
+    if (!container || !selected || !first || !this.isConnected) return;
+    container.style.paddingTop = `${Math.max(24, (container.clientHeight - first.offsetHeight) / 2)}px`;
+    const position = Math.max(0, selected.offsetTop - (container.clientHeight - selected.offsetHeight) / 2);
     if (!this.scroller) {
       this.scroller = new domtools.plugins.SweetScroll(
-        {
-          vertical: true,
-          horizontal: false,
-          easing: 'easeInOutExpo',
-          duration: 700,
-        },
-        stepperContainer
-      );
-    }
-    if (!this.selectedStep.validationFuncCalled && this.selectedStep.validationFunc) {
-      this.selectedStep.abortController = new AbortController();
-      this.selectedStep.validationFuncCalled = true;
-      void this.runStepValidation(
-        this.selectedStep,
-        selectedStepElement,
-        this.selectedStep.abortController.signal,
+        { vertical: true, horizontal: false, easing: 'easeOutCubic', duration: 320, cancellable: false },
+        container
       );
+      animate = false;
     }
-    this.scroller.to(scrollPosition);
+    // Form validity can resize the footer after selection. Retarget the active
+    // scroll instead of letting ResizeObserver snap it to the destination.
+    if (this.scrollTarget !== undefined && Math.abs(this.scrollTarget - position) < 1) return;
+    const duration = (animate || this.scrollInFlight) && !matchMedia('(prefers-reduced-motion: reduce)').matches ? 320 : 0;
+    this.scrollTarget = position;
+    this.scroller.to(position, { duration, complete: () => { this.scrollInFlight = false; } });
+    this.scrollInFlight = duration > 0;
   }
 
   public async goBack() {
     const currentIndex = this.steps.findIndex((stepArg) => stepArg === this.selectedStep);
-    if (currentIndex <= 0) {
+    if (currentIndex <= 0 || this.selectedStep.allowBack === false) {
       return;
     }
     // Abort any active listeners on current step
@@ -554,9 +329,11 @@ export class DeesStepper extends DeesElement {
     previousStep.validationFuncCalled = false;
     this.prepareStepForActivation(previousStep);
     this.selectedStep = previousStep;
-    await this.domtoolsPromise;
-    await this.domtools.convenience.smartdelay.delayFor(100);
-    this.selectedStep.onReturnToStepFunc?.(this, this.shadowRoot!.querySelector('.selected') as HTMLElement);
+    await this.updateComplete;
+    if (this.isConnected && this.selectedStep === previousStep) {
+      try { await previousStep.onReturnToStepFunc?.(this, this.shadowRoot!.querySelector('.selected') as HTMLElement); }
+      catch (error) { if (this.selectedStep === previousStep) this.stepError = error instanceof Error ? error.message : 'Could not return to this step.'; }
+    }
   }
 
   public goNext() {
@@ -659,9 +436,11 @@ export class DeesStepper extends DeesElement {
       return;
     }
     const fields = form.getFormElements();
-    this.activeFormValid = fields.every(
-      (field) => !field.required || (field.value !== null && field.value !== undefined && field.value !== ''),
-    );
+    this.activeFormValid = fields.every(field => {
+      if (!field.required || field.disabled) return true;
+      const value = 'getValue' in field && field.getValue ? field.getValue() : field.value;
+      return value !== null && value !== undefined && value !== '' && value !== false && (!Array.isArray(value) || value.length > 0);
+    });
   }
 
   /**
@@ -675,15 +454,23 @@ export class DeesStepper extends DeesElement {
     optionArg: plugins.tsclass.website.IMenuItem<DeesStepper>,
     isPrimary: boolean,
   ) {
+    if (this.actionPending || (isPrimary && this.progressRunning)) return;
+    this.recomputeFormValid();
     const form = this.activeForm;
-    if (isPrimary && form) {
-      if (!this.activeFormValid) return;
-      await new Promise<void>((resolve) => {
-        form.addEventListener('formData', () => resolve(), { once: true });
-        form.gatherAndDispatch();
-      });
+    if (isPrimary && !this.activeFormValid) return;
+    const step = this.selectedStep;
+    this.actionPending = true;
+    this.actionStep = step;
+    this.stepError = '';
+    try {
+      if (isPrimary && form) await form.gatherAndDispatch();
+      if (!this.isConnected || step !== this.selectedStep) return;
+      await optionArg.action(this);
+    } catch (error) {
+      if (this.isConnected && step === this.selectedStep) this.stepError = error instanceof Error ? error.message : 'The action could not be completed. Try again.';
+    } finally {
+      if (this.actionStep === step) { this.actionPending = false; this.actionStep = undefined; }
     }
-    await optionArg.action(this);
   }
 
   private getProgressStepState(stepArg: IStep): IStepProgressState {
@@ -691,11 +478,7 @@ export class DeesStepper extends DeesElement {
       return {};
     }
 
-    if (!stepArg.progressStepState) {
-      stepArg.progressStepState = this.createInitialProgressStepState(stepArg);
-    }
-
-    return stepArg.progressStepState;
+    return stepArg.progressStepState ?? this.createInitialProgressStepState(stepArg);
   }
 
   private createInitialProgressStepState(stepArg: IStep): IStepProgressState {
@@ -723,10 +506,11 @@ export class DeesStepper extends DeesElement {
     selectedStepElement: HTMLElement,
     signal: AbortSignal,
   ): Promise<void> {
+    this.progressRunning = !!stepArg.progressStep;
     try {
       await stepArg.validationFunc?.(this, selectedStepElement, signal);
 
-      if (signal.aborted) {
+      if (signal.aborted || !this.isConnected || this.selectedStep !== stepArg) {
         return;
       }
 
@@ -734,12 +518,13 @@ export class DeesStepper extends DeesElement {
         this.goNext();
       }
     } catch (error) {
-      if (signal.aborted) {
+      if (signal.aborted || !this.isConnected || this.selectedStep !== stepArg) {
         return;
       }
 
+      const errorText = error instanceof Error ? error.message : 'This step could not be completed. Try again.';
+      this.stepError = errorText;
       if (stepArg.progressStep) {
-        const errorText = error instanceof Error ? error.message : 'Unexpected error';
         this.appendProgressStepLine(`Error: ${errorText}`, stepArg);
         this.updateProgressStep(
           {
@@ -750,10 +535,27 @@ export class DeesStepper extends DeesElement {
         );
       }
 
-      console.error(error);
+    } finally {
+      if (!signal.aborted && this.selectedStep === stepArg) this.progressRunning = false;
     }
   }
 
+  /** Rerun the current step after a recoverable validation/provisioning failure. */
+  public async retryStep() {
+    const step = this.selectedStep;
+    if (!step?.validationFunc || this.progressRunning || this.actionPending) return;
+    step.abortController?.abort();
+    step.validationFuncCalled = false;
+    this.stepError = '';
+    this.prepareStepForActivation(step);
+    await this.setScrollStatus();
+  }
+
+  private handleDialogCancel(event: Event) {
+    event.preventDefault();
+    void this.handleCancelRequest();
+  }
+
   /**
    * Currently-open confirmation modal (if any). Prevents double-stacking when
    * the user clicks the backdrop or the Cancel button while a confirm modal
@@ -793,10 +595,11 @@ export class DeesStepper extends DeesElement {
    * fallback check.
    */
   public async handleCancelRequest() {
-    if (!this.cancelable) return;
+    if (!this.cancelable || this.cancelRequestPending || !this.isConnected) return;
     if (this.cancelConfirmModal && this.cancelConfirmModal.isConnected) return;
     this.cancelConfirmModal = undefined;
-    this.cancelConfirmModal = await DeesModal.createAndShow({
+    this.cancelRequestPending = true;
+    try { this.cancelConfirmModal = await DeesModal.createAndShow({
       heading: 'Cancel setup?',
       width: 'small',
       content: html`
@@ -816,37 +619,50 @@ export class DeesStepper extends DeesElement {
           name: 'Yes, cancel',
           action: async (modal) => {
             this.cancelConfirmModal = undefined;
-            modal!.destroy(); // fire-and-forget — starts the confirm modal fade
-            const domtools = await this.domtoolsPromise;
-            await domtools.convenience.smartdelay.delayFor(100);
+            await modal!.destroy();
             await this.destroy();
           },
         },
       ],
     });
+    if (!this.isConnected) await this.cancelConfirmModal.destroy();
+    } finally { this.cancelRequestPending = false; }
   }
 
-  public async destroy() {
-    const domtools = await this.domtoolsPromise;
-    const container = this.shadowRoot!.querySelector('.stepperContainer');
-    if (this.selectedStep?.abortController) {
-      this.selectedStep.abortController.abort();
-    }
-    container?.classList.add('predestroy');
-    await domtools.convenience.smartdelay.delayFor(250);
-    if (this.parentElement) {
-      this.parentElement.removeChild(this);
-    }
-    if (this.windowLayer) {
-      await this.windowLayer.destroy();
-    }
+  public destroy(): Promise<void> {
+    return this.destroyPromise ??= this.closeAndRemove();
+  }
 
-    // Tear down form subscription to avoid leaks when the overlay closes.
+  private async closeAndRemove() {
+    this.selectedStep?.abortController?.abort();
+    // Close nested dialogs first so the browser can restore the original opener.
+    if (this.cancelConfirmModal?.isConnected) await this.cancelConfirmModal.destroy();
+    this.shadowRoot?.querySelector('.stepperContainer')?.classList.add('predestroy');
+    const tile = this.shadowRoot?.querySelector('.step.selected');
+    if (tile) await Promise.allSettled(tile.getAnimations().map(animation => animation.finished));
+    this.shadowRoot?.querySelector('dialog')?.close();
+    this.remove();
+  }
+
+  public async disconnectedCallback() {
+    this.selectedStep?.abortController?.abort();
+    if (this.selectedStep) this.selectedStep.validationFuncCalled = false;
+    this.resizeObserver?.disconnect();
+    this.resizeObserver = undefined;
+    this.scroller?.destroy();
+    this.scroller = undefined!;
+    this.scrollTarget = undefined;
+    this.scrollInFlight = false;
+    this.shadowRoot?.querySelector('dialog')?.close();
+    if (this.cancelConfirmModal?.isConnected) void this.cancelConfirmModal.destroy();
     this.activeFormSubscription?.unsubscribe();
     this.activeFormSubscription = undefined;
     this.activeForm = null;
-
-    // Unregister from z-index registry
+    this.actionPending = false;
+    this.actionStep = undefined;
+    this.progressRunning = false;
     zIndexRegistry.unregister(this);
+    this.dispatchEvent(new CustomEvent('stepper-close', { bubbles: true, composed: true }));
+    await super.disconnectedCallback();
   }
 }