@nuvia-ui/components 4.0.1

package/src/ds-stepper/ds-stepper.js

@@ -0,0 +1,207 @@
+import { LitElement, html, css } from 'lit';
+import '../ds-stepper-item/ds-stepper-item.js';
+
+/**
+ * Stepper container component for displaying progress through steps.
+ * 
+ * Supports two modes:
+ * - **Uncontrolled**: Omit `active-step` and the component manages its own state.
+ * - **Controlled**: Set `active-step` to control state from the parent.
+ * 
+ * @element ds-stepper
+ * 
+ * @prop {string} direction - Layout direction: 'horizontal' | 'vertical'
+ * @prop {number} activeStep - Zero-based index of the active step (controlled mode).
+ * @prop {number} defaultActiveStep - Initial active step for uncontrolled mode (default: 0).
+ * @prop {boolean} linear - When true, only completed and current steps are
+ *   interactive. When false (default), all non-disabled steps are clickable.
+ * @prop {boolean} autoComplete - When true (default), steps before activeStep are
+ *   automatically marked as completed. When false, completed state is controlled
+ *   manually via the `completed` prop on each ds-stepper-item.
+ * @prop {string} label - Accessible label for the stepper group (default: "Progress")
+ * 
+ * @slot - Default slot for ds-stepper-item elements
+ * 
+ * @fires ds-change - Fired when the active step changes, with detail { currentStep, previousStep }
+ */
+export class DsStepper extends LitElement {
+    static properties = {
+        direction: { type: String, reflect: true },
+        activeStep: { type: Number, attribute: 'active-step', reflect: true },
+        defaultActiveStep: { type: Number, attribute: 'default-active-step' },
+        linear: { type: Boolean, reflect: true },
+        autoComplete: { type: Boolean, attribute: 'auto-complete', reflect: true },
+        label: { type: String },
+        _internalActiveStep: { type: Number, state: true }
+    };
+
+    static styles = css`
+    :host {
+      display: flex;
+      width: 100%;
+      box-sizing: border-box;
+    }
+
+    :host([direction="vertical"]) {
+      flex-direction: column;
+    }
+
+    ::slotted(ds-stepper-item) {
+      flex: 1;
+    }
+  `;
+
+    constructor() {
+        super();
+        this.direction = 'horizontal';
+        this.activeStep = undefined;
+        this.defaultActiveStep = 0;
+        this.linear = false;
+        this.autoComplete = true;
+        this.label = 'Progress';
+        this._internalActiveStep = 0;
+    }
+
+    connectedCallback() {
+        super.connectedCallback();
+        // ARIA: group role with label
+        this.setAttribute('role', 'group');
+        this.addEventListener('ds-step-click', this._handleStepClick);
+        this.addEventListener('ds-step-update', this._handleStepUpdate);
+
+        // Initialize internal state if controlled prop is present
+        if (this.activeStep !== undefined) {
+            this._internalActiveStep = this.activeStep;
+        } else {
+            this._internalActiveStep = this.defaultActiveStep;
+        }
+    }
+
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.removeEventListener('ds-step-click', this._handleStepClick);
+        this.removeEventListener('ds-step-update', this._handleStepUpdate);
+    }
+
+    firstUpdated() {
+        this._updateChildren();
+    }
+
+    updated(changedProperties) {
+        super.updated(changedProperties);
+
+        // Sync internal state with controlled prop
+        if (changedProperties.has('activeStep') && this.activeStep !== undefined) {
+            this._internalActiveStep = this.activeStep;
+        }
+
+        if (changedProperties.has('direction') ||
+            changedProperties.has('activeStep') ||
+            changedProperties.has('_internalActiveStep') ||
+            changedProperties.has('linear') ||
+            changedProperties.has('autoComplete')) {
+            this._updateChildren();
+        }
+        // Keep aria-label in sync
+        if (changedProperties.has('label')) {
+            this.setAttribute('aria-label', this.label);
+        }
+    }
+
+    _handleStepClick = (e) => {
+        // Stop the raw step click from bubbling out, we will emit ds-change instead
+        e.stopPropagation();
+
+        const stepIndex = e.detail.step - 1; // Convert 1-based to 0-based
+        const oldStep = this._internalActiveStep;
+
+        // If clicked same step, do nothing
+        if (stepIndex === oldStep) return;
+
+        // Emit change event
+        const event = new CustomEvent('ds-change', {
+            bubbles: true,
+            composed: true,
+            detail: {
+                currentStep: stepIndex, // 0-based to match activeStep prop
+                previousStep: oldStep
+            }
+        });
+        this.dispatchEvent(event);
+
+        // If Uncontrolled (activeStep prop is undefined), update internal state
+        if (this.activeStep === undefined && !event.defaultPrevented) {
+            this._internalActiveStep = stepIndex;
+        }
+    }
+
+    _handleStepUpdate = () => {
+        this._updateChildren();
+    }
+
+    _handleSlotChange() {
+        this._updateChildren();
+    }
+
+    _updateChildren() {
+        const slot = this.shadowRoot?.querySelector('slot');
+        if (!slot) return;
+
+        const items = slot.assignedElements().filter(el => el.tagName === 'DS-STEPPER-ITEM');
+        const total = items.length;
+
+        // Use internal state which handles both controlled and uncontrolled
+        const currentActiveIndex = this._internalActiveStep;
+
+        items.forEach((item, index) => {
+            // Set direction
+            item._direction = this.direction;
+
+            // Set position
+            if (index === 0) {
+                item._position = 'first';
+            } else if (index === total - 1) {
+                item._position = 'last';
+            } else {
+                item._position = 'middle';
+            }
+
+            // Set step number and total
+            item._step = index + 1;
+            item._totalSteps = total;
+
+            // Set linear mode
+            item._linear = this.linear;
+
+            // Update state based on current internal active index
+            // Only auto-complete if autoComplete=true
+            if (this.autoComplete) {
+                item.completed = index < currentActiveIndex;
+            }
+            // Note: if autoComplete=false, we never set completed — 
+            // it is fully controlled by the consumer via the `completed` attribute
+
+            item.current = index === currentActiveIndex;
+
+            // Set previous step completed status (for connector coloring)
+            if (index > 0) {
+                const prevItem = items[index - 1];
+                item._prevCompleted = prevItem.completed;
+                item._prevError = prevItem.error || false;
+            } else {
+                item._prevCompleted = false;
+                item._prevError = false;
+            }
+        });
+    }
+
+    render() {
+        return html`
+      <slot @slotchange=${this._handleSlotChange}></slot>
+    `;
+    }
+}
+
+if (!customElements.get('ds-stepper')) {
+    customElements.define('ds-stepper', DsStepper);
+}