@3fn/core 14.1.0 → 15.0.0

package/src/components/core/Progress-Stepper-Base/README.md

@@ -1,311 +0,0 @@
-# Progress-Stepper-Base
-
-**Family**: Progress Indicator
-**Type**: Semantic (Base)
-**Readiness**: Development
-**Platforms**: Web, iOS, Android
-
----
-
-## Overview
-
-Progress-Stepper-Base is a semantic component that composes Progress-Indicator-Node-Base and Progress-Indicator-Connector-Base primitives to create a stepper indicator for linear multi-step flows.
-
-It renders nodes connected by lines — no labels. State derivation follows a priority system: error > completed > current > incomplete. Completed nodes display a checkmark; all others display a dot.
-
-### Key Characteristics
-
-- Composes Node-Base + Connector-Base (no Label-Base)
-- State priority: error > completed > current > incomplete
-- Completed nodes get `content='checkmark'`, all others get `content='none'`
-- Connectors: active between completed nodes, inactive otherwise
-- 2 sizes: `md`, `lg` only (`sm` throws an error)
-- Max 8 steps (dev: throws, production: warns and clamps)
-- Non-interactive — navigation is handled by the parent flow
-- Accessibility: `role="progressbar"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax`
-
-### Use Cases
-
-- Multi-step form wizards
-- Checkout flows
-- Account setup sequences
-- Linear workflow progress tracking
-
----
-
-## Usage
-
-### Web (Custom Element)
-
-```html
-<!-- Basic: 5 steps, current is 3 -->
-<progress-stepper-base total-steps="5" current-step="3" size="md"></progress-stepper-base>
-
-<!-- Large size -->
-<progress-stepper-base total-steps="4" current-step="2" size="lg"></progress-stepper-base>
-
-<!-- With error steps -->
-<progress-stepper-base total-steps="5" current-step="3" size="md" error-steps="2"></progress-stepper-base>
-
-<!-- Multiple error steps -->
-<progress-stepper-base total-steps="6" current-step="4" size="lg" error-steps="2,5"></progress-stepper-base>
-
-<!-- Custom accessibility label -->
-<progress-stepper-base
-  total-steps="5"
-  current-step="3"
-  accessibility-label="Checkout progress: step 3 of 5"
-></progress-stepper-base>
-```
-
-### iOS (SwiftUI)
-
-```swift
-// Basic: 5 steps, current is 3
-ProgressStepperBase(totalSteps: 5, currentStep: 3, size: .md)
-
-// Large size
-ProgressStepperBase(totalSteps: 4, currentStep: 2, size: .lg)
-
-// With error steps
-ProgressStepperBase(totalSteps: 5, currentStep: 3, size: .md, errorSteps: [2])
-
-// Multiple error steps
-ProgressStepperBase(totalSteps: 6, currentStep: 4, size: .lg, errorSteps: [2, 5])
-
-// Custom accessibility label
-ProgressStepperBase(
-    totalSteps: 5,
-    currentStep: 3,
-    accessibilityLabel: "Checkout progress: step 3 of 5"
-)
-```
-
-### Android (Jetpack Compose)
-
-```kotlin
-// Basic: 5 steps, current is 3
-ProgressStepperBase(totalSteps = 5, currentStep = 3, size = ProgressNodeSize.MD)
-
-// Large size
-ProgressStepperBase(totalSteps = 4, currentStep = 2, size = ProgressNodeSize.LG)
-
-// With error steps
-ProgressStepperBase(totalSteps = 5, currentStep = 3, size = ProgressNodeSize.MD, errorSteps = listOf(2))
-
-// Multiple error steps
-ProgressStepperBase(totalSteps = 6, currentStep = 4, size = ProgressNodeSize.LG, errorSteps = listOf(2, 5))
-
-// Custom accessibility label
-ProgressStepperBase(
-    totalSteps = 5,
-    currentStep = 3,
-    accessibilityLabel = "Checkout progress: step 3 of 5"
-)
-```
-
----
-
-## API Reference
-
-| Property | Type | Default | Required | Description |
-|----------|------|---------|----------|-------------|
-| `totalSteps` | `number` | — | Yes | Total number of steps. Max 8 |
-| `currentStep` | `number` | — | Yes | Current active step (1-indexed). Clamped to [1, totalSteps] |
-| `size` | `'md' \| 'lg'` | `'md'` | No | Size variant. `sm` is not supported and throws an error |
-| `errorSteps` | `number[]` | `[]` | No | Array of step indices (1-indexed) in error state. Filtered to valid range |
-| `accessibilityLabel` | `string` | `'Step {currentStep} of {totalSteps}'` | No | Custom accessibility label override |
-| `testID` | `string` | `undefined` | No | Test identifier (web: `data-testid`, iOS: `accessibilityIdentifier`, Android: `testTag`) |
-
-### Constants
-
-| Constant | Value | Description |
-|----------|-------|-------------|
-| `STEPPER_MAX_STEPS` | 8 | Maximum supported steps |
-
-### Validation Behavior
-
-| Condition | Development | Production |
-|-----------|-------------|------------|
-| `totalSteps > 8` | Throws `Error` with guidance | `console.warn` + clamp to 8 |
-| `size = 'sm'` | Throws `Error` | Throws `Error` |
-| `currentStep < 1` | Clamps to 1 | Clamps to 1 |
-| `currentStep > totalSteps` | Clamps to `totalSteps` | Clamps to `totalSteps` |
-| `errorSteps` out of range | Filtered to [1, totalSteps] | Filtered to [1, totalSteps] |
-
-### Utility Functions
-
-| Function | Signature | Description |
-|----------|-----------|-------------|
-| `deriveStepperNodeState` | `(index, currentStep, errorSteps) → NodeState` | Derives state with priority: error > completed > current > incomplete |
-| `deriveStepperNodeContent` | `(state) → NodeContent` | Returns `'checkmark'` for completed, `'none'` for all others |
-| `deriveConnectorState` | `(leftState, rightState) → ConnectorState` | Returns `'active'` when both sides completed, `'inactive'` otherwise |
-| `clampCurrentStep` | `(currentStep, totalSteps) → number` | Clamps to valid range [1, totalSteps] |
-| `filterErrorSteps` | `(errorSteps, totalSteps) → number[]` | Filters to valid range [1, totalSteps] |
-
----
-
-## Composition
-
-Progress-Stepper-Base composes two primitives:
-
-| Primitive | Usage | Props Passed |
-|-----------|-------|--------------|
-| [Node-Base](../Progress-Indicator-Node-Base/README.md) | One per step | `state` (derived), `size`, `content` (checkmark or none) |
-| [Connector-Base](../Progress-Indicator-Connector-Base/README.md) | One between each adjacent pair (n-1 total) | `state` (active or inactive) |
-
-**Not composed:**
-- Label-Base — Stepper-Base has no text labels (see [Stepper-Detailed](../Progress-Stepper-Detailed/README.md) for labels)
-
-### Composition Diagram
-
-```
-Progress-Stepper-Base
-├── Node-Base (step 1)
-├── Connector-Base (between 1–2)
-├── Node-Base (step 2)
-├── Connector-Base (between 2–3)
-├── Node-Base (step 3)
-├── ...
-└── Node-Base (step N)
-```
-
-### State Derivation Logic
-
-Each node's state is derived using priority logic:
-
-| Priority | State | Condition |
-|----------|-------|-----------|
-| 1 (highest) | `error` | Step index is in `errorSteps` |
-| 2 | `completed` | Step index < `currentStep` and not in `errorSteps` |
-| 3 | `current` | Step index === `currentStep` and not in `errorSteps` |
-| 4 (lowest) | `incomplete` | Step index > `currentStep` |
-
-**Node content** is derived from state:
-- `completed` → `content='checkmark'` (displays ✓)
-- All others → `content='none'` (displays dot)
-
-**Connector state** is derived from adjacent nodes:
-- Both sides `completed` → `state='active'` (green line)
-- Any other combination → `state='inactive'` (gray line)
-
-### Example: 5 steps, currentStep=3, errorSteps=[5]
-
-| Step | State | Content | Connector After |
-|------|-------|---------|-----------------|
-| 1 | completed | checkmark | active (1→2 both completed) |
-| 2 | completed | checkmark | inactive (2→3 completed→current) |
-| 3 | current | none | inactive (3→4 current→incomplete) |
-| 4 | incomplete | none | inactive (4→5 incomplete→error) |
-| 5 | error | none | — |
-
----
-
-## Token Dependencies
-
-### Component Size Tokens (`progress.node.size.*`)
-
-| Token | Value | Usage |
-|-------|-------|-------|
-| `progress.node.size.md` | 16px | Medium node base size |
-| `progress.node.size.lg` | 24px | Large node base size |
-| `progress.node.size.md.current` | 20px | Medium current emphasis (+4px) |
-| `progress.node.size.lg.current` | 28px | Large current emphasis (+4px) |
-
-Note: `sm` size tokens exist but are not used by Stepper-Base (sm throws an error).
-
-### Component Gap Tokens (`progress.node.gap.*`)
-
-| Token | CSS Custom Property | Value | Primitive | Usage |
-|-------|---------------------|-------|-----------|-------|
-| `progress.node.gap.md` | `--progress-node-gap-md` | 8px | `space100` | Spacing between md elements |
-| `progress.node.gap.lg` | `--progress-node-gap-lg` | 12px | `space150` | Spacing between lg elements |
-
-### Connector Thickness Token
-
-| Token | Value | Primitive | Usage |
-|-------|-------|-----------|-------|
-| `progress.connector.thickness` | 1px | `borderDefault` | Line thickness between nodes |
-
-### Semantic Color Tokens (via primitives)
-
-Color tokens are applied by the Node-Base and Connector-Base primitives, not directly by Stepper-Base:
-
-| Token | Primitive | State |
-|-------|-----------|-------|
-| `color.progress.current.background` | `cyan300` | Current node |
-| `color.progress.completed.background` | `green100` | Completed node |
-| `color.progress.completed.text` | `green400` | Checkmark on completed node |
-| `color.progress.pending.background` | `white300` | Incomplete node |
-| `color.progress.error.background` | `pink100` | Error node |
-| `color.progress.error.text` | `pink400` | Icon on error node |
-| `color.progress.completed.connector` | `green100` | Active connector |
-| `color.progress.pending.connector` | `white200` | Inactive connector |
-
-**Token source files:**
-- Semantic: `src/tokens/semantic/color-progress.ts`
-- Component: `src/tokens/component/progress.ts`
-
----
-
-## Accessibility
-
-### ARIA Implementation
-
-| Platform | Role | Attributes |
-|----------|------|------------|
-| Web | `role="progressbar"` | `aria-valuenow={currentStep}`, `aria-valuemin={1}`, `aria-valuemax={totalSteps}`, `aria-label` |
-| iOS | `.accessibilityAddTraits(.updatesFrequently)` | `.accessibilityValue("Step X of Y")`, `.accessibilityLabel` |
-| Android | `semantics { progressBarRangeInfo }` | `contentDescription`, `ProgressBarRangeInfo(current, range)` |
-
-### Key Accessibility Behaviors
-
-- Default label: "Step {currentStep} of {totalSteps}"
-- Custom `accessibilityLabel` prop overrides the default
-- Current node has non-color differentiation via +4px size emphasis
-- Screen reader announces step position within the total
-
-### WCAG 2.1 AA Compliance
-
-- **1.3.1 Info and Relationships**: `role="progressbar"` with `aria-value*` attributes conveys step position
-- **1.4.11 Non-text Contrast**: Current node size emphasis (+4px) provides non-color differentiation
-- **4.1.2 Name, Role, Value**: `aria-valuenow`, `aria-valuemin`, `aria-valuemax` reflect actual step position
-
----
-
-## Platform-Specific Notes
-
-### Web
-- Custom Element: `<progress-stepper-base>`
-- Shadow DOM for style encapsulation
-- CSS custom properties for gap tokens (with fallback values)
-- Attributes use kebab-case: `total-steps`, `current-step`, `error-steps`, `accessibility-label`, `test-id`
-- Composes `<progress-indicator-node-base>` and `<progress-indicator-connector-base>` in shadow DOM
-- Flexbox layout with `gap` for spacing
-
-### iOS
-- SwiftUI `View` struct: `ProgressStepperBase`
-- Uses `HStack` with `spacing` from gap token values
-- Composes `ProgressIndicatorNodeBase` and `ProgressIndicatorConnectorBase` views via `ForEach`
-- Accessibility: `.accessibilityElement(children: .ignore)` with `.accessibilityValue` and `.accessibilityLabel`
-- Debug builds use `assertionFailure` for totalSteps > 8; `precondition` for size = sm
-
-### Android
-- Jetpack Compose `@Composable` function: `ProgressStepperBase`
-- Uses `Row` with `Arrangement.spacedBy` from gap token values
-- Connectors wrapped in `Box(modifier = Modifier.weight(1f))` for flexible length
-- Accessibility: `semantics { contentDescription; progressBarRangeInfo }` 
-- Debug builds throw `IllegalArgumentException` for totalSteps > 8; `require` for size = sm
-
----
-
-## Related Documentation
-
-- [Node-Base](../Progress-Indicator-Node-Base/README.md) — Primitive node composed by this component
-- [Connector-Base](../Progress-Indicator-Connector-Base/README.md) — Primitive connector composed by this component
-- [Label-Base](../Progress-Indicator-Label-Base/README.md) — Primitive label (not used by Stepper-Base)
-- [Pagination-Base](../Progress-Pagination-Base/README.md) — Semantic variant: dots only, supports sm size
-- [Stepper-Detailed](../Progress-Stepper-Detailed/README.md) — Semantic variant: nodes + connectors + labels + icons
-- [Spec Requirements](/.kiro/specs/048-progress-family/requirements.md) — Requirements 3.1–3.17, 7.3, 7.12, 8.4–8.5, 8.8–8.10, 10.3–10.7, 11.7–11.13
-- [Spec Design](/.kiro/specs/048-progress-family/design.md) — Design specification
-- [Design Outline](/.kiro/specs/048-progress-family/design-outline.md) — Original design outline

