fix: support flex-based sizing without explicit width/height

[dohooo]

Summary

This PR fixes the issue where Carousel would not render when using style={{ flex: 1 }} without explicit width/height values.

Changes

1. useVisibleRanges.tsx: Handle viewSize <= 0 to prevent division by zero and return sensible default ranges
2. ItemRenderer.tsx: Initialize displayedItems with sensible defaults instead of null to ensure items render on first frame
3. Tests: Added 7 new tests covering:
   • viewSize boundary conditions (0, negative values)
   • Carousel sizing scenarios (flex-based, explicit dimensions, itemWidth)
4. Documentation: Added "Sizing Your Carousel" section to usage.mdx explaining all sizing options

How to Use

Now users can use flex-based sizing:

<View style={{ flex: 1 }}>
  <Carousel
    style={{ flex: 1 }}
    data={data}
    renderItem={renderItem}
  />
</View>

Or explicit dimensions:

<Carousel
  style={{ width: 300, height: 200 }}
  data={data}
  renderItem={renderItem}
/>

Fixes #668

[changeset-bot]

⚠️ No Changeset found

Latest commit: 82f225e

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
react-native-reanimated-carousel	Ready	Preview, Comment	Dec 13, 2025 8:20am

[dosubot]

Related Documentation

Checked 1 published document(s) in 1 knowledge base(s). No updates required.

^{How did I do? Any feedback?}  

[codecov]

Codecov Report

❌ Patch coverage is 58.62069% with 12 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.38%. Comparing base (13861ac) to head (82f225e).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
src/components/ScrollViewGesture.tsx	42.10%	0 Missing and 11 partials ⚠️
src/components/ItemLayout.tsx	75.00%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #877      +/-   ##
==========================================
+ Coverage   81.90%   82.38%   +0.47%     
==========================================
  Files          35       35              
  Lines        1006     1016      +10     
  Branches      339      346       +7     
==========================================
+ Hits          824      837      +13     
  Misses         81       81              
+ Partials      101       98       -3     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.