@3fn/core 13.0.0

package/dist/components/core/Button-VerticalList-Set/platforms/web/ButtonVerticalListSet.web.js

@@ -0,0 +1,1263 @@
+"use strict";
+/**
+ * Button-VerticalList-Set Web Component
+ *
+ * Stemma System: Buttons Family
+ * Component Type: Pattern (VerticalList-Set)
+ * Custom Element Tag: <button-vertical-list-set>
+ *
+ * Container/orchestrator component that manages selection behavior,
+ * state coordination, animations, keyboard navigation, and accessibility
+ * for vertical list button groups.
+ *
+ * RENDERING ARCHITECTURE:
+ * Uses incremental DOM updates rather than full re-renders to enable CSS transitions.
+ * - _createDOM(): Called once on first render, creates the full DOM structure
+ * - _updateDOM(): Called on attribute changes, updates only changed properties
+ * This preserves DOM element identity, allowing CSS transitions to animate smoothly.
+ *
+ * @module Button-VerticalList-Set/platforms/web
+ * @see Requirements: 2.1, 2.6, 11.2
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ButtonVerticalListSet = void 0;
+const types_1 = require("../../types");
+// Import CSS as string for browser bundle compatibility
+// The esbuild CSS-as-string plugin transforms this import into a JS string export
+const Button_VerticalList_Set_styles_css_1 = __importDefault(require("./Button-VerticalList-Set.styles.css"));
+/**
+ * Get the ARIA role for the container based on mode.
+ *
+ * @param mode - The selection mode
+ * @returns The appropriate ARIA role
+ * @see Requirements: 2.1, 3.4, 4.6, 5.4
+ */
+function getContainerRole(mode) {
+    switch (mode) {
+        case 'tap':
+            return 'group';
+        case 'select':
+            return 'radiogroup';
+        case 'multiSelect':
+            return 'group';
+        default:
+            return 'group';
+    }
+}
+/**
+ * Button-VerticalList-Set Web Component
+ *
+ * A native web component that orchestrates selection behavior and coordinates
+ * visual states across child Button-VerticalList-Item components.
+ *
+ * @remarks
+ * - Uses Shadow DOM for style encapsulation
+ * - Follows controlled component pattern (parent manages state)
+ * - Coordinates animation timing across children
+ * - Manages keyboard navigation with roving tabindex
+ * - Provides appropriate ARIA roles based on mode
+ *
+ * @example
+ * ```html
+ * <!-- Tap mode - action buttons -->
+ * <button-vertical-list-set mode="tap">
+ *   <button-vertical-list-item label="Settings"></button-vertical-list-item>
+ *   <button-vertical-list-item label="Help"></button-vertical-list-item>
+ * </button-vertical-list-set>
+ *
+ * <!-- Select mode - single selection -->
+ * <button-vertical-list-set mode="select" selected-index="0">
+ *   <button-vertical-list-item label="Option A"></button-vertical-list-item>
+ *   <button-vertical-list-item label="Option B"></button-vertical-list-item>
+ * </button-vertical-list-set>
+ *
+ * <!-- MultiSelect mode - multiple selections -->
+ * <button-vertical-list-set mode="multiSelect" selected-indices="[0,2]">
+ *   <button-vertical-list-item label="Choice 1"></button-vertical-list-item>
+ *   <button-vertical-list-item label="Choice 2"></button-vertical-list-item>
+ *   <button-vertical-list-item label="Choice 3"></button-vertical-list-item>
+ * </button-vertical-list-set>
+ * ```
+ *
+ * @see Requirements 2.1, 2.6, 11.2
+ */
+class ButtonVerticalListSet extends HTMLElement {
+    // ─────────────────────────────────────────────────────────────────
+    // Static Properties
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Observed attributes for attribute change callbacks.
+     *
+     * When these attributes change, attributeChangedCallback is invoked.
+     */
+    static get observedAttributes() {
+        return [
+            'mode',
+            'selected-index',
+            'selected-indices',
+            'required',
+            'min-selections',
+            'max-selections',
+            'error',
+            'error-message',
+            'test-id'
+        ];
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Constructor
+    // ─────────────────────────────────────────────────────────────────
+    constructor() {
+        super();
+        /** Whether DOM has been created */
+        this._domCreated = false;
+        // Cached DOM element references for incremental updates
+        this._container = null;
+        this._errorMessageEl = null;
+        // Props (backed by attributes)
+        this._mode = 'tap';
+        this._selectedIndex = null;
+        this._selectedIndices = [];
+        this._required = false;
+        this._error = false;
+        // Internal state for focus management and animation tracking
+        this._internalState = {
+            focusedIndex: 0,
+            previousSelectedIndex: null,
+            isFirstSelection: true
+        };
+        /**
+         * Handle slot change events.
+         *
+         * Called when children are added or removed from the slot.
+         */
+        this._handleSlotChange = () => {
+            // Update child items when slot content changes
+            this._updateChildItems();
+        };
+        /**
+         * Handle click events from child items.
+         *
+         * Determines which child was clicked and invokes appropriate callback
+         * based on the current mode.
+         *
+         * Mode behaviors:
+         * - **Tap**: Invokes onItemClick callback with clicked index
+         * - **Select**: Toggles selection (select new item or deselect if same)
+         * - **MultiSelect**: Toggles item in selection array (Task 3.4)
+         *
+         * @param event - The click event
+         * @see Requirements 3.2, 4.2, 4.3, 4.4, 4.5, 9.3, 9.5
+         */
+        this._handleChildClick = (event) => {
+            // Find the clicked child item
+            const target = event.target;
+            // Check if the click came from a button-vertical-list-item
+            const item = target.closest('button-vertical-list-item');
+            if (!item)
+                return;
+            // Get the index of the clicked item
+            const slot = this._shadowRoot.querySelector('slot');
+            if (!slot)
+                return;
+            const children = slot.assignedElements();
+            const index = children.indexOf(item);
+            if (index === -1)
+                return;
+            // Handle click based on mode
+            switch (this._mode) {
+                case 'tap':
+                    // Tap mode: Invoke callback with clicked index
+                    // No selection state tracking
+                    // @see Requirements 3.2, 9.5
+                    if (this._onItemClick) {
+                        this._onItemClick(index);
+                    }
+                    break;
+                case 'select':
+                    // Select mode: Single-selection (radio-button style)
+                    // @see Requirements 4.2, 4.3, 4.4, 4.5, 9.3
+                    this._handleSelectModeClick(index);
+                    break;
+                case 'multiSelect':
+                    // MultiSelect mode: Multiple-selection (checkbox style)
+                    // @see Requirements 5.2, 5.3, 9.4
+                    this._handleMultiSelectModeClick(index);
+                    break;
+            }
+        };
+        // ─────────────────────────────────────────────────────────────────
+        // Keyboard Navigation
+        // ─────────────────────────────────────────────────────────────────
+        /**
+         * Handle keyboard events for navigation.
+         *
+         * Implements keyboard navigation per WCAG 2.1 AA requirements:
+         * - Arrow Up/Down: Move focus between items with wrapping
+         * - Home: Move focus to first item
+         * - End: Move focus to last item
+         * - Enter/Space: Activate the focused item based on mode
+         *
+         * @param event - The keyboard event
+         * @see Requirements 8.2, 8.3, 8.4, 8.5
+         */
+        this._handleKeyDown = (event) => {
+            // Get all child items
+            const children = this._getChildItems();
+            const itemCount = children.length;
+            // No items to navigate
+            if (itemCount === 0)
+                return;
+            // Process the key and determine action
+            const result = this._processKeyboardNavigation(event, itemCount);
+            // If the key wasn't handled, let it propagate
+            if (!result.handled)
+                return;
+            // Prevent default behavior for handled keys
+            event.preventDefault();
+            // Update focus if needed
+            if (result.newFocusIndex !== this._internalState.focusedIndex) {
+                this._moveFocusToIndex(result.newFocusIndex, children);
+            }
+            // Activate item if needed (Enter/Space)
+            if (result.shouldActivate) {
+                this._activateItem(this._internalState.focusedIndex);
+            }
+        };
+        /**
+         * Handle focus-in events to track which item has focus.
+         *
+         * Updates the internal focused index when focus moves to a child item.
+         * This ensures the roving tabindex pattern stays in sync with actual focus.
+         *
+         * @param event - The focus event
+         * @see Requirement 8.6: Roving tabindex pattern
+         */
+        this._handleFocusIn = (event) => {
+            const target = event.target;
+            // Check if the focus target is a child item
+            const item = target.closest('button-vertical-list-item');
+            if (!item)
+                return;
+            // Get the index of the focused item
+            const children = this._getChildItems();
+            const index = children.indexOf(item);
+            if (index !== -1 && index !== this._internalState.focusedIndex) {
+                // Update internal state
+                this._internalState.focusedIndex = index;
+                // Update tabindex values to reflect new focus
+                this._updateTabIndices(children, index);
+            }
+        };
+        // Attach shadow DOM for style encapsulation
+        // delegatesFocus: true enables proper tab navigation
+        this._shadowRoot = this.attachShadow({ mode: 'open', delegatesFocus: true });
+        // Generate unique ID for error message element
+        this._errorMessageId = `vls-error-${Math.random().toString(36).slice(2, 11)}`;
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Lifecycle Callbacks
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Called when the element is added to the DOM.
+     *
+     * Performs initial render and sets up event listeners.
+     */
+    connectedCallback() {
+        // Defer rendering until DOM is ready to ensure CSS is applied
+        if (document.readyState === 'loading') {
+            document.addEventListener('DOMContentLoaded', () => {
+                this._render();
+            }, { once: true });
+        }
+        else {
+            this._render();
+        }
+    }
+    /**
+     * Called when the element is removed from the DOM.
+     *
+     * Cleans up event listeners to prevent memory leaks.
+     */
+    disconnectedCallback() {
+        this._detachEventListeners();
+    }
+    /**
+     * Called when an observed attribute changes.
+     *
+     * Triggers incremental DOM update to reflect the new attribute value.
+     *
+     * @param name - Attribute name
+     * @param oldValue - Previous attribute value
+     * @param newValue - New attribute value
+     */
+    attributeChangedCallback(name, oldValue, newValue) {
+        // Only update if value changed and DOM exists
+        if (oldValue === newValue)
+            return;
+        // Parse attribute values into internal properties
+        switch (name) {
+            case 'mode':
+                this._mode = newValue || 'tap';
+                break;
+            case 'selected-index':
+                this._selectedIndex = newValue !== null ? parseInt(newValue, 10) : null;
+                if (isNaN(this._selectedIndex)) {
+                    this._selectedIndex = null;
+                }
+                break;
+            case 'selected-indices':
+                try {
+                    this._selectedIndices = newValue ? JSON.parse(newValue) : [];
+                }
+                catch {
+                    this._selectedIndices = [];
+                }
+                break;
+            case 'required':
+                this._required = newValue !== null;
+                break;
+            case 'min-selections':
+                this._minSelections = newValue !== null ? parseInt(newValue, 10) : undefined;
+                break;
+            case 'max-selections':
+                this._maxSelections = newValue !== null ? parseInt(newValue, 10) : undefined;
+                break;
+            case 'error':
+                this._error = newValue !== null;
+                break;
+            case 'error-message':
+                this._errorMessage = newValue || undefined;
+                break;
+            case 'test-id':
+                this._testID = newValue || undefined;
+                break;
+        }
+        // Update DOM if it exists
+        if (this.isConnected && this._domCreated) {
+            this._updateDOM();
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Public Getters/Setters
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Get the selection mode.
+     */
+    get mode() {
+        return this._mode;
+    }
+    /**
+     * Set the selection mode.
+     */
+    set mode(value) {
+        this._mode = value;
+        this.setAttribute('mode', value);
+    }
+    /**
+     * Get the selected index (Select mode).
+     */
+    get selectedIndex() {
+        return this._selectedIndex;
+    }
+    /**
+     * Set the selected index (Select mode).
+     */
+    set selectedIndex(value) {
+        this._selectedIndex = value;
+        if (value !== null) {
+            this.setAttribute('selected-index', String(value));
+        }
+        else {
+            this.removeAttribute('selected-index');
+        }
+    }
+    /**
+     * Get the selected indices (MultiSelect mode).
+     */
+    get selectedIndices() {
+        return this._selectedIndices;
+    }
+    /**
+     * Set the selected indices (MultiSelect mode).
+     */
+    set selectedIndices(value) {
+        this._selectedIndices = value;
+        this.setAttribute('selected-indices', JSON.stringify(value));
+    }
+    /**
+     * Get the required flag.
+     */
+    get required() {
+        return this._required;
+    }
+    /**
+     * Set the required flag.
+     */
+    set required(value) {
+        this._required = value;
+        if (value) {
+            this.setAttribute('required', '');
+        }
+        else {
+            this.removeAttribute('required');
+        }
+    }
+    /**
+     * Get the minimum selections (MultiSelect mode).
+     */
+    get minSelections() {
+        return this._minSelections;
+    }
+    /**
+     * Set the minimum selections (MultiSelect mode).
+     */
+    set minSelections(value) {
+        this._minSelections = value;
+        if (value !== undefined) {
+            this.setAttribute('min-selections', String(value));
+        }
+        else {
+            this.removeAttribute('min-selections');
+        }
+    }
+    /**
+     * Get the maximum selections (MultiSelect mode).
+     */
+    get maxSelections() {
+        return this._maxSelections;
+    }
+    /**
+     * Set the maximum selections (MultiSelect mode).
+     */
+    set maxSelections(value) {
+        this._maxSelections = value;
+        if (value !== undefined) {
+            this.setAttribute('max-selections', String(value));
+        }
+        else {
+            this.removeAttribute('max-selections');
+        }
+    }
+    /**
+     * Get the error state.
+     */
+    get error() {
+        return this._error;
+    }
+    /**
+     * Set the error state.
+     */
+    set error(value) {
+        this._error = value;
+        if (value) {
+            this.setAttribute('error', '');
+        }
+        else {
+            this.removeAttribute('error');
+        }
+    }
+    /**
+     * Get the error message.
+     */
+    get errorMessage() {
+        return this._errorMessage;
+    }
+    /**
+     * Set the error message.
+     */
+    set errorMessage(value) {
+        this._errorMessage = value;
+        if (value) {
+            this.setAttribute('error-message', value);
+        }
+        else {
+            this.removeAttribute('error-message');
+        }
+    }
+    /**
+     * Get the test ID.
+     */
+    get testID() {
+        return this._testID;
+    }
+    /**
+     * Set the test ID.
+     */
+    set testID(value) {
+        this._testID = value;
+        if (value) {
+            this.setAttribute('test-id', value);
+        }
+        else {
+            this.removeAttribute('test-id');
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Callback Setters
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Set the onItemClick callback (Tap mode).
+     */
+    set onItemClick(callback) {
+        this._onItemClick = callback;
+    }
+    /**
+     * Get the onItemClick callback.
+     */
+    get onItemClick() {
+        return this._onItemClick;
+    }
+    /**
+     * Set the onSelectionChange callback (Select mode).
+     */
+    set onSelectionChange(callback) {
+        this._onSelectionChange = callback;
+    }
+    /**
+     * Get the onSelectionChange callback.
+     */
+    get onSelectionChange() {
+        return this._onSelectionChange;
+    }
+    /**
+     * Set the onMultiSelectionChange callback (MultiSelect mode).
+     */
+    set onMultiSelectionChange(callback) {
+        this._onMultiSelectionChange = callback;
+    }
+    /**
+     * Get the onMultiSelectionChange callback.
+     */
+    get onMultiSelectionChange() {
+        return this._onMultiSelectionChange;
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Public Methods
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Validate the current selection state.
+     *
+     * Checks if the current selection meets the validation requirements
+     * based on the mode and configured constraints (required, minSelections, maxSelections).
+     *
+     * This method can be called externally to validate the selection before
+     * form submission or other actions.
+     *
+     * @returns ValidationResult with isValid flag and optional error message
+     *
+     * @example
+     * ```typescript
+     * const set = document.querySelector('button-vertical-list-set');
+     * const result = set.validate();
+     * if (!result.isValid) {
+     *   console.log(result.message); // "Please select an option"
+     * }
+     * ```
+     *
+     * @see Requirements 7.3, 7.4, 7.5
+     */
+    validate() {
+        return (0, types_1.validateSelection)(this._mode, this._selectedIndex, this._selectedIndices, this._required, this._minSelections, this._maxSelections);
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Rendering (Incremental Update Architecture)
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Main render entry point.
+     *
+     * Routes to _createDOM() for first render or _updateDOM() for subsequent updates.
+     * This architecture enables CSS transitions by preserving DOM element identity.
+     */
+    _render() {
+        if (!this._domCreated) {
+            this._createDOM();
+            this._domCreated = true;
+            this._attachEventListeners();
+        }
+        else {
+            this._updateDOM();
+        }
+    }
+    /**
+     * Create the initial DOM structure (called once).
+     *
+     * Creates the shadow DOM structure with container and slot for children.
+     * Error message element is always present but hidden when not needed.
+     *
+     * @see Requirements 2.1, 11.2
+     */
+    _createDOM() {
+        // Get initial ARIA role based on mode
+        const role = getContainerRole(this._mode);
+        const ariaMultiSelectable = this._mode === 'multiSelect' ? 'true' : null;
+        // Create the shadow DOM structure
+        // Error message is conditionally rendered (only when errorMessage is provided)
+        // Slot receives child Button-VerticalList-Item elements
+        this._shadowRoot.innerHTML = `
+      <style>${Button_VerticalList_Set_styles_css_1.default}</style>
+      <div 
+        class="vls-container" 
+        role="${role}"
+        ${ariaMultiSelectable ? `aria-multiselectable="${ariaMultiSelectable}"` : ''}
+      >
+        <div 
+          class="vls-error-message" 
+          id="${this._errorMessageId}" 
+          role="alert"
+          style="display: none;"
+        ></div>
+        <slot></slot>
+      </div>
+    `;
+        // Cache element references for incremental updates
+        this._container = this._shadowRoot.querySelector('.vls-container');
+        this._errorMessageEl = this._shadowRoot.querySelector('.vls-error-message');
+        // Apply initial state
+        this._updateDOM();
+    }
+    /**
+     * Update existing DOM elements (called on attribute changes).
+     *
+     * Only updates properties that need to change, preserving DOM element identity.
+     * This enables CSS transitions to animate smoothly between states.
+     *
+     * @see Requirements 2.1, 11.2
+     */
+    _updateDOM() {
+        if (!this._container)
+            return;
+        // Update ARIA role based on mode
+        const role = getContainerRole(this._mode);
+        this._container.setAttribute('role', role);
+        // Update aria-multiselectable for multiSelect mode
+        if (this._mode === 'multiSelect') {
+            this._container.setAttribute('aria-multiselectable', 'true');
+        }
+        else {
+            this._container.removeAttribute('aria-multiselectable');
+        }
+        // Update error state accessibility attributes
+        if (this._error && this._errorMessage) {
+            this._container.setAttribute('aria-invalid', 'true');
+            this._container.setAttribute('aria-describedby', this._errorMessageId);
+        }
+        else {
+            this._container.removeAttribute('aria-invalid');
+            this._container.removeAttribute('aria-describedby');
+        }
+        // Update test ID
+        if (this._testID) {
+            this._container.setAttribute('data-testid', this._testID);
+        }
+        else {
+            this._container.removeAttribute('data-testid');
+        }
+        // Update error message
+        if (this._errorMessageEl) {
+            if (this._error && this._errorMessage) {
+                this._errorMessageEl.textContent = this._errorMessage;
+                this._errorMessageEl.style.display = '';
+            }
+            else {
+                this._errorMessageEl.textContent = '';
+                this._errorMessageEl.style.display = 'none';
+            }
+        }
+        // Update child items (will be implemented in Task 3)
+        // For now, just propagate error state to children
+        this._updateChildItems();
+    }
+    /**
+     * Update child Button-VerticalList-Item elements.
+     *
+     * Propagates visual state, transition delay, checkmark transition, error state,
+     * and ARIA attributes to children. Uses deriveItemStates() to calculate visual
+     * states from controlled props. Also sets up roving tabindex pattern for
+     * keyboard navigation.
+     *
+     * Communication props passed to children:
+     * - `visual-state`: Derived from controlled props (mode, selectedIndex, selectedIndices)
+     * - `transition-delay`: Animation timing coordination (calculated in Task 6)
+     * - `checkmark-transition`: Checkmark animation behavior ('fade' or 'instant')
+     * - `error`: Error state propagation to all children
+     * - `tabindex`: Roving tabindex for keyboard navigation (0 for focused, -1 for others)
+     *
+     * @see Requirements 3.1, 4.1, 4.2, 5.1, 6.5, 7.1, 8.6, 9.6
+     */
+    _updateChildItems() {
+        // Get all slotted children
+        const slot = this._shadowRoot.querySelector('slot');
+        if (!slot)
+            return;
+        const children = slot.assignedElements();
+        const itemCount = children.length;
+        // Derive visual states from controlled props
+        // This is the core state derivation logic per design document
+        const visualStates = (0, types_1.deriveItemStates)(this._mode, this._selectedIndex, this._selectedIndices, itemCount);
+        // Calculate transition delays for animation coordination
+        // @see Requirements 6.1, 6.2, 6.3, 6.4: Animation timing coordination
+        const transitionDelays = this._calculateTransitionDelays(itemCount, visualStates);
+        // Calculate checkmark transitions for animation coordination
+        // @see Requirement 6.5: "checkmarkTransition='instant' on deselecting items in Select mode"
+        const checkmarkTransitions = this._calculateCheckmarkTransitions(itemCount, visualStates);
+        // Determine ARIA role for items based on mode
+        // @see Requirements 3.4, 4.7, 5.5
+        const itemRole = this._getItemRole();
+        // Ensure focused index is within bounds
+        // @see Requirement 8.6: Roving tabindex pattern
+        if (this._internalState.focusedIndex >= itemCount) {
+            this._internalState.focusedIndex = Math.max(0, itemCount - 1);
+        }
+        // Update each child with derived state
+        children.forEach((child, index) => {
+            if (child.tagName.toLowerCase() === 'button-vertical-list-item') {
+                // Set visual state derived from controlled props
+                // @see Requirements 9.6: "derive child visual states from controlled props"
+                const visualState = visualStates[index];
+                child.setAttribute('visual-state', visualState);
+                // Set transition delay for animation coordination
+                // @see Requirements 6.1, 6.2, 6.3, 6.4: Animation timing coordination
+                const transitionDelay = transitionDelays[index];
+                child.setAttribute('transition-delay', String(transitionDelay));
+                // Set checkmark transition for animation coordination
+                // @see Requirement 6.5: "checkmarkTransition='instant' on deselecting items in Select mode"
+                // Note: Map 'animated' to 'fade' for Item component compatibility
+                const checkmarkTransition = checkmarkTransitions[index];
+                child.setAttribute('checkmark-transition', checkmarkTransition === 'instant' ? 'instant' : 'fade');
+                // Propagate error state to all children
+                // @see Requirements 7.1: "pass error={true} to all child items"
+                if (this._error) {
+                    child.setAttribute('error', 'true');
+                }
+                else {
+                    child.setAttribute('error', 'false');
+                }
+                // Set ARIA role for the item based on mode
+                // @see Requirements 3.4, 4.7, 5.5
+                child.setAttribute('role', itemRole);
+                // Set aria-checked for radio and checkbox roles
+                // @see Requirements 4.7, 5.5
+                if (itemRole === 'radio' || itemRole === 'checkbox') {
+                    const isChecked = this._getItemAriaChecked(index, visualState);
+                    child.setAttribute('aria-checked', isChecked ? 'true' : 'false');
+                }
+                else {
+                    // Button role doesn't use aria-checked
+                    child.removeAttribute('aria-checked');
+                }
+                // Set tabindex for roving tabindex pattern
+                // @see Requirement 8.6: "focused item has tabindex=0, others have tabindex=-1"
+                if (index === this._internalState.focusedIndex) {
+                    child.setAttribute('tabindex', '0');
+                }
+                else {
+                    child.setAttribute('tabindex', '-1');
+                }
+            }
+        });
+    }
+    /**
+     * Get the ARIA role for child items based on mode.
+     *
+     * Role mapping:
+     * - Tap mode: 'button' (simple action buttons)
+     * - Select mode: 'radio' (single-selection radio-button style)
+     * - MultiSelect mode: 'checkbox' (multiple-selection checkbox style)
+     *
+     * @returns The ARIA role for child items
+     * @see Requirements 3.4, 4.7, 5.5
+     */
+    _getItemRole() {
+        switch (this._mode) {
+            case 'tap':
+                return 'button';
+            case 'select':
+                return 'radio';
+            case 'multiSelect':
+                return 'checkbox';
+            default:
+                return 'button';
+        }
+    }
+    /**
+     * Determine if an item should have aria-checked="true".
+     *
+     * For Select mode (radio): Item is checked if it's the selected item
+     * For MultiSelect mode (checkbox): Item is checked if it's in the selectedIndices array
+     *
+     * @param index - The index of the item
+     * @param visualState - The visual state of the item
+     * @returns true if the item should be aria-checked="true"
+     * @see Requirements 4.7, 5.5
+     */
+    _getItemAriaChecked(index, visualState) {
+        switch (this._mode) {
+            case 'select':
+                // In Select mode, item is checked if it's the selected item
+                // Visual states 'selected' indicates the item is checked
+                return visualState === 'selected';
+            case 'multiSelect':
+                // In MultiSelect mode, item is checked if it's in the selectedIndices array
+                // Visual state 'checked' indicates the item is checked
+                return visualState === 'checked';
+            default:
+                // Tap mode doesn't use aria-checked
+                return false;
+        }
+    }
+    /**
+     * Calculate transition delays for animation coordination.
+     *
+     * This method coordinates animation timing across child items based on
+     * the current mode and selection state. It uses the animation timing
+     * functions from types.ts to determine appropriate delays.
+     *
+     * Animation timing rules:
+     * - **Select mode - Selection change**: Deselecting item gets 0ms, selecting item gets 125ms (staggered handoff)
+     * - **Select mode - First selection**: All items get 0ms (simultaneous)
+     * - **Select mode - Deselection**: All items get 0ms (simultaneous)
+     * - **MultiSelect mode - Toggle**: Toggled item gets 0ms (independent)
+     * - **Tap mode**: All items get 0ms (no selection state)
+     *
+     * @param itemCount - Number of child items
+     * @param visualStates - Array of visual states for each item
+     * @returns Array of transition delays in milliseconds
+     * @see Requirements 6.1, 6.2, 6.3, 6.4
+     */
+    _calculateTransitionDelays(itemCount, visualStates) {
+        // Tap mode: No animation coordination needed
+        if (this._mode === 'tap') {
+            return Array(itemCount).fill(0);
+        }
+        // MultiSelect mode: Independent animation per item
+        // Each item animates immediately when toggled
+        // @see Requirement 6.4: "WHEN items toggle in MultiSelect mode THEN toggled item gets 0ms"
+        if (this._mode === 'multiSelect') {
+            // In multiSelect mode, we don't track previous state for staggering
+            // Each toggle is independent, so all items get 0ms delay
+            return (0, types_1.calculateMultiSelectDelay)(0, itemCount);
+        }
+        // Select mode: Coordinate animation timing based on selection state
+        // @see Requirements 6.1, 6.2, 6.3
+        if (this._mode === 'select') {
+            const previousIndex = this._internalState.previousSelectedIndex;
+            const currentIndex = this._selectedIndex;
+            const isFirstSelection = this._internalState.isFirstSelection;
+            // Case 1: First selection (no previous selection)
+            // All items animate simultaneously
+            // @see Requirement 6.2: "WHEN first selection is made THEN all items get 0ms"
+            if (isFirstSelection && currentIndex !== null) {
+                return (0, types_1.calculateFirstSelectionDelays)(itemCount);
+            }
+            // Case 2: Deselection (clearing selection)
+            // All items animate simultaneously back to rest
+            // @see Requirement 6.3: "WHEN deselection occurs THEN all items get 0ms"
+            if (currentIndex === null && previousIndex !== null) {
+                return (0, types_1.calculateDeselectionDelays)(itemCount);
+            }
+            // Case 3: Selection change (from one item to another)
+            // Staggered animation: deselecting item starts first, selecting item follows
+            // @see Requirement 6.1: "WHEN selection changes THEN deselecting gets 0ms, selecting gets 125ms"
+            if (previousIndex !== null && currentIndex !== null && previousIndex !== currentIndex) {
+                return (0, types_1.calculateStaggeredDelays)(previousIndex, currentIndex, itemCount);
+            }
+            // Default: No animation coordination needed
+            return Array(itemCount).fill(0);
+        }
+        // Fallback: No animation coordination
+        return Array(itemCount).fill(0);
+    }
+    /**
+     * Calculate checkmark transitions for animation coordination.
+     *
+     * This method determines the checkmark transition behavior for each child item
+     * based on the current mode and selection state. In Select mode, deselecting
+     * items get 'instant' checkmark removal while selecting items get 'animated'.
+     *
+     * Checkmark transition rules:
+     * - **Select mode - Deselecting item**: 'instant' (checkmark hides immediately)
+     * - **Select mode - Selecting item**: 'animated' (checkmark fades in)
+     * - **Select mode - Other items**: 'animated' (default)
+     * - **MultiSelect mode**: 'animated' (all items animate normally)
+     * - **Tap mode**: 'animated' (no checkmarks, but default to animated)
+     *
+     * @param itemCount - Number of child items
+     * @param visualStates - Array of visual states for each item
+     * @returns Array of checkmark transition values ('animated' | 'instant')
+     * @see Requirement 6.5: "checkmarkTransition='instant' on deselecting items in Select mode"
+     */
+    _calculateCheckmarkTransitions(itemCount, visualStates) {
+        // Tap mode: No checkmarks, default to animated
+        if (this._mode === 'tap') {
+            return Array(itemCount).fill('animated');
+        }
+        // MultiSelect mode: All items animate normally
+        // @see Requirement 6.5: Only Select mode uses instant checkmark removal
+        if (this._mode === 'multiSelect') {
+            return Array(itemCount).fill('animated');
+        }
+        // Select mode: Determine which item is deselecting
+        // @see Requirement 6.5: "checkmarkTransition='instant' on deselecting items in Select mode"
+        if (this._mode === 'select') {
+            const previousIndex = this._internalState.previousSelectedIndex;
+            const currentIndex = this._selectedIndex;
+            // Create array with default 'animated' transitions
+            const transitions = Array(itemCount).fill('animated');
+            // Case: Selection change (from one item to another)
+            // The deselecting item (previousIndex) gets 'instant' checkmark removal
+            if (previousIndex !== null && currentIndex !== null && previousIndex !== currentIndex) {
+                // Use getCheckmarkTransition to determine the transition for the deselecting item
+                transitions[previousIndex] = (0, types_1.getCheckmarkTransition)(true, this._mode);
+                // Selecting item gets animated transition
+                transitions[currentIndex] = (0, types_1.getCheckmarkTransition)(false, this._mode);
+            }
+            // Case: Deselection (clearing selection by clicking selected item)
+            // The deselecting item gets 'instant' checkmark removal
+            if (currentIndex === null && previousIndex !== null) {
+                transitions[previousIndex] = (0, types_1.getCheckmarkTransition)(true, this._mode);
+            }
+            return transitions;
+        }
+        // Fallback: All items animate normally
+        return Array(itemCount).fill('animated');
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Event Handling
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Attach event listeners.
+     *
+     * Sets up listeners for child item clicks and keyboard navigation.
+     *
+     * @see Requirements 8.1, 8.2, 8.3, 8.4, 8.5, 8.6
+     */
+    _attachEventListeners() {
+        // Listen for slot changes to update child items
+        const slot = this._shadowRoot.querySelector('slot');
+        if (slot) {
+            slot.addEventListener('slotchange', this._handleSlotChange);
+        }
+        // Listen for click events from children (bubbles through slot)
+        this.addEventListener('click', this._handleChildClick);
+        // Listen for keyboard events for navigation
+        // @see Requirements 8.1, 8.2, 8.3, 8.4, 8.5
+        this.addEventListener('keydown', this._handleKeyDown);
+        // Listen for focus events to track which item has focus
+        // @see Requirement 8.6: Roving tabindex pattern
+        this.addEventListener('focusin', this._handleFocusIn);
+    }
+    /**
+     * Detach event listeners.
+     */
+    _detachEventListeners() {
+        const slot = this._shadowRoot.querySelector('slot');
+        if (slot) {
+            slot.removeEventListener('slotchange', this._handleSlotChange);
+        }
+        this.removeEventListener('click', this._handleChildClick);
+        this.removeEventListener('keydown', this._handleKeyDown);
+        this.removeEventListener('focusin', this._handleFocusIn);
+    }
+    /**
+     * Handle click in Select mode.
+     *
+     * Implements single-selection behavior:
+     * - Clicking an unselected item selects it (and deselects any previous selection)
+     * - Clicking the currently selected item deselects it (returns to null)
+     *
+     * This is a controlled component, so we invoke the callback and let the parent
+     * update the selectedIndex prop. The visual state update happens when the
+     * attribute changes.
+     *
+     * Also handles:
+     * - Error clearing: when a valid selection is made and required is true
+     * - Selection history tracking: updates previousSelectedIndex and isFirstSelection
+     *   for animation coordination
+     *
+     * @param clickedIndex - The index of the clicked item
+     * @see Requirements 4.2, 4.3, 4.4, 4.5, 6.1, 6.2, 6.3, 7.3, 9.3
+     */
+    _handleSelectModeClick(clickedIndex) {
+        // Determine the new selection state
+        let newSelectedIndex;
+        if (this._selectedIndex === clickedIndex) {
+            // Clicking the currently selected item deselects it
+            // @see Requirement 4.3: "clicking selected item SHALL reset all items to rest state"
+            newSelectedIndex = null;
+        }
+        else {
+            // Clicking a different item selects it
+            // @see Requirement 4.2, 4.4: "selecting an item SHALL set that item to selected state"
+            newSelectedIndex = clickedIndex;
+        }
+        // ─────────────────────────────────────────────────────────────────
+        // Selection History Tracking for Animation Coordination
+        // @see Requirements 6.1, 6.2, 6.3
+        // ─────────────────────────────────────────────────────────────────
+        // Track previous selection for stagger calculation
+        // @see Requirement 6.1: "WHEN selection changes between items THEN 
+        // deselecting item gets 0ms, selecting item gets 125ms"
+        this._internalState.previousSelectedIndex = this._selectedIndex;
+        // Handle deselection: reset isFirstSelection flag
+        // @see Requirement 6.3: "WHEN deselection occurs THEN all items get 0ms"
+        if (newSelectedIndex === null) {
+            // Deselection resets the first selection flag
+            // Next selection will be treated as "first selection" again
+            this._internalState.isFirstSelection = true;
+        }
+        else if (this._internalState.isFirstSelection) {
+            // First selection made - clear the flag for future selections
+            // @see Requirement 6.2: "WHEN first selection is made THEN all items get 0ms"
+            // After this selection, subsequent selections will use staggered animation
+            this._internalState.isFirstSelection = false;
+        }
+        // Clear error on valid selection
+        // @see Requirement 7.3: "WHEN a valid selection is made AND required is true THEN clear error"
+        if (this._error && this._required && newSelectedIndex !== null) {
+            // Validate the new selection
+            const validation = (0, types_1.validateSelection)(this._mode, newSelectedIndex, this._selectedIndices, this._required, this._minSelections, this._maxSelections);
+            if (validation.isValid) {
+                // Clear error state
+                this._error = false;
+                this._errorMessage = undefined;
+                this.removeAttribute('error');
+                this.removeAttribute('error-message');
+                // Update DOM to reflect cleared error
+                if (this._domCreated) {
+                    this._updateDOM();
+                }
+            }
+        }
+        // Invoke the callback with the new selection
+        // @see Requirement 4.5, 9.3: "SHALL invoke onSelectionChange callback"
+        if (this._onSelectionChange) {
+            this._onSelectionChange(newSelectedIndex);
+        }
+    }
+    /**
+     * Handle click in MultiSelect mode.
+     *
+     * Implements multiple-selection behavior (checkbox style):
+     * - Clicking an unchecked item adds it to the selection (toggles to checked)
+     * - Clicking a checked item removes it from the selection (toggles to unchecked)
+     *
+     * This is a controlled component, so we invoke the callback and let the parent
+     * update the selectedIndices prop. The visual state update happens when the
+     * attribute changes.
+     *
+     * Also handles:
+     * - Max selection enforcement: prevents selecting beyond maxSelections
+     * - Error clearing: clears error when selection becomes valid
+     *
+     * @param clickedIndex - The index of the clicked item
+     * @see Requirements 5.2, 5.3, 7.4, 7.5, 9.4
+     */
+    _handleMultiSelectModeClick(clickedIndex) {
+        // Check if the item can be selected (respects maxSelections)
+        // @see Requirement 7.5: "WHEN maxSelections is set THEN prevent selecting more"
+        if (!(0, types_1.canSelectItem)(clickedIndex, this._selectedIndices, this._maxSelections)) {
+            // At max selections and trying to select a new item - do nothing
+            return;
+        }
+        // Create a new array to avoid mutating the existing one
+        let newSelectedIndices;
+        if (this._selectedIndices.includes(clickedIndex)) {
+            // Item is currently checked - remove it from selection (toggle to unchecked)
+            // @see Requirement 5.2: "toggling an item SHALL toggle between checked and unchecked"
+            newSelectedIndices = this._selectedIndices.filter(i => i !== clickedIndex);
+        }
+        else {
+            // Item is currently unchecked - add it to selection (toggle to checked)
+            // @see Requirement 5.2: "toggling an item SHALL toggle between checked and unchecked"
+            newSelectedIndices = [...this._selectedIndices, clickedIndex];
+        }
+        // Clear error on valid selection
+        // @see Requirement 7.4: "WHEN minSelections is set THEN validate at least that many"
+        if (this._error) {
+            // Validate the new selection
+            const validation = (0, types_1.validateSelection)(this._mode, this._selectedIndex, newSelectedIndices, this._required, this._minSelections, this._maxSelections);
+            if (validation.isValid) {
+                // Clear error state
+                this._error = false;
+                this._errorMessage = undefined;
+                this.removeAttribute('error');
+                this.removeAttribute('error-message');
+                // Update DOM to reflect cleared error
+                if (this._domCreated) {
+                    this._updateDOM();
+                }
+            }
+        }
+        // Invoke the callback with the complete array of selected indices
+        // @see Requirement 5.3, 9.4: "SHALL invoke onMultiSelectionChange callback with array of selected indices"
+        if (this._onMultiSelectionChange) {
+            this._onMultiSelectionChange(newSelectedIndices);
+        }
+    }
+    /**
+     * Process keyboard navigation and determine the action to take.
+     *
+     * Implements the key handler logic from the design document:
+     * - Arrow Down: Move focus to next item (wrap to first)
+     * - Arrow Up: Move focus to previous item (wrap to last)
+     * - Home: Move focus to first item
+     * - End: Move focus to last item
+     * - Enter/Space: Activate the focused item
+     *
+     * @param event - The keyboard event
+     * @param itemCount - Number of child items
+     * @returns Object with newFocusIndex, shouldActivate, and handled flags
+     * @see Requirements 8.2, 8.3, 8.4, 8.5
+     */
+    _processKeyboardNavigation(event, itemCount) {
+        const currentIndex = this._internalState.focusedIndex;
+        switch (event.key) {
+            case 'ArrowDown':
+                // Move focus to next item, wrap to first if at end
+                // @see Requirement 8.2: "Arrow Down SHALL move focus between items"
+                return {
+                    newFocusIndex: (currentIndex + 1) % itemCount,
+                    shouldActivate: false,
+                    handled: true
+                };
+            case 'ArrowUp':
+                // Move focus to previous item, wrap to last if at beginning
+                // @see Requirement 8.2: "Arrow Up SHALL move focus between items"
+                return {
+                    newFocusIndex: (currentIndex - 1 + itemCount) % itemCount,
+                    shouldActivate: false,
+                    handled: true
+                };
+            case 'Home':
+                // Move focus to first item
+                // @see Requirement 8.4: "Home SHALL move focus to first item"
+                return {
+                    newFocusIndex: 0,
+                    shouldActivate: false,
+                    handled: true
+                };
+            case 'End':
+                // Move focus to last item
+                // @see Requirement 8.5: "End SHALL move focus to last item"
+                return {
+                    newFocusIndex: itemCount - 1,
+                    shouldActivate: false,
+                    handled: true
+                };
+            case 'Enter':
+            case ' ':
+                // Activate the focused item
+                // @see Requirement 8.3: "Enter/Space SHALL activate or toggle item based on mode"
+                return {
+                    newFocusIndex: currentIndex,
+                    shouldActivate: true,
+                    handled: true
+                };
+            default:
+                // Key not handled
+                return {
+                    newFocusIndex: currentIndex,
+                    shouldActivate: false,
+                    handled: false
+                };
+        }
+    }
+    /**
+     * Move focus to a specific item index.
+     *
+     * Updates the internal focused index, updates tabindex values using
+     * roving tabindex pattern, and moves DOM focus to the new item.
+     *
+     * @param newIndex - The index to focus
+     * @param children - Array of child elements (optional, will be fetched if not provided)
+     * @see Requirement 8.6: Roving tabindex pattern
+     */
+    _moveFocusToIndex(newIndex, children) {
+        const items = children || this._getChildItems();
+        if (items.length === 0 || newIndex < 0 || newIndex >= items.length)
+            return;
+        // Update internal state
+        this._internalState.focusedIndex = newIndex;
+        // Update tabindex values (roving tabindex pattern)
+        // @see Requirement 8.6: "focused item has tabindex=0, others have tabindex=-1"
+        this._updateTabIndices(items, newIndex);
+        // Move DOM focus to the new item
+        const targetItem = items[newIndex];
+        if (targetItem) {
+            targetItem.focus();
+        }
+    }
+    /**
+     * Update tabindex values for roving tabindex pattern.
+     *
+     * Sets tabindex="0" on the focused item and tabindex="-1" on all others.
+     * This ensures only one item is in the tab order at a time.
+     *
+     * @param items - Array of child elements
+     * @param focusedIndex - Index of the item that should have tabindex="0"
+     * @see Requirement 8.6: Roving tabindex pattern
+     */
+    _updateTabIndices(items, focusedIndex) {
+        items.forEach((item, index) => {
+            if (index === focusedIndex) {
+                item.setAttribute('tabindex', '0');
+            }
+            else {
+                item.setAttribute('tabindex', '-1');
+            }
+        });
+    }
+    /**
+     * Activate an item at the specified index.
+     *
+     * Simulates a click on the item, which triggers the appropriate
+     * mode-specific behavior (tap callback, selection change, or toggle).
+     *
+     * @param index - The index of the item to activate
+     * @see Requirement 8.3: "Enter/Space SHALL activate or toggle item based on mode"
+     */
+    _activateItem(index) {
+        // Handle activation based on mode (same as click handling)
+        switch (this._mode) {
+            case 'tap':
+                // Tap mode: Invoke callback with index
+                if (this._onItemClick) {
+                    this._onItemClick(index);
+                }
+                break;
+            case 'select':
+                // Select mode: Toggle selection
+                this._handleSelectModeClick(index);
+                break;
+            case 'multiSelect':
+                // MultiSelect mode: Toggle item
+                this._handleMultiSelectModeClick(index);
+                break;
+        }
+    }
+    /**
+     * Get all child Button-VerticalList-Item elements.
+     *
+     * @returns Array of child elements
+     */
+    _getChildItems() {
+        const slot = this._shadowRoot.querySelector('slot');
+        if (!slot)
+            return [];
+        return slot.assignedElements().filter(el => el.tagName.toLowerCase() === 'button-vertical-list-item');
+    }
+}
+exports.ButtonVerticalListSet = ButtonVerticalListSet;
+// Register custom element
+// Uses conditional check for idempotent registration
+if (typeof customElements !== 'undefined' && !customElements.get('button-vertical-list-set')) {
+    customElements.define('button-vertical-list-set', ButtonVerticalListSet);
+}
+/**
+ * Default export for convenience.
+ */
+exports.default = ButtonVerticalListSet;
+//# sourceMappingURL=ButtonVerticalListSet.web.js.map