diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml new file mode 100644 index 0000000..b37fee8 --- /dev/null +++ b/.github/workflows/deploy-docs.yml @@ -0,0 +1,59 @@ +name: Deploy Documentation + +on: + push: + branches: + - main + paths: + - 'docs/**' + - '.github/workflows/deploy-docs.yml' + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + defaults: + run: + working-directory: docs + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' + cache-dependency-path: docs/package-lock.json + + - name: Install dependencies + run: npm ci + + - name: Build website + run: npm run build + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: docs/build + + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/README.md b/README.md index 5cee5ad..dc8e93e 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,17 @@ Native Modal implementation which allows to display multiple Modals simultaneous ![React Native Multiple Modals](./assets/preview.gif) +## 📚 Documentation + +For comprehensive documentation, visit: **[https://paufau.github.io/react-native-multiple-modals/](https://paufau.github.io/react-native-multiple-modals/)** + +The documentation includes: +- 📖 [Installation Guide](https://paufau.github.io/react-native-multiple-modals/installation) +- 🚀 [Usage Examples](https://paufau.github.io/react-native-multiple-modals/usage) +- 🔧 [API Reference](https://paufau.github.io/react-native-multiple-modals/api/properties) +- 🐛 [Troubleshooting](https://paufau.github.io/react-native-multiple-modals/troubleshooting) +- 🤝 [Contributing](https://paufau.github.io/react-native-multiple-modals/contribution) + ## ✨ Features - 🚀 Shows multiple instances at the same time @@ -160,7 +171,7 @@ Follow instructions: https://github.com/paufau/react-native-multiple-modals-exam Common: -- Create separate documentation page +- ✅ Create separate documentation page - [View Docs](https://paufau.github.io/react-native-multiple-modals/) ## Troubleshooting diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..b2d6de3 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,20 @@ +# Dependencies +/node_modules + +# Production +/build + +# Generated files +.docusaurus +.cache-loader + +# Misc +.DS_Store +.env.local +.env.development.local +.env.test.local +.env.production.local + +npm-debug.log* +yarn-debug.log* +yarn-error.log* diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..d41b367 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,43 @@ +# React Native Multiple Modals - Documentation + +This directory contains the Docusaurus-based documentation for React Native Multiple Modals. + +## Quick Start + +### Local Development + +```bash +npm install +npm start +``` + +### Build + +```bash +npm run build +``` + +## Deployment + +The documentation automatically deploys to GitHub Pages via GitHub Actions on changes to `main`. + +**Initial Setup** (one-time): +1. Go to repository Settings → Pages +2. Set Source to "GitHub Actions" +3. Verify workflow permissions in Settings → Actions → General + +Once configured, the site will be live at: https://paufau.github.io/react-native-multiple-modals/ + +## Structure + +- `docs/` - Documentation markdown files +- `static/` - Static assets (images, etc.) +- `docusaurus.config.ts` - Configuration +- `sidebars.ts` - Sidebar structure + +## Contributing + +1. Edit markdown files in `docs/` +2. Test locally with `npm start` +3. Build to verify: `npm run build` +4. Submit a pull request diff --git a/docs/docs/api/properties.md b/docs/docs/api/properties.md new file mode 100644 index 0000000..1e6d977 --- /dev/null +++ b/docs/docs/api/properties.md @@ -0,0 +1,248 @@ +--- +sidebar_position: 4 +--- + +# Properties + +Complete reference for all available properties of the `ModalView` component. + +## animationType + +```tsx +animationType?: "fade" | "slide" | "none" +``` + +**Default:** `"none"` + +The `animationType` prop controls how the modal animates when appearing and disappearing. + +**Possible values:** + +- `"slide"` - Slides in from the bottom +- `"fade"` - Fades into view +- `"none"` - Appears without an animation + +**Example:** + +```tsx + + + +``` + +--- + +## contentContainerStyle + +```tsx +contentContainerStyle?: ViewStyle +``` + +Styles for the content wrapper. Use it for aligning your content view within the modal. + +**Example:** + +```tsx + + + +``` + +--- + +## statusBar + +```tsx +statusBar?: StatusBarProps +``` + +**Platform:** Native Only (iOS & Android) + +Controls the status bar appearance within the modal. + +**Platform-specific support:** +- **Android** - Supports only `translucent` and `barStyle` props +- **iOS** - All StatusBar props are supported + +[See React Native StatusBarProps documentation](https://reactnative.dev/docs/statusbar#props) + +**Example:** + +```tsx + + + +``` + +--- + +## disableDefaultStatusBarIOS + +```tsx +disableDefaultStatusBarIOS?: boolean +``` + +**Default:** `false` + +**Platform:** iOS Only + +Allows you to disable the inner StatusBar component in case you are using `expo-status-bar` or want to manage the status bar manually. + +**Note:** This is only applicable for iOS because the status bar is shared between all modal windows on iOS. On Android, the status bar is tightly coupled to the individual modal window and cannot be controlled through the StatusBar component. + +**Example:** + +```tsx + + {/* Using expo-status-bar */} + + +``` + +--- + +## onRequestDismiss + +```tsx +onRequestDismiss?: (calledBy: 'Backdrop' | 'BackButton') => void +``` + +Callback method that is called when the backdrop is pressed or the back button is pressed (Android). + +The `calledBy` parameter indicates what triggered the dismissal: +- `'Backdrop'` - User tapped on the backdrop +- `'BackButton'` - User pressed the hardware back button (Android) + +**💡 TIP:** If you want the modal to block the interface and not close when the user taps the backdrop or back button, simply don't pass this function. The modal will remain rendered until you remove it from the React tree. + +**Example:** + +```tsx + { + console.log(`Modal dismissed by: ${calledBy}`); + setModalVisible(false); + }} +> + + +``` + +--- + +## renderBackdrop + +```tsx +renderBackdrop?: () => ReactNode +``` + +Use this prop to render a custom backdrop component. This is useful when you want to use a blur effect or other custom backdrop implementations. + +**Example with BlurView:** + +```tsx +import { BlurView } from 'expo-blur'; + + ( + + )} +> + + +``` + +--- + +## backdropColor + +```tsx +backdropColor?: string +``` + +**Default:** `"rgba(0, 0, 0, 0.3)"` + +The background color of the default backdrop. This prop is ignored if you provide a custom `renderBackdrop`. + +**Example:** + +```tsx + + + +``` + +--- + +## BackdropPressableComponent + +```tsx +BackdropPressableComponent?: FC +``` + +The component which wraps the backdrop. Use this to override the default Pressable component with your own implementation. + +This is useful when you want to: +- Apply additional props to the backdrop +- Use `react-native-gesture-handler`'s Pressable +- Make the backdrop untouchable + +**Example making backdrop untouchable:** + +```tsx +import { Pressable } from 'react-native'; + +const UntouchablePressable = (props) => ( + +); + + + + +``` + +**Example with gesture handler:** + +```tsx +import { Pressable } from 'react-native-gesture-handler'; + + + + +``` + +--- + +## statusBarTranslucent (Deprecated) + +```tsx +statusBarTranslucent?: boolean +``` + +**Default:** `false` + +**Platform:** Android Only + +:::caution Deprecated +This prop is deprecated. Use the `statusBar` prop instead: +```tsx + +``` +::: + +Determines whether your modal should go under the system status bar. diff --git a/docs/docs/contribution.md b/docs/docs/contribution.md new file mode 100644 index 0000000..a5a30c7 --- /dev/null +++ b/docs/docs/contribution.md @@ -0,0 +1,182 @@ +--- +sidebar_position: 6 +--- + +# Contribution + +Thank you for your interest in contributing to React Native Multiple Modals! This guide will help you get started. + +## 🐛 Found a Bug? Help the Project and Report It! + +If you notice any bugs or anything working differently compared to React Native, feel free to open an issue. It'll really help improve the project 🙏. + +### How to Report a Bug + +1. **Search existing issues** - Check if someone has already reported the issue +2. **Create a detailed report** - Include: + - Clear description of the bug + - Steps to reproduce + - Expected behavior vs actual behavior + - Screenshots or videos if applicable + - Environment details (React Native version, platform, device) + - Minimal code sample to reproduce + +**Report bugs here:** [GitHub Issues](https://github.com/paufau/react-native-multiple-modals/issues/new) + +--- + +## 💡 Feature Requests + +### Still Missing Something? + +I would love if you would let me know what you are missing in the library. _Together we can make it a community standard!_ + +When requesting a feature: +- Explain the use case and why it's needed +- Provide examples of how you'd like to use it +- Consider if it fits the scope of the library +- Check if it can be achieved with existing props + +**Submit feature requests:** [GitHub Issues](https://github.com/paufau/react-native-multiple-modals/issues/new) + +--- + +## 🔧 Developing & Testing + +Want to contribute code? Here's how to set up the development environment. + +### Setup + +Follow the instructions in the examples repository: +[react-native-multiple-modals-examples](https://github.com/paufau/react-native-multiple-modals-examples) + +This repository contains: +- Development setup +- Testing environment +- Example implementations +- Integration tests + +### Development Workflow + +1. **Fork the repository** +2. **Clone your fork:** + ```bash + git clone https://github.com/YOUR_USERNAME/react-native-multiple-modals.git + cd react-native-multiple-modals + ``` + +3. **Install dependencies:** + ```bash + npm install + ``` + +4. **Make your changes** + +5. **Lint your code:** + ```bash + npm run lint + ``` + +6. **Type check:** + ```bash + npm run typecheck + ``` + +7. **Build:** + ```bash + npm run build + ``` + +8. **Test your changes** using the examples repository + +--- + +## 📝 Contributing Code + +### Guidelines + +- **Code Style:** Follow the existing code style and conventions +- **TypeScript:** Write type-safe code with proper type definitions +- **Documentation:** Update documentation for any API changes +- **Tests:** Add tests if applicable (see examples repository) +- **Commit Messages:** Write clear, descriptive commit messages +- **Pull Requests:** + - Keep PRs focused on a single change + - Describe what changed and why + - Link to relevant issues + +### Pull Request Process + +1. Create a feature branch from `main` +2. Make your changes +3. Ensure all checks pass (lint, typecheck, build) +4. Push to your fork +5. Open a Pull Request with a clear description + +--- + +## 📖 Contributing to Documentation + +Documentation improvements are always welcome! This includes: +- Fixing typos or unclear explanations +- Adding examples +- Improving organization +- Translating content + +The documentation is built with [Docusaurus](https://docusaurus.io/) and located in the `docs/` directory. + +To run the documentation locally: + +```bash +cd docs +npm install +npm start +``` + +--- + +## 🎯 Areas We Need Help With + +- **Platform Testing:** Testing on different devices and OS versions +- **Performance Optimization:** Identifying and fixing performance bottlenecks +- **Accessibility:** Improving accessibility support +- **Documentation:** Improving docs and adding examples +- **Bug Fixes:** Fixing reported issues +- **Code Quality:** Refactoring and improving code structure + +--- + +## 💬 Communication + +- **GitHub Issues:** For bugs and feature requests +- **Pull Requests:** For code contributions +- **GitHub Discussions:** For questions and general discussions + +--- + +## 📜 Code of Conduct + +Please be respectful and constructive in all interactions. We're all here to make this library better! + +--- + +## 🙏 Recognition + +All contributors will be recognized in the project. Thank you for making React Native Multiple Modals better! + +--- + +## 📬 Contact + +- **Maintainer:** [Pavel Pakseev](https://www.linkedin.com/in/pavel-pakseev/) +- **GitHub:** [@paufau](https://github.com/paufau) + +--- + +## ☕ Support the Project + +If you find this library useful, you can support the development: + + + Buy Me a Coffee at ko-fi.com + diff --git a/docs/docs/installation.md b/docs/docs/installation.md new file mode 100644 index 0000000..2837c7e --- /dev/null +++ b/docs/docs/installation.md @@ -0,0 +1,71 @@ +--- +sidebar_position: 2 +--- + +# Installation + +## Prerequisites + +Before installing, make sure you have: +- React Native version 0.71.0 or higher +- React version 18 or higher + +## Using npm + +```bash +npm i react-native-multiple-modals +``` + +## Using yarn + +```bash +yarn add react-native-multiple-modals +``` + +## iOS Setup + +After installing the package, you need to install the iOS native dependencies: + +```bash +pod install --project-directory=ios +``` + +Or if you're in your iOS directory: + +```bash +cd ios +pod install +cd .. +``` + +## Android Setup + +For Android, the native dependencies are automatically linked. No additional setup is required. + +## Web Setup + +For web projects, make sure you have `react-dom` installed: + +```bash +npm i react-dom +``` + +or + +```bash +yarn add react-dom +``` + +## Verifying Installation + +To verify that the installation was successful, try importing the component in your code: + +```tsx +import { ModalView } from 'react-native-multiple-modals'; +``` + +If no errors appear, you're ready to start using the library! + +## Next Steps + +Check out the [Usage](./usage.md) guide to learn how to use the library in your application. diff --git a/docs/docs/intro.md b/docs/docs/intro.md new file mode 100644 index 0000000..32b3830 --- /dev/null +++ b/docs/docs/intro.md @@ -0,0 +1,68 @@ +--- +sidebar_position: 1 +slug: /intro +--- + +# Introduction + +[![NPM Version](https://img.shields.io/npm/v/react-native-multiple-modals)](https://www.npmjs.com/package/react-native-multiple-modals) +![Static Badge](https://img.shields.io/badge/types-included-81B622) +![Static Badge](https://img.shields.io/badge/platforms-iOS%2C_Android%2C_Web-7a34eb) +[![NPM Downloads](https://img.shields.io/npm/dm/react-native-multiple-modals)](https://www.npmjs.com/package/react-native-multiple-modals) + +**React Native Multiple Modals** is a Native Modal implementation which allows to display multiple Modals simultaneously. + +## ✨ Features + +- 🚀 **Multiple Instances** - Shows multiple modal instances at the same time +- 💯 **Displays on top** - Works on top of default React Native modal +- 🆗 **Gesture Handler Support** - Supports gesture handler out of the box +- 🛠️ **Bottom Tabs Navigation** - Displays above bottom tabs navigation +- 📱 **Rotation Support** - Adjusts content when device is rotated +- 💥 **Enhanced Status Bar** - Enhanced status bar configuration +- ✅ **Accessibility** - Built-in accessibility support +- 🌐 **Web Support** - Works on web platforms + +## Why Use This Library? + +React Native's built-in Modal component doesn't support displaying multiple modals simultaneously. This library solves that problem by providing a native implementation that allows you to: + +- Stack multiple modals on top of each other +- Show modals from different parts of your app simultaneously +- Have better control over modal presentation and dismissal +- Maintain performance with native implementations + +## Quick Example + +```tsx +import { ModalView } from 'react-native-multiple-modals'; + +const YourComponent = () => { + const [isVisible, setVisibility] = useState(false); + + return ( + +