@3fn/core 14.0.0 → 15.0.0

package/src/components/core/Button-VerticalList-Set/README.md

@@ -1,578 +0,0 @@
-# Button-VerticalList-Set Component
-
-**Stemma System**: Buttons Family  
-**Component Type**: Pattern (VerticalList-Set)  
-**Readiness**: 🟢 Production Ready  
-**Version**: 1.0.0
-
----
-
-## Overview
-
-The Button-VerticalList-Set component is a container/orchestrator pattern for presenting actionable choices in a stacked vertical layout. It manages selection behavior, state coordination between child items, animations, keyboard navigation, and accessibility semantics across three interaction modes: Tap, Select, and Multi-Select.
-
-**Stemma System Naming**: This component follows the `[Family]-[Type]` naming convention:
-- **Family**: Button
-- **Type**: VerticalList-Set (vertical list selection container)
-
-**Key Design Decision**: This is a controlled component — the parent manages selection state via props, and the Set coordinates visual states across all child items. This enables complex selection patterns like max selections, dependencies, and coordinated animations.
-
----
-
-## Key Features
-
-- ✅ Three interaction modes (Tap, Select, MultiSelect)
-- ✅ Controlled component API (parent manages state)
-- ✅ Coordinated animation timing across children (staggered handoff)
-- ✅ Keyboard navigation with roving tabindex
-- ✅ Error state management with validation
-- ✅ Min/max selection constraints (MultiSelect mode)
-- ✅ WCAG 2.1 AA accessibility compliance
-- ✅ Token-based styling (zero hard-coded values)
-- ✅ True Native Architecture (separate implementations per platform)
-- ❌ No disabled state (by design—see Design Decisions)
-
----
-
-## Behavioral Contracts
-
-This component guarantees the following behaviors across all platforms:
-
-| Contract | Description | Platforms | WCAG |
-|----------|-------------|-----------|------|
-| `mode_driven` | Behavior determined by mode prop (tap/select/multiSelect) | web, ios, android | - |
-| `controlled_state` | Selection state managed by parent via props | web, ios, android | - |
-| `state_coordination` | Derives and propagates visual states to children | web, ios, android | - |
-| `animation_coordination` | Coordinates transition timing across children | web, ios, android | 2.3.3 |
-| `keyboard_navigation` | Arrow keys, Home, End, Enter, Space support | web, ios, android | 2.1.1 |
-| `roving_tabindex` | Single tab stop with arrow key navigation | web | 2.4.3 |
-| `error_propagation` | Error state propagates to all children | web, ios, android | 3.3.1 |
-| `validation` | Validates selection against constraints | web, ios, android | 3.3.1 |
-| `aria_roles` | Appropriate ARIA roles based on mode | web, ios, android | 4.1.2 |
-
----
-
-## Usage
-
-### HTML Custom Element
-
-```html
-<!-- Tap mode - simple 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-item label="About"></button-vertical-list-item>
-</button-vertical-list-set>
-
-<!-- Select mode - single selection (radio-button style) -->
-<button-vertical-list-set 
-  mode="select" 
-  selected-index="0"
-  required
->
-  <button-vertical-list-item label="Option A" description="First option"></button-vertical-list-item>
-  <button-vertical-list-item label="Option B" description="Second option"></button-vertical-list-item>
-  <button-vertical-list-item label="Option C" description="Third option"></button-vertical-list-item>
-</button-vertical-list-set>
-
-<!-- MultiSelect mode - multiple selections (checkbox style) -->
-<button-vertical-list-set 
-  mode="multiSelect"
-  selected-indices="[0,2]"
-  min-selections="1"
-  max-selections="3"
->
-  <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-item label="Choice 4"></button-vertical-list-item>
-</button-vertical-list-set>
-
-<!-- With error state -->
-<button-vertical-list-set 
-  mode="select"
-  required
-  error
-  error-message="Please select an option"
->
-  <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>
-```
-
-### JavaScript/TypeScript
-
-```typescript
-import { ButtonVerticalListSet } from '@3fn/core/components';
-
-// Programmatic usage - Tap mode
-const tapSet = document.createElement('button-vertical-list-set') as ButtonVerticalListSet;
-tapSet.mode = 'tap';
-tapSet.onItemClick = (index) => {
-  console.log(`Item ${index} clicked`);
-  handleAction(index);
-};
-document.body.appendChild(tapSet);
-
-// Programmatic usage - Select mode (controlled)
-const selectSet = document.createElement('button-vertical-list-set') as ButtonVerticalListSet;
-selectSet.mode = 'select';
-selectSet.selectedIndex = 0;
-selectSet.required = true;
-selectSet.onSelectionChange = (index) => {
-  console.log(`Selection changed to ${index}`);
-  selectSet.selectedIndex = index; // Update controlled state
-};
-document.body.appendChild(selectSet);
-
-// Programmatic usage - MultiSelect mode (controlled)
-const multiSet = document.createElement('button-vertical-list-set') as ButtonVerticalListSet;
-multiSet.mode = 'multiSelect';
-multiSet.selectedIndices = [0, 2];
-multiSet.minSelections = 1;
-multiSet.maxSelections = 3;
-multiSet.onMultiSelectionChange = (indices) => {
-  console.log(`Selections changed to ${indices}`);
-  multiSet.selectedIndices = indices; // Update controlled state
-};
-document.body.appendChild(multiSet);
-
-// Validation
-const result = selectSet.validate();
-if (!result.isValid) {
-  selectSet.error = true;
-  selectSet.errorMessage = result.message;
-}
-```
-
-### iOS (SwiftUI)
-
-```swift
-import DesignerPunk
-
-// Tap mode - action buttons
-ButtonVerticalListSet(
-    mode: .tap,
-    onItemClick: { index in
-        handleAction(index)
-    }
-) {
-    ButtonVerticalListItem(label: "Settings")
-    ButtonVerticalListItem(label: "Help")
-    ButtonVerticalListItem(label: "About")
-}
-
-// Select mode - single selection
-@State private var selectedOption: Int? = 0
-
-ButtonVerticalListSet(
-    mode: .select,
-    selectedIndex: $selectedOption,
-    required: true
-) {
-    ButtonVerticalListItem(label: "Option A", description: "First option")
-    ButtonVerticalListItem(label: "Option B", description: "Second option")
-    ButtonVerticalListItem(label: "Option C", description: "Third option")
-}
-
-// MultiSelect mode - multiple selections
-@State private var selectedOptions: [Int] = [0, 2]
-
-ButtonVerticalListSet(
-    mode: .multiSelect,
-    selectedIndices: $selectedOptions,
-    minSelections: 1,
-    maxSelections: 3
-) {
-    ButtonVerticalListItem(label: "Choice 1")
-    ButtonVerticalListItem(label: "Choice 2")
-    ButtonVerticalListItem(label: "Choice 3")
-    ButtonVerticalListItem(label: "Choice 4")
-}
-
-// With error state
-ButtonVerticalListSet(
-    mode: .select,
-    selectedIndex: $selectedOption,
-    required: true,
-    error: true,
-    errorMessage: "Please select an option"
-) {
-    ButtonVerticalListItem(label: "Option A")
-    ButtonVerticalListItem(label: "Option B")
-}
-```
-
-### Android (Jetpack Compose)
-
-```kotlin
-import com.designerpunk.components
-
-// Tap mode - action buttons
-ButtonVerticalListSet(
-    mode = SelectionMode.Tap,
-    onItemClick = { index -> handleAction(index) }
-) {
-    ButtonVerticalListItem(label = "Settings")
-    ButtonVerticalListItem(label = "Help")
-    ButtonVerticalListItem(label = "About")
-}
-
-// Select mode - single selection
-var selectedOption by remember { mutableStateOf<Int?>(0) }
-
-ButtonVerticalListSet(
-    mode = SelectionMode.Select,
-    selectedIndex = selectedOption,
-    onSelectionChange = { index -> selectedOption = index },
-    required = true
-) {
-    ButtonVerticalListItem(label = "Option A", description = "First option")
-    ButtonVerticalListItem(label = "Option B", description = "Second option")
-    ButtonVerticalListItem(label = "Option C", description = "Third option")
-}
-
-// MultiSelect mode - multiple selections
-var selectedOptions by remember { mutableStateOf(listOf(0, 2)) }
-
-ButtonVerticalListSet(
-    mode = SelectionMode.MultiSelect,
-    selectedIndices = selectedOptions,
-    onMultiSelectionChange = { indices -> selectedOptions = indices },
-    minSelections = 1,
-    maxSelections = 3
-) {
-    ButtonVerticalListItem(label = "Choice 1")
-    ButtonVerticalListItem(label = "Choice 2")
-    ButtonVerticalListItem(label = "Choice 3")
-    ButtonVerticalListItem(label = "Choice 4")
-}
-
-// With error state
-ButtonVerticalListSet(
-    mode = SelectionMode.Select,
-    selectedIndex = selectedOption,
-    onSelectionChange = { index -> selectedOption = index },
-    required = true,
-    error = true,
-    errorMessage = "Please select an option"
-) {
-    ButtonVerticalListItem(label = "Option A")
-    ButtonVerticalListItem(label = "Option B")
-}
-```
-
----
-
-## API Reference
-
-### Properties
-
-| Property | Type | Required | Default | Description |
-|----------|------|----------|---------|-------------|
-| `mode` | `'tap' \| 'select' \| 'multiSelect'` | ✅ Yes | - | Selection mode |
-| `selectedIndex` | `number \| null` | No | `null` | Selected index (Select mode) |
-| `selectedIndices` | `number[]` | No | `[]` | Selected indices (MultiSelect mode) |
-| `required` | `boolean` | No | `false` | Selection required (Select mode) |
-| `minSelections` | `number` | No | - | Minimum selections (MultiSelect mode) |
-| `maxSelections` | `number` | No | - | Maximum selections (MultiSelect mode) |
-| `error` | `boolean` | No | `false` | Error state indicator |
-| `errorMessage` | `string` | No | - | Error message to display |
-| `testID` | `string` | No | - | Test identifier |
-
-### Events/Callbacks
-
-| Callback | Parameters | Mode | Description |
-|----------|------------|------|-------------|
-| `onItemClick` | `(index: number)` | Tap | Item clicked |
-| `onSelectionChange` | `(index: number \| null)` | Select | Selection changed (null = deselected) |
-| `onMultiSelectionChange` | `(indices: number[])` | MultiSelect | Selections changed |
-
-### Methods
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `validate()` | `{ isValid: boolean; message: string \| null }` | Validate current selection against constraints |
-
----
-
-## Selection Modes
-
-### Tap Mode
-
-**Purpose**: Simple action buttons with no selection tracking.
-
-**Behavior**:
-- All items remain in `rest` visual state
-- Clicking an item invokes `onItemClick` callback
-- No selection state is maintained
-
-**ARIA**: `role="group"` on container, `role="button"` on items
-
-**Use Cases**: Navigation menus, action lists, settings shortcuts
-
-### Select Mode
-
-**Purpose**: Single-selection (radio-button style).
-
-**Behavior**:
-- Initial state: All items in `rest` state
-- After selection: Selected item → `selected`, others → `notSelected`
-- Re-selecting the selected item clears selection (all return to `rest`)
-- Selection changes invoke `onSelectionChange` callback
-
-**ARIA**: `role="radiogroup"` on container, `role="radio"` + `aria-checked` on items
-
-**Use Cases**: Single-choice questions, preference selection, option pickers
-
-### MultiSelect Mode
-
-**Purpose**: Multiple-selection (checkbox style).
-
-**Behavior**:
-- Items toggle between `checked` and `unchecked` states
-- Multiple items can be selected simultaneously
-- Selection changes invoke `onMultiSelectionChange` callback
-- Optional `minSelections` and `maxSelections` constraints
-
-**ARIA**: `role="group"` + `aria-multiselectable="true"` on container, `role="checkbox"` + `aria-checked` on items
-
-**Use Cases**: Multi-choice questions, feature toggles, filter selections
-
----
-
-## Animation Coordination
-
-The Set coordinates animation timing across child items to create smooth, polished transitions.
-
-### Select Mode Animations
-
-| Scenario | Deselecting Item | Selecting Item | Other Items |
-|----------|------------------|----------------|-------------|
-| **Selection change** | 0ms delay | 125ms delay | 0ms delay |
-| **First selection** | - | 0ms delay | 0ms delay |
-| **Deselection** | 0ms delay | - | 0ms delay |
-
-**Staggered Handoff**: When changing selection from item A to item B:
-- T=0ms: Item A begins deselection animation
-- T=125ms: Item B begins selection animation
-- T=250ms: Item A completes deselection
-- T=375ms: Item B completes selection
-
-**Checkmark Transition**: In Select mode, deselecting items get `checkmarkTransition='instant'` (checkmark hides immediately while border animates).
-
-### MultiSelect Mode Animations
-
-Each item animates independently with 0ms delay when toggled.
-
----
-
-## Error Handling
-
-### Validation
-
-The Set validates selection state against configured constraints:
-
-| Mode | Constraint | Validation |
-|------|------------|------------|
-| Select | `required={true}` | Fails if no selection |
-| MultiSelect | `minSelections={n}` | Fails if fewer than n selected |
-| MultiSelect | `maxSelections={n}` | Prevents selecting more than n |
-
-### Error State Propagation
-
-When `error={true}`:
-- All child items receive `error={true}`
-- Error message displays above the list with `role="alert"`
-- Container gets `aria-invalid="true"` and `aria-describedby`
-
-### Programmatic Validation
-
-```typescript
-const set = document.querySelector('button-vertical-list-set');
-const result = set.validate();
-
-if (!result.isValid) {
-  set.error = true;
-  set.errorMessage = result.message;
-} else {
-  set.error = false;
-  set.errorMessage = undefined;
-}
-```
-
----
-
-## Accessibility
-
-### WCAG 2.1 AA Compliance
-
-| Criterion | Status | Implementation |
-|-----------|--------|----------------|
-| 1.3.1 Info and Relationships | ✅ | Semantic ARIA roles based on mode |
-| 1.4.1 Use of Color | ✅ | Visual states use border/background, not just color |
-| 2.1.1 Keyboard | ✅ | Full keyboard navigation (Tab, Arrows, Enter, Space) |
-| 2.4.3 Focus Order | ✅ | Roving tabindex maintains logical focus order |
-| 2.4.7 Focus Visible | ✅ | Clear focus indicator on child items |
-| 3.3.1 Error Identification | ✅ | Error message with role="alert" |
-| 3.3.3 Error Suggestion | ✅ | Validation messages suggest correction |
-| 4.1.2 Name, Role, Value | ✅ | Proper ARIA roles and states |
-
-### Keyboard Navigation
-
-| Key | Action |
-|-----|--------|
-| Tab | Move focus into/out of the button group |
-| Arrow Down | Move focus to next item (wraps to first) |
-| Arrow Up | Move focus to previous item (wraps to last) |
-| Home | Move focus to first item |
-| End | Move focus to last item |
-| Enter | Activate focused item (mode-dependent) |
-| Space | Activate focused item (mode-dependent) |
-
-### Roving Tabindex Pattern
-
-The Set manages focus using roving tabindex:
-- Focused item has `tabindex="0"`
-- Other items have `tabindex="-1"`
-- Arrow keys move focus between items
-- Tab moves focus into/out of the group
-
-### Screen Reader Support
-
-- Container announces appropriate role (group, radiogroup)
-- Items announce role (button, radio, checkbox) and state
-- Selection changes are announced via `aria-checked`
-- Error messages are announced immediately via `role="alert"`
-
----
-
-## Token Dependencies
-
-### Spacing
-- `space.grouped.normal` (8px) - Gap between child items
-- `space.grouped.normal` (8px) - Error message margin
-
-### Typography
-- `typography.body.sm` - Error message text
-
-### Color
-- `color.error.strong` - Error message text color
-
-### Component-Scoped Properties
-
-The component uses `--_vls-*` prefix for internal CSS custom properties:
-
-| Property | Token Reference | Description |
-|----------|-----------------|-------------|
-| `--_vls-gap` | `space.grouped.normal` | Gap between items |
-| `--_vls-error-font-size` | `typography.body.sm.fontSize` | Error text size |
-| `--_vls-error-font-weight` | `typography.body.sm.fontWeight` | Error text weight |
-| `--_vls-error-line-height` | `typography.body.sm.lineHeight` | Error text line height |
-| `--_vls-error-color` | `color.error.strong` | Error text color |
-| `--_vls-error-margin-bottom` | `space.grouped.normal` | Error message spacing |
-
----
-
-## Design Decisions
-
-### Controlled-Only API
-
-**Decision**: The Set uses a controlled component pattern exclusively.
-
-**Rationale**: The Set needs to coordinate visual states across all items. In Select mode, when one item is selected, all other items must transition to `notSelected`. This coordination requires the Set to be the source of truth.
-
-**Trade-offs**:
-- ✅ Clear state ownership
-- ✅ Predictable behavior
-- ✅ Easy to integrate with form libraries
-- ❌ More boilerplate for simple use cases
-
-### No Disabled State
-
-**Decision**: The Set does not support disabling individual items.
-
-**Rationale**: Disabled buttons remove affordance without explanation. Screen reader users may not understand why something is disabled.
-
-**Alternatives**:
-1. **Hide unavailable options**: Don't render options that aren't available
-2. **Show validation messaging**: Keep items enabled, show error on invalid interaction
-
-### Error Message Position (Top)
-
-**Decision**: Error message displays above the list.
-
-**Rationale**: Users should see the error before the options, allowing them to understand the problem before making a selection.
-
-### Staggered Animation
-
-**Decision**: Selection changes use staggered animation (125ms offset).
-
-**Rationale**: The staggered "handoff" effect guides the user's eye from the old selection to the new selection, creating a polished feel without making the transition feel slow.
-
----
-
-## Platform-Specific Behavior
-
-### Web
-- Shadow DOM for style encapsulation
-- Roving tabindex for keyboard navigation
-- `:focus-visible` for keyboard-only focus ring
-- CSS logical properties for RTL support
-- Custom element tag: `<button-vertical-list-set>`
-
-### iOS
-- SwiftUI `@Binding` for controlled state
-- VoiceOver accessibility support
-- Haptic feedback on selection changes
-- Native gesture handling
-
-### Android
-- Jetpack Compose state hoisting
-- TalkBack accessibility support
-- Material ripple effects
-- Native gesture handling
-
----
-
-## File Structure
-
-```
-src/components/core/Button-VerticalList-Set/
-├── types.ts                              # Shared type definitions
-├── index.ts                              # Module exports
-├── README.md                             # This documentation
-├── platforms/
-│   ├── web/
-│   │   ├── ButtonVerticalListSet.web.ts      # Web Component implementation
-│   │   └── Button-VerticalList-Set.styles.css # Web styles
-│   ├── ios/
-│   │   ├── ButtonVerticalListSet.ios.swift       # SwiftUI implementation
-│   │   ├── ButtonVerticalListSetPreview.swift # SwiftUI Preview
-│   │   └── ButtonVerticalListSetTests.swift  # iOS unit tests
-│   └── android/
-│       ├── ButtonVerticalListSet.android.kt          # Jetpack Compose implementation
-│       ├── ButtonVerticalListSetPreview.kt   # Compose Preview
-│       └── ButtonVerticalListSetTest.kt      # Android unit tests
-└── __tests__/
-    ├── ButtonVerticalListSet.unit.test.ts        # Unit tests
-    ├── ButtonVerticalListSet.integration.test.ts # Integration tests
-    ├── ButtonVerticalListSet.property.test.ts    # Property tests (1-9)
-    ├── ButtonVerticalListSet.property2.test.ts   # Property tests (10-18)
-    ├── crossPlatformConsistency.test.ts          # Cross-platform behavioral tests
-    ├── animationTiming.test.ts                   # Animation coordination tests
-    ├── deriveItemStates.test.ts                  # State derivation tests
-    └── validation.test.ts                        # Validation logic tests
-```
-
----
-
-## Related Documentation
-
-- [Button-VerticalList-Item Component](../Button-VerticalList-Item/README.md) - Child item component
-- [Spec 041 - Vertical List Buttons Pattern](/.kiro/specs/041-vertical-list-buttons-pattern/) - Full specification
-- [Component Quick Reference](/.kiro/steering/Component-Quick-Reference.md) - Component selection guide
-
----
-
-*This component is part of the DesignerPunk Design System, following Stemma System principles for cross-platform consistency and AI-optimal discoverability.*

package/src/components/core/Button-VerticalList-Set/__tests__/.gitkeep

@@ -1,5 +0,0 @@
-# Placeholder for test files
-# Tests to be created in Task 7:
-# - ButtonVerticalListSet.unit.test.ts
-# - ButtonVerticalListSet.integration.test.ts
-# - ButtonVerticalListSet.property.test.ts