Add Async Props documentation with animated SVG diagrams

[AbanoubGhadban]

Summary

• Adds comprehensive documentation for the Async Props feature
• Includes 4 static SVG diagrams explaining core concepts
• Includes 12 animated SVG diagrams with SMIL animations covering:
  • Streaming flow visualization
  • Suspense boundaries and resolution
  • Waterfall vs parallel fetching comparison
  • Hydration process
  • Error handling isolation
  • Full request lifecycle
  • Server vs client components
  • User experience comparison

Documentation Structure

docs/async-props/
├── README.md           # Overview and quick start
├── how-it-works.md     # Deep dive into streaming architecture
├── api-reference.md    # Complete API reference
├── advanced-usage.md   # Error handling, caching, patterns
└── images/
    ├── *.svg           # Static diagrams
    └── animated/*.svg  # Animated SMIL diagrams

Test plan

• Verify SVG diagrams render correctly in documentation
• Review documentation content for accuracy
• Consider converting animated SVGs to GIFs for GitHub compatibility

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch async-props-documentation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[claude]

📚 Documentation Review: Async Props with Animated SVG Diagrams

This is an excellent addition to the React on Rails Pro documentation! The comprehensive coverage with visual aids will greatly help users understand the streaming SSR feature.

---

✅ Strengths

1. Outstanding Visual Documentation

• 12 animated SVG diagrams using SMIL animations effectively illustrate complex streaming concepts
• 4 static SVGs provide clear architectural overviews
• Progressive loading sequence diagrams are particularly helpful for understanding the user experience
• Clean, professional design with good use of color gradients and animations

2. Well-Structured Content

• Logical progression from problem → solution → implementation
• Clear separation of concerns across 4 documents:
  • README.md: Quick start and overview
  • how-it-works.md: Deep technical dive
  • api-reference.md: Complete API documentation
  • advanced-usage.md: Patterns and best practices

3. Comprehensive Coverage

• Covers the full spectrum from beginner to advanced usage
• Includes error handling, caching, testing, and performance monitoring
• Real-world examples with both Ruby and TypeScript/React code
• Migration guide from traditional SSR

4. Technical Accuracy

• Documentation aligns with actual implementation in react_on_rails_pro/lib/react_on_rails_pro/async_props_emitter.rb
• Correctly describes the NDJSON protocol and streaming architecture
• Accurate explanation of sharedExecutionContext for request isolation

---

🔍 Suggestions for Improvement

1. GitHub SVG Animation Compatibility ⚠️

Issue: GitHub's markdown renderer may not support SMIL animations in SVG files for security reasons.

Recommendation: Consider one of these approaches:

• Convert animated SVGs to GIF animations for GitHub compatibility (tools like svg2gif or ffmpeg)
• Provide both SVG (for full quality) and GIF fallbacks
• Add a note in the PR description that animations may not display on GitHub but work in local environments

Test this: View the PR in GitHub's preview to confirm animations display correctly.

2. API Documentation Minor Gap

In api-reference.md, the async_prop helper is documented but the actual Rails controller method that makes this available isn't shown.

Suggested addition to api-reference.md:

# Ensure the helper is available in your controller
class ApplicationController < ActionController::Base
  include ReactOnRailsPro::Helper
end

3. Documentation Location

Placing docs at docs/async-props/ is good, but consider:

• Adding a reference in the main README.md linking to this feature documentation
• Adding an entry to CHANGELOG_PRO.md (since this is Pro-specific documentation)
• Updating any existing Pro documentation index/table of contents

4. Code Example Consistency

In how-it-works.md line 28-32, the comment says "Deferred: streamed when ready" but the actual implementation shows async_prop blocks are evaluated immediately in parallel (not deferred).

Clarification needed: The blocks execute immediately, but results stream as they complete. Consider updating the comment to:

title: "Dashboard",           # Immediate: sent in initial request
users: async_prop { ... },    # Parallel: executes immediately, streams when ready
posts: async_prop { ... }     # Parallel: executes immediately, streams when ready

5. Missing Error Code Documentation

api-reference.md lists error codes (lines 253-262), but these aren't referenced elsewhere. Consider:

• Adding examples showing when each error occurs
• Explaining how to handle each error type
• Verifying these match actual error codes in the implementation

6. TypeScript Types Verification

The TypeScript interfaces in api-reference.md (lines 226-251) should be verified against actual Pro package types:

# Check if these types exist in the codebase
grep -r "AsyncPropsManager" react_on_rails_pro/packages/ --include="*.ts" --include="*.tsx"

7. Testing Examples Need Adjustment

In advanced-usage.md lines 273-293, the Jest example imports from @react-on-rails-pro/core:

import { AsyncPropsProvider } from '@react-on-rails-pro/core';

Verify: Does this export exist in the Pro package? If not, provide the correct import path or note that this is a conceptual example.

---

📋 Pre-Merge Checklist

• Test SVG animations render in GitHub's markdown preview
• Add link to this documentation from main README.md
• Add entry to CHANGELOG_PRO.md documenting new documentation
• Verify all TypeScript type examples match actual Pro package exports
• Test all code examples work with current Pro version
• Consider converting animated SVGs to GIFs if animations don't render on GitHub
• Run bundle exec rubocop (documentation changes likely won't trigger violations, but good practice)
• Ensure all markdown files end with newline character

---

🎯 Overall Assessment

Code Quality: N/A (documentation only)
Content Quality: ⭐⭐⭐⭐⭐ (Excellent)
Visual Quality: ⭐⭐⭐⭐⭐ (Outstanding)
Completeness: ⭐⭐⭐⭐☆ (Very comprehensive, minor gaps noted)
Security Concerns: ✅ None
Performance Impact: ✅ None (documentation only)

---

🚀 Recommendation

Approve with minor revisions. This is excellent documentation that will significantly improve developer experience with the Async Props feature. The suggestions above are refinements rather than blockers.

Priority fixes:

1. Verify/convert animated SVGs for GitHub compatibility
2. Link from main documentation
3. Update CHANGELOG_PRO.md

Nice-to-haves:

• Verify all code examples against actual Pro package
• Add more real-world troubleshooting scenarios

Great work on creating such comprehensive, visual documentation! 🎉