@3fn/core 14.0.0 → 15.0.0

package/src/components/core/Button-VerticalList-Set/platforms/web/ButtonVerticalListSet.web.ts

@@ -1,1446 +0,0 @@
-/**
- * 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
- */
-
-/// <reference lib="dom" />
-
-import type { 
-  SelectionMode, 
-  SetInternalState
-} from '../../types';
-
-import { 
-  deriveItemStates, 
-  validateSelection, 
-  canSelectItem,
-  calculateStaggeredDelays,
-  calculateFirstSelectionDelays,
-  calculateDeselectionDelays,
-  calculateMultiSelectDelay,
-  getCheckmarkTransition
-} from '../../types';
-
-// Import CSS as string for browser bundle compatibility
-// The esbuild CSS-as-string plugin transforms this import into a JS string export
-import componentStyles from './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: SelectionMode): string {
-  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
- */
-export class ButtonVerticalListSet extends HTMLElement {
-  // ─────────────────────────────────────────────────────────────────
-  // Static Properties
-  // ─────────────────────────────────────────────────────────────────
-  
-  /**
-   * Observed attributes for attribute change callbacks.
-   * 
-   * When these attributes change, attributeChangedCallback is invoked.
-   */
-  static get observedAttributes(): string[] {
-    return [
-      'mode',
-      'selected-index',
-      'selected-indices',
-      'required',
-      'min-selections',
-      'max-selections',
-      'error',
-      'error-message',
-      'test-id'
-    ];
-  }
-  
-  // ─────────────────────────────────────────────────────────────────
-  // Private Properties
-  // ─────────────────────────────────────────────────────────────────
-  
-  /** Shadow root reference */
-  private _shadowRoot: ShadowRoot;
-  
-  /** Whether DOM has been created */
-  private _domCreated: boolean = false;
-  
-  // Cached DOM element references for incremental updates
-  private _container: HTMLDivElement | null = null;
-  private _errorMessageEl: HTMLDivElement | null = null;
-  
-  // Props (backed by attributes)
-  private _mode: SelectionMode = 'tap';
-  private _selectedIndex: number | null = null;
-  private _selectedIndices: number[] = [];
-  private _required: boolean = false;
-  private _minSelections?: number;
-  private _maxSelections?: number;
-  private _error: boolean = false;
-  private _errorMessage?: string;
-  private _testID?: string;
-  
-  // Internal state for focus management and animation tracking
-  private _internalState: SetInternalState = {
-    focusedIndex: 0,
-    previousSelectedIndex: null,
-    isFirstSelection: true
-  };
-  
-  // Callbacks (set via properties, not attributes)
-  private _onItemClick?: (index: number) => void;
-  private _onSelectionChange?: (index: number | null) => void;
-  private _onMultiSelectionChange?: (indices: number[]) => void;
-  
-  // Unique ID for error message element (for aria-describedby)
-  private _errorMessageId: string;
-  
-  // ─────────────────────────────────────────────────────────────────
-  // Constructor
-  // ─────────────────────────────────────────────────────────────────
-  
-  constructor() {
-    super();
-    
-    // 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(): void {
-    // 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(): void {
-    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: string, oldValue: string | null, newValue: string | null): void {
-    // 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 as SelectionMode) || 'tap';
-        break;
-      case 'selected-index':
-        this._selectedIndex = newValue !== null ? parseInt(newValue, 10) : null;
-        if (isNaN(this._selectedIndex as number)) {
-          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(): SelectionMode {
-    return this._mode;
-  }
-  
-  /**
-   * Set the selection mode.
-   */
-  set mode(value: SelectionMode) {
-    this._mode = value;
-    this.setAttribute('mode', value);
-  }
-  
-  /**
-   * Get the selected index (Select mode).
-   */
-  get selectedIndex(): number | null {
-    return this._selectedIndex;
-  }
-  
-  /**
-   * Set the selected index (Select mode).
-   */
-  set selectedIndex(value: number | null) {
-    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(): number[] {
-    return this._selectedIndices;
-  }
-  
-  /**
-   * Set the selected indices (MultiSelect mode).
-   */
-  set selectedIndices(value: number[]) {
-    this._selectedIndices = value;
-    this.setAttribute('selected-indices', JSON.stringify(value));
-  }
-  
-  /**
-   * Get the required flag.
-   */
-  get required(): boolean {
-    return this._required;
-  }
-  
-  /**
-   * Set the required flag.
-   */
-  set required(value: boolean) {
-    this._required = value;
-    if (value) {
-      this.setAttribute('required', '');
-    } else {
-      this.removeAttribute('required');
-    }
-  }
-  
-  /**
-   * Get the minimum selections (MultiSelect mode).
-   */
-  get minSelections(): number | undefined {
-    return this._minSelections;
-  }
-  
-  /**
-   * Set the minimum selections (MultiSelect mode).
-   */
-  set minSelections(value: number | undefined) {
-    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(): number | undefined {
-    return this._maxSelections;
-  }
-  
-  /**
-   * Set the maximum selections (MultiSelect mode).
-   */
-  set maxSelections(value: number | undefined) {
-    this._maxSelections = value;
-    if (value !== undefined) {
-      this.setAttribute('max-selections', String(value));
-    } else {
-      this.removeAttribute('max-selections');
-    }
-  }
-  
-  /**
-   * Get the error state.
-   */
-  get error(): boolean {
-    return this._error;
-  }
-  
-  /**
-   * Set the error state.
-   */
-  set error(value: boolean) {
-    this._error = value;
-    if (value) {
-      this.setAttribute('error', '');
-    } else {
-      this.removeAttribute('error');
-    }
-  }
-  
-  /**
-   * Get the error message.
-   */
-  get errorMessage(): string | undefined {
-    return this._errorMessage;
-  }
-  
-  /**
-   * Set the error message.
-   */
-  set errorMessage(value: string | undefined) {
-    this._errorMessage = value;
-    if (value) {
-      this.setAttribute('error-message', value);
-    } else {
-      this.removeAttribute('error-message');
-    }
-  }
-  
-  /**
-   * Get the test ID.
-   */
-  get testID(): string | undefined {
-    return this._testID;
-  }
-  
-  /**
-   * Set the test ID.
-   */
-  set testID(value: string | undefined) {
-    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: ((index: number) => void) | undefined) {
-    this._onItemClick = callback;
-  }
-  
-  /**
-   * Get the onItemClick callback.
-   */
-  get onItemClick(): ((index: number) => void) | undefined {
-    return this._onItemClick;
-  }
-  
-  /**
-   * Set the onSelectionChange callback (Select mode).
-   */
-  set onSelectionChange(callback: ((index: number | null) => void) | undefined) {
-    this._onSelectionChange = callback;
-  }
-  
-  /**
-   * Get the onSelectionChange callback.
-   */
-  get onSelectionChange(): ((index: number | null) => void) | undefined {
-    return this._onSelectionChange;
-  }
-  
-  /**
-   * Set the onMultiSelectionChange callback (MultiSelect mode).
-   */
-  set onMultiSelectionChange(callback: ((indices: number[]) => void) | undefined) {
-    this._onMultiSelectionChange = callback;
-  }
-  
-  /**
-   * Get the onMultiSelectionChange callback.
-   */
-  get onMultiSelectionChange(): ((indices: number[]) => void) | undefined {
-    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(): { isValid: boolean; message: string | null } {
-    return 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.
-   */
-  private _render(): void {
-    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
-   */
-  private _createDOM(): void {
-    // 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>${componentStyles}</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
-   */
-  private _updateDOM(): void {
-    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
-   */
-  private _updateChildItems(): void {
-    // Get all slotted children
-    const slot = this._shadowRoot.querySelector('slot');
-    if (!slot) return;
-    
-    const children = slot.assignedElements() as HTMLElement[];
-    const itemCount = children.length;
-    
-    // Derive visual states from controlled props
-    // This is the core state derivation logic per design document
-    const visualStates = 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
-   */
-  private _getItemRole(): 'button' | 'radio' | 'checkbox' {
-    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
-   */
-  private _getItemAriaChecked(index: number, visualState: string): boolean {
-    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
-   */
-  private _calculateTransitionDelays(itemCount: number, visualStates: string[]): number[] {
-    // 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 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 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 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 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"
-   */
-  private _calculateCheckmarkTransitions(itemCount: number, visualStates: string[]): ('animated' | 'instant')[] {
-    // 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: ('animated' | 'instant')[] = 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] = getCheckmarkTransition(true, this._mode);
-        // Selecting item gets animated transition
-        transitions[currentIndex] = 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] = 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
-   */
-  private _attachEventListeners(): void {
-    // 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.
-   */
-  private _detachEventListeners(): void {
-    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 slot change events.
-   * 
-   * Called when children are added or removed from the slot.
-   */
-  private _handleSlotChange = (): void => {
-    // 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
-   */
-  private _handleChildClick = (event: Event): void => {
-    // Find the clicked child item
-    const target = event.target as HTMLElement;
-    
-    // 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;
-    }
-  };
-  
-  /**
-   * 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
-   */
-  private _handleSelectModeClick(clickedIndex: number): void {
-    // Determine the new selection state
-    let newSelectedIndex: number | null;
-    
-    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 = 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
-   */
-  private _handleMultiSelectModeClick(clickedIndex: number): void {
-    // Check if the item can be selected (respects maxSelections)
-    // @see Requirement 7.5: "WHEN maxSelections is set THEN prevent selecting more"
-    if (!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: number[];
-    
-    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 = 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);
-    }
-  }
-  
-  // ─────────────────────────────────────────────────────────────────
-  // 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
-   */
-  private _handleKeyDown = (event: KeyboardEvent): void => {
-    // 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);
-    }
-  };
-  
-  /**
-   * 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
-   */
-  private _processKeyboardNavigation(
-    event: KeyboardEvent,
-    itemCount: number
-  ): { newFocusIndex: number; shouldActivate: boolean; handled: boolean } {
-    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
-   */
-  private _moveFocusToIndex(newIndex: number, children?: HTMLElement[]): void {
-    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
-   */
-  private _updateTabIndices(items: HTMLElement[], focusedIndex: number): void {
-    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"
-   */
-  private _activateItem(index: number): void {
-    // 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;
-    }
-  }
-  
-  /**
-   * 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
-   */
-  private _handleFocusIn = (event: FocusEvent): void => {
-    const target = event.target as HTMLElement;
-    
-    // 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 as HTMLElement);
-    
-    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);
-    }
-  };
-  
-  /**
-   * Get all child Button-VerticalList-Item elements.
-   * 
-   * @returns Array of child elements
-   */
-  private _getChildItems(): HTMLElement[] {
-    const slot = this._shadowRoot.querySelector('slot');
-    if (!slot) return [];
-    
-    return slot.assignedElements().filter(
-      el => el.tagName.toLowerCase() === 'button-vertical-list-item'
-    ) as HTMLElement[];
-  }
-}
-
-// 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.
- */
-export default ButtonVerticalListSet;