feat: why this API - accessible disclosure widget with focused tests

[martinshub-tech]

Closes #391

feat: why this API — accessible disclosure widget with focused tests

What

Implements the WhyApi component (src/components/WhyApi.tsx) — a "Why this API?" disclosure widget surfaced on each marketplace ApiCard. It derives a short, human-readable list of recommendation reasons from the API's existing metrics (rating, uptime, latency, price, category) and reveals them through a native toggle/disclosure pattern.

Changes

src/components/WhyApi.tsx (modified)

• Replaced all inline style={{}} props with BEM class names (.why-api, .why-api__toggle, .why-api__toggle--open, .why-api__reasons, .why-api__item, .why-api__check, .why-api__text, .why-api__chevron)
• Exported WhyApiProps interface for downstream type safety
• Added why-api__toggle--open modifier class so the open state is CSS-targetable
• Expanded JSDoc: full param/return doc on buildReasons(), component-level ARIA guarantee list, design token inventory, and usage example

src/components/WhyApi.test.tsx (new)

36 focused tests across two suites — all passing:

buildReasons() (20 tests)

• Each metric signal fires at its threshold (rating ≥ 4.5, uptime ≥ 99.9 %, latency ≤ 150 ms, price ≤ $0.005, category present)
• Each signal correctly excluded just below threshold
• Format precision: rating to 1 dp, uptime to 2 dp
• pricePerCall takes precedence over pricePerRequest via ??
• Fallback: always returns ≥ 1 reason
• Boundary values at exact thresholds
• No throw on sparse/undefined optional fields

WhyApi component (16 tests)

• Initial closed state (aria-expanded="false", list absent)
• Toggle opens/closes list, syncs aria-expanded
• aria-controls wired to list id
• aria-label names the specific API
• Correct item count and text rendered
• Click propagation stopped (parent card handler not fired)
• BEM class presence: why-api__toggle, why-api__toggle--open added/removed correctly

src/index.css (modified)

Added self-contained .why-api BEM block:

• All values use design tokens (--accent, --accent-strong, --muted, --transition-speed)
• Light and dark mode consistent (tokens are theme-aware)
• Smooth fade-in animation (why-api-appear keyframe) on list open
• focus-visible ring matches app-wide focus style (2 px solid --accent, 3 px offset)
• Responsive: font scales down at < 400 px breakpoint
• user-select: none on decorative glyphs (chevron, check mark)

Accessibility (WCAG 2.1 AA)

• Toggle button: aria-expanded + aria-controls disclosure pattern
• Reasons list: aria-label + role="list"
• Decorative glyphs (▸▾, ✓): aria-hidden="true"
• Keyboard operable: Space / Enter toggle; Tab moves naturally
• Focus ring colour meets contrast requirements in both themes

Test output

[drips-wave]

@martinshub-tech Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[greatest0fallt1me]

LGTM ✅ solid work — thanks for taking this on!