React Component Developer

Act as a senior React developer and TypeScript expert with 8+ years of production experience building scalable front-end systems. Build a complete, production-ready React component for the following specification.

COMPONENT SPECIFICATION:
[DESCRIBE THE COMPONENT — what it does, what data it receives, what interactions it handles, where it will be used]

TECH STACK (override if different):
• React 18+ with hooks
• TypeScript strict mode
• Tailwind CSS for styling
• No external component library unless specified

COMPLETE DELIVERABLES:

1. TYPESCRIPT INTERFACE & TYPES
• Define all props with precise TypeScript types — no `any`
• Use union types, generics, or discriminated unions where appropriate
• Add JSDoc comments on non-obvious props
• Export the Props type separately so consumers can extend it

2. COMPONENT IMPLEMENTATION
• Functional component with explicit return type
• All hooks — useState, useEffect, useCallback, useMemo — used only where genuinely needed, never as habit
• Controlled vs. uncontrolled decision: explain your choice briefly
• Proper useEffect cleanup (event listeners, timers, subscriptions)
• No inline function creation in JSX where avoidable

3. STATE MANAGEMENT
• If complex state: use useReducer with a typed action union
• Document why each piece of state exists — call out any derived state you chose NOT to store

4. ACCESSIBILITY (A11Y) — MANDATORY
• ARIA roles, labels, and attributes on all interactive elements
• Keyboard navigation: Tab, Enter, Escape, arrow keys where appropriate
• Visible focus ring that meets WCAG AA
• Screen reader announcements for dynamic content changes (aria-live)
• Color contrast considerations in Tailwind classes

5. ALL THREE UI STATES
• Loading state with skeleton or spinner + aria-busy
• Error state with a user-friendly message and a retry action
• Empty state with a helpful message and a suggested next action

6. PERFORMANCE NOTES
• Identify any render bottlenecks and apply memoisation where warranted
• Justify every React.memo, useCallback, and useMemo — no premature optimisation
• Note if any heavy dependency should be code-split

7. TESTING CHECKLIST
List 5 specific test cases a QA engineer should cover, including edge cases that are easy to miss.

8. EXAMPLE USAGE
Show at least 2 usage examples with different prop configurations, including the import statement.

9. KNOWN LIMITATIONS & FUTURE IMPROVEMENTS
• What this component intentionally does NOT handle
• What you would add in a larger-scale production context

Explain every non-obvious architectural decision you made.