package/src/components/core/Progress-Stepper-Base/__tests__/StepperBase.test.ts

@@ -1,345 +0,0 @@
-/**
- * @jest-environment jsdom
- */
-
-/**
- * @category evergreen
- * @purpose Verify Progress-Stepper-Base behavioral contracts, composition, state derivation, validation, and accessibility
- */
-
-/**
- * Stepper-Base Tests
- * 
- * Stemma System: Progress Indicator Family
- * Component Type: Semantic (Base)
- * 
- * Tests verify:
- * - Stemma behavioral contracts: naming, type classification, prop validation, accessibility (Req 13.2, 13.8, 13.11, 13.14)
- * - Composition: renders nodes and connectors, no labels (Req 15.15-15.18)
- * - State derivation: priority logic error > completed > current > incomplete (Req 15.20)
- * - Validation: dev throw, production warn+clamp for >8 steps, throw for sm size (Req 15.35-15.37)
- * - Accessibility: ARIA progressbar, aria-value* attributes (Req 15.26)
- * 
- * Requirements: 13.2, 13.8, 13.11, 13.14, 15.11-15.15, 15.16-15.18, 15.20, 15.26, 15.35-15.37, 15.39
- * @see .kiro/specs/048-progress-family/requirements.md
- */
-
-import { cleanupDOM } from '../../../../__tests__/helpers/web-component-test-utils';
-import * as fs from 'fs';
-import * as path from 'path';
-import { describe, it, expect, beforeAll, beforeEach } from '@jest/globals';
-import { ProgressStepperBase } from '../platforms/web/ProgressStepperBase.web';
-import {
-  deriveStepperNodeState,
-  deriveStepperNodeContent,
-  deriveConnectorState,
-  clampCurrentStep,
-  filterErrorSteps,
-  STEPPER_MAX_STEPS,
-} from '../types';
-
-// ============================================================================
-// Helpers
-// ============================================================================
-
-/** Create a stepper component with given attributes */
-function createStepper(attrs: Record<string, string> = {}): ProgressStepperBase {
-  const el = document.createElement('progress-stepper-base') as ProgressStepperBase;
-  for (const [key, value] of Object.entries(attrs)) {
-    el.setAttribute(key, value);
-  }
-  document.body.appendChild(el);
-  return el;
-}
-
-/** Read the schema YAML for Stemma contract assertions */
-function readSchema(): string {
-  const schemaPath = path.resolve(
-    process.cwd(),
-    'src/components/core/Progress-Stepper-Base/Progress-Stepper-Base.schema.yaml'
-  );
-  return fs.existsSync(schemaPath) ? fs.readFileSync(schemaPath, 'utf-8') : '';
-}
-
-// ============================================================================
-// Test Suite
-// ============================================================================
-
-describe('Progress-Stepper-Base', () => {
-  let schemaContent: string;
-
-  beforeAll(() => {
-    if (!customElements.get('progress-stepper-base')) {
-      customElements.define('progress-stepper-base', ProgressStepperBase);
-    }
-    schemaContent = readSchema();
-  });
-
-  beforeEach(() => {
-    cleanupDOM();
-  });
-
-  // ==========================================================================
-  // Stemma Behavioral Contracts (Req 13.2, 13.8, 13.11, 13.14)
-  // ==========================================================================
-
-  describe('Stemma Behavioral Contracts', () => {
-    it('follows [Family]-[Type]-[Variant] naming pattern (Req 13.2)', () => {
-      expect(schemaContent).toMatch(/name:\s*Progress-Stepper-Base/);
-      expect(schemaContent).toMatch(/family:\s*ProgressIndicator/);
-    });
-
-    it('is classified as semantic component type (Req 13.8)', () => {
-      expect(schemaContent).toMatch(/type:\s*semantic/);
-    });
-
-    it('requires totalSteps and currentStep props (Req 13.11)', () => {
-      expect(schemaContent).toMatch(/totalSteps:[\s\S]*?required:\s*true/);
-      expect(schemaContent).toMatch(/currentStep:[\s\S]*?required:\s*true/);
-    });
-
-    it('specifies role="progressbar" and aria-value* in accessibility (Req 13.14)', () => {
-      expect(schemaContent).toMatch(/role='progressbar'/);
-      expect(schemaContent).toMatch(/aria-value/);
-    });
-  });
-
-  // ==========================================================================
-  // Composition Tests (Req 15.15-15.18, 11.7-11.13)
-  // ==========================================================================
-
-  describe('Composition', () => {
-    it('renders Node-Base primitives for each step (Req 15.16)', () => {
-      const el = createStepper({ 'total-steps': '5', 'current-step': '3', size: 'md' });
-      const nodes = el.shadowRoot!.querySelectorAll('progress-indicator-node-base');
-      expect(nodes.length).toBe(5);
-    });
-
-    it('renders n-1 Connector-Base elements between nodes (Req 15.16)', () => {
-      const el = createStepper({ 'total-steps': '5', 'current-step': '3' });
-      const connectors = el.shadowRoot!.querySelectorAll('progress-indicator-connector-base');
-      expect(connectors.length).toBe(4);
-    });
-
-    it('does NOT render Label-Base elements (Req 15.16)', () => {
-      const el = createStepper({ 'total-steps': '5', 'current-step': '3' });
-      const labels = el.shadowRoot!.querySelectorAll('progress-indicator-label-base');
-      expect(labels.length).toBe(0);
-    });
-
-    it('passes content="checkmark" to completed nodes (Req 15.18)', () => {
-      const el = createStepper({ 'total-steps': '5', 'current-step': '4' });
-      const nodes = el.shadowRoot!.querySelectorAll('progress-indicator-node-base');
-      // Steps 1-3 are completed (before currentStep=4)
-      for (let i = 0; i < 3; i++) {
-        expect(nodes[i].getAttribute('content')).toBe('checkmark');
-      }
-    });
-
-    it('passes content="none" to current/incomplete/error nodes (Req 15.18)', () => {
-      const el = createStepper({ 'total-steps': '5', 'current-step': '3', 'error-steps': '5' });
-      const nodes = el.shadowRoot!.querySelectorAll('progress-indicator-node-base');
-      // Step 3 = current, step 4 = incomplete, step 5 = error — all should be 'none'
-      expect(nodes[2].getAttribute('content')).toBe('none');
-      expect(nodes[3].getAttribute('content')).toBe('none');
-      expect(nodes[4].getAttribute('content')).toBe('none');
-    });
-
-    it('passes size prop to each node', () => {
-      const el = createStepper({ 'total-steps': '3', 'current-step': '1', size: 'lg' });
-      const nodes = el.shadowRoot!.querySelectorAll('progress-indicator-node-base');
-      nodes.forEach((node) => {
-        expect(node.getAttribute('size')).toBe('lg');
-      });
-    });
-  });
-
-
-  // ==========================================================================
-  // State Derivation Tests (Req 15.20, 10.3-10.7)
-  // ==========================================================================
-
-  describe('State Derivation', () => {
-    it('deriveStepperNodeState returns "error" for steps in errorSteps (highest priority) (Req 10.3)', () => {
-      expect(deriveStepperNodeState(2, 3, [2])).toBe('error');
-    });
-
-    it('deriveStepperNodeState returns "completed" for steps before currentStep (Req 10.4)', () => {
-      expect(deriveStepperNodeState(1, 3, [])).toBe('completed');
-      expect(deriveStepperNodeState(2, 3, [])).toBe('completed');
-    });
-
-    it('deriveStepperNodeState returns "current" for currentStep (Req 10.5)', () => {
-      expect(deriveStepperNodeState(3, 3, [])).toBe('current');
-    });
-
-    it('deriveStepperNodeState returns "incomplete" for steps after currentStep (Req 10.6)', () => {
-      expect(deriveStepperNodeState(4, 3, [])).toBe('incomplete');
-      expect(deriveStepperNodeState(5, 3, [])).toBe('incomplete');
-    });
-
-    it('error overrides completed state (priority: error > completed) (Req 10.7)', () => {
-      // Step 1 is before currentStep=3 (would be completed), but is in errorSteps
-      expect(deriveStepperNodeState(1, 3, [1])).toBe('error');
-    });
-
-    it('error overrides current state (priority: error > current) (Req 10.7)', () => {
-      // Step 3 is currentStep, but is in errorSteps
-      expect(deriveStepperNodeState(3, 3, [3])).toBe('error');
-    });
-
-    it('deriveStepperNodeContent returns "checkmark" for completed, "none" for others', () => {
-      expect(deriveStepperNodeContent('completed')).toBe('checkmark');
-      expect(deriveStepperNodeContent('current')).toBe('none');
-      expect(deriveStepperNodeContent('incomplete')).toBe('none');
-      expect(deriveStepperNodeContent('error')).toBe('none');
-    });
-
-    it('deriveConnectorState returns "active" when both sides are completed', () => {
-      expect(deriveConnectorState('completed', 'completed')).toBe('active');
-    });
-
-    it('deriveConnectorState returns "inactive" when either side is not completed', () => {
-      expect(deriveConnectorState('completed', 'current')).toBe('inactive');
-      expect(deriveConnectorState('current', 'incomplete')).toBe('inactive');
-      expect(deriveConnectorState('incomplete', 'incomplete')).toBe('inactive');
-    });
-
-    it('rendered nodes reflect correct state derivation with priority', () => {
-      // 5 steps, current=3, error on step 1
-      const el = createStepper({ 'total-steps': '5', 'current-step': '3', 'error-steps': '1' });
-      const nodes = el.shadowRoot!.querySelectorAll('progress-indicator-node-base');
-      expect(nodes[0].getAttribute('state')).toBe('error');      // step 1: error (overrides completed)
-      expect(nodes[1].getAttribute('state')).toBe('completed');   // step 2: completed
-      expect(nodes[2].getAttribute('state')).toBe('current');     // step 3: current
-      expect(nodes[3].getAttribute('state')).toBe('incomplete');  // step 4: incomplete
-      expect(nodes[4].getAttribute('state')).toBe('incomplete');  // step 5: incomplete
-    });
-
-    it('rendered connectors reflect correct state derivation', () => {
-      // 4 steps, current=4 (all completed except current)
-      const el = createStepper({ 'total-steps': '4', 'current-step': '4' });
-      const connectors = el.shadowRoot!.querySelectorAll('progress-indicator-connector-base');
-      // Connectors: between 1-2 (completed-completed=active), 2-3 (completed-completed=active), 3-4 (completed-current=inactive)
-      expect(connectors[0].getAttribute('state')).toBe('active');
-      expect(connectors[1].getAttribute('state')).toBe('active');
-      expect(connectors[2].getAttribute('state')).toBe('inactive');
-    });
-  });
-
-  // ==========================================================================
-  // Validation Tests (Req 15.35-15.37, 8.4-8.5, 8.8-8.10)
-  // ==========================================================================
-
-  describe('Validation', () => {
-    it('STEPPER_MAX_STEPS constant is 8 (Req 8.4)', () => {
-      expect(STEPPER_MAX_STEPS).toBe(8);
-    });
-
-    it('clampCurrentStep clamps below lower bound to 1 (Req 15.36)', () => {
-      expect(clampCurrentStep(0, 5)).toBe(1);
-      expect(clampCurrentStep(-3, 5)).toBe(1);
-    });
-
-    it('clampCurrentStep clamps above upper bound to totalSteps (Req 15.36)', () => {
-      expect(clampCurrentStep(10, 5)).toBe(5);
-    });
-
-    it('clampCurrentStep returns value when within bounds', () => {
-      expect(clampCurrentStep(3, 5)).toBe(3);
-    });
-
-    it('filterErrorSteps removes indices outside valid range (Req 15.37)', () => {
-      const result = filterErrorSteps([0, 1, 3, 6, 10], 5);
-      expect(result).toEqual([1, 3]);
-    });
-
-    it('throws error when size="sm" (Req 8.10)', () => {
-      // jsdom's custom element lifecycle is async, so we need to catch the error differently.
-      // preventDefault() marks the error HANDLED, which stops jsdom's default reporter from
-      // printing an "Uncaught [Error: ...]" console.error block for this expected throw
-      // (CI-log noise; the assertion below still receives the event first).
-      const errorHandler = jest.fn((event: ErrorEvent) => event.preventDefault());
-      window.addEventListener('error', errorHandler);
-
-      createStepper({ 'total-steps': '3', 'current-step': '1', size: 'sm' });
-
-      expect(errorHandler).toHaveBeenCalled();
-      const errorEvent = errorHandler.mock.calls[0][0];
-      expect(errorEvent.error.message).toContain("Steppers require size 'md' or 'lg'");
-
-      window.removeEventListener('error', errorHandler);
-    });
-
-    it('warns and clamps in production when totalSteps > 8 (Req 8.5, 15.35)', () => {
-      const origEnv = process.env.NODE_ENV;
-      process.env.NODE_ENV = 'production';
-      const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
-      try {
-        const el = createStepper({ 'total-steps': '12', 'current-step': '1' });
-        expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('maximum is 8'));
-        // Should render only 8 nodes (clamped)
-        const nodes = el.shadowRoot!.querySelectorAll('progress-indicator-node-base');
-        expect(nodes.length).toBe(8);
-      } finally {
-        warnSpy.mockRestore();
-        process.env.NODE_ENV = origEnv;
-      }
-    });
-
-    it('clamps currentStep outside bounds in rendered output (Req 15.36)', () => {
-      const el = createStepper({ 'total-steps': '5', 'current-step': '10' });
-      const nodes = el.shadowRoot!.querySelectorAll('progress-indicator-node-base');
-      // currentStep clamped to 5, so last node should be current
-      const lastNode = nodes[nodes.length - 1];
-      expect(lastNode.getAttribute('state')).toBe('current');
-    });
-  });
-
-
-  // ==========================================================================
-  // Accessibility Tests (Req 15.26, 7.3, 7.12)
-  // ==========================================================================
-
-  describe('Accessibility', () => {
-    it('applies role="progressbar" to container (Req 7.3)', () => {
-      const el = createStepper({ 'total-steps': '5', 'current-step': '2' });
-      const container = el.shadowRoot!.querySelector('[role="progressbar"]');
-      expect(container).not.toBeNull();
-    });
-
-    it('sets aria-valuenow to currentStep (Req 7.3)', () => {
-      const el = createStepper({ 'total-steps': '5', 'current-step': '3' });
-      const container = el.shadowRoot!.querySelector('[role="progressbar"]');
-      expect(container!.getAttribute('aria-valuenow')).toBe('3');
-    });
-
-    it('sets aria-valuemin to 1 (Req 7.3)', () => {
-      const el = createStepper({ 'total-steps': '5', 'current-step': '3' });
-      const container = el.shadowRoot!.querySelector('[role="progressbar"]');
-      expect(container!.getAttribute('aria-valuemin')).toBe('1');
-    });
-
-    it('sets aria-valuemax to totalSteps (Req 7.3)', () => {
-      const el = createStepper({ 'total-steps': '5', 'current-step': '3' });
-      const container = el.shadowRoot!.querySelector('[role="progressbar"]');
-      expect(container!.getAttribute('aria-valuemax')).toBe('5');
-    });
-
-    it('aria-label defaults to "Step X of Y" (Req 7.12)', () => {
-      const el = createStepper({ 'total-steps': '8', 'current-step': '4' });
-      const container = el.shadowRoot!.querySelector('[role="progressbar"]');
-      expect(container!.getAttribute('aria-label')).toBe('Step 4 of 8');
-    });
-
-    it('supports custom accessibility label override', () => {
-      const el = createStepper({
-        'total-steps': '5',
-        'current-step': '2',
-        'accessibility-label': 'Progress: step 2 of 5',
-      });
-      const container = el.shadowRoot!.querySelector('[role="progressbar"]');
-      expect(container!.getAttribute('aria-label')).toBe('Progress: step 2 of 5');
-    });
-  });
-});