@rubixscript/react-native-onboarding 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 RubixScript Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,383 @@
+# @rubixscript/react-native-onboarding
+
+A comprehensive React Native onboarding library with customizable slide types, animations, and themes. Built for React Native 0.70+ with Expo.
+
+## Features
+
+- **Multiple Slide Types**: Image, Icon, Form, Video, and Custom slides
+- **Pre-built Themes**: onepage, zaprecipe, pomodo, modern, minimal, gradient presets
+- **Customizable Navigation**: Dots, progress bar, steps, numbers, or no pagination
+- **Smooth Animations**: Slide, fade, scale, parallax transitions with react-native-reanimated
+- **Storage Integration**: AsyncStorage persistence for onboarding completion
+- **Form Support**: Built-in form validation and data collection
+- **Dark Mode**: Full dark mode support
+- **TypeScript**: Fully typed for better developer experience
+
+## Installation
+
+```bash
+npm install @rubixscript/react-native-onboarding
+# or
+yarn add @rubixscript/react-native-onboarding
+```
+
+### Peer Dependencies
+
+Ensure you have these installed:
+
+```bash
+npm install react-native-reanimated @react-native-async-storage/async-storage expo-linear-gradient expo-blur @expo/vector-icons
+```
+
+## Quick Start
+
+### Basic Usage
+
+```tsx
+import React, { useState } from 'react';
+import { View } from 'react-native';
+import { Onboarding, useOnboarding } from '@rubixscript/react-native-onboarding';
+
+const App = () => {
+  const { hasCompletedOnboarding, isLoading } = useOnboarding('@myapp:onboarding_complete');
+  const [showOnboarding, setShowOnboarding] = useState(!hasCompletedOnboarding);
+
+  if (isLoading) return null;
+
+  return (
+    <>
+      {showOnboarding ? (
+        <Onboarding
+          visible={showOnboarding}
+          slides={mySlides}
+          onboardingComplete={(data) => {
+            setShowOnboarding(false);
+            console.log('Onboarding data:', data);
+          }}
+        />
+      ) : (
+        <YourMainApp />
+      )}
+    </>
+  );
+};
+```
+
+### Using Presets
+
+```tsx
+import { Onboarding } from '@rubixscript/react-native-onboarding';
+import { onepageConfig, onepagePreset } from '@rubixscript/react-native-onboarding/presets';
+
+// Use a complete preset
+<Onboarding
+  visible={true}
+  {...onepageConfig}
+  theme={onepagePreset.theme}
+  navigation={onepagePreset.navigation}
+  animation={onepagePreset.animation}
+  onboardingComplete={() => console.log('Done!')}
+/>
+
+// Or just use the theme with custom slides
+<Onboarding
+  visible={true}
+  slides={myCustomSlides}
+  theme={onepagePreset.theme}
+  onboardingComplete={() => console.log('Done!')}
+/>
+```
+
+## Slide Types
+
+### Image Slide
+
+```tsx
+{
+  id: 'welcome',
+  type: 'image',
+  title: 'Welcome',
+  description: 'Your description here',
+  image: require('./assets/welcome.png'),
+  imageResizeMode: 'cover',
+  gradientColors: ['#667EEA', '#764BA2'],
+  overlayIcon: {
+    name: 'heart',
+    size: 40,
+    color: '#FFFFFF'
+  }
+}
+```
+
+### Icon Slide
+
+```tsx
+{
+  id: 'features',
+  type: 'icon',
+  title: 'Powerful Features',
+  description: 'Discover what we offer',
+  icon: {
+    name: 'rocket',
+    type: 'ionicons', // or 'material', 'material-community', 'font-awesome', 'octicons', 'feather'
+    size: 64,
+    color: '#FFFFFF',
+    backgroundColor: '#8B5CF6',
+    backgroundSize: 160
+  },
+  backgroundColor: '#F6F6F6'
+}
+```
+
+### Form Slide
+
+```tsx
+{
+  id: 'profile',
+  type: 'form',
+  title: 'Tell us about yourself',
+  description: 'We\'ll personalize your experience',
+  fields: [
+    {
+      key: 'name',
+      label: 'Your Name',
+      placeholder: 'Enter your name',
+      type: 'text',
+      required: true
+    },
+    {
+      key: 'level',
+      label: 'Experience Level',
+      placeholder: 'Select level',
+      type: 'select',
+      required: true,
+      options: [
+        { value: 'beginner', label: 'Beginner', icon: 'leaf' },
+        { value: 'advanced', label: 'Advanced', icon: 'star' }
+      ]
+    }
+  ],
+  submitLabel: 'Get Started',
+  onSubmit: async (data) => {
+    console.log('Form data:', data);
+    // Save to backend, etc.
+  }
+}
+```
+
+### Video Slide
+
+```tsx
+{
+  id: 'intro',
+  type: 'video',
+  title: 'Watch Our Story',
+  description: 'A quick introduction',
+  videoSource: require('./assets/intro.mp4'),
+  autoPlay: true,
+  loop: true,
+  muted: true,
+  poster: require('./assets/poster.png')
+}
+```
+
+## Customization
+
+### Theme
+
+```tsx
+import { mergeTheme, modernTheme } from '@rubixscript/react-native-onboarding';
+
+const customTheme = mergeTheme(modernTheme, {
+  colors: {
+    primary: '#FF6B6B',
+    secondary: '#4ECDC4',
+  },
+  typography: {
+    title: {
+      fontSize: 32,
+      fontWeight: '800',
+    }
+  }
+});
+
+<Onboarding theme={customTheme} {...otherProps} />
+```
+
+### Navigation
+
+```tsx
+<Onboarding
+  navigation={{
+    style: 'dots', // 'dots' | 'progress-bar' | 'steps' | 'numbers' | 'none'
+    position: 'bottom', // 'top' | 'bottom' | 'floating'
+    showSkip: true,
+    showBack: true,
+    skipLabel: 'Skip',
+    backLabel: 'Back',
+    nextLabel: 'Continue',
+    doneLabel: 'Get Started',
+  }}
+  {...otherProps}
+/>
+```
+
+### Animation
+
+```tsx
+<Onboarding
+  animation={{
+    type: 'slide', // 'slide' | 'fade' | 'scale' | 'parallax' | 'cube' | 'none'
+    duration: 300,
+    parallaxFactor: 0.3
+  }}
+  {...otherProps}
+/>
+```
+
+### Storage
+
+```tsx
+<Onboarding
+  storage={{
+    key: '@myapp:onboarding_complete',
+    enabled: true,
+    onComplete: async () => {
+      // Called after saving completion status
+      console.log('Onboarding saved!');
+    }
+  }}
+  {...otherProps}
+/>
+```
+
+## Hooks
+
+### useOnboarding
+
+```tsx
+import { useOnboarding } from '@rubixscript/react-native-onboarding';
+
+const MyComponent = () => {
+  const {
+    hasCompletedOnboarding, // boolean | null
+    isLoading, // boolean
+    markComplete, // () => Promise<void>
+    reset // () => Promise<void>
+  } = useOnboarding('@myapp:onboarding_key');
+
+  if (isLoading) return <LoadingScreen />;
+
+  return hasCompletedOnboarding ? <App /> : <Onboarding ... />;
+};
+```
+
+## Available Presets
+
+| Preset | Style | Best For |
+|--------|-------|----------|
+| `onepage` | Gradient backgrounds, images, forms | Reading apps, content apps |
+| `zaprecipe` | Rich images, overlay icons, gradients | Lifestyle, food, travel apps |
+| `pomodo` | Clean icons, minimal design | Productivity, utility apps |
+| `modern` | Contemporary, rounded, vibrant | Modern consumer apps |
+| `minimal` | Simple, monochrome, clean | Professional, business apps |
+| `gradient` | Full-screen gradients, immersive | Creative, artistic apps |
+
+## Integration Examples
+
+### Expo Router
+
+```tsx
+// app/onboarding.tsx
+import { View } from 'react-native';
+import { Onboarding } from '@rubixscript/react-native-onboarding';
+import { router } from 'expo-router';
+import { onepageConfig } from '@rubixscript/react-native-onboarding/presets';
+
+export default function OnboardingScreen() {
+  return (
+    <Onboarding
+      visible={true}
+      {...onepageConfig}
+      onboardingComplete={() => router.replace('/(tabs)')}
+    />
+  );
+}
+
+// app/_layout.tsx
+import { useOnboarding } from '@rubixscript/react-native-onboarding';
+import { router } from 'expo-router';
+
+export default function Layout() {
+  const { hasCompletedOnboarding, isLoading } = useOnboarding();
+
+  useEffect(() => {
+    if (!isLoading && !hasCompletedOnboarding) {
+      router.replace('/onboarding');
+    }
+  }, [hasCompletedOnboarding, isLoading]);
+
+  return <Slot />;
+}
+```
+
+### React Navigation
+
+```tsx
+import { Onboarding, useOnboarding } from '@rubixscript/react-native-onboarding';
+
+const OnboardingScreen = ({ navigation }: any) => (
+  <Onboarding
+    visible={true}
+    slides={slides}
+    onboardingComplete={() => navigation.navigate('Home')}
+  />
+);
+
+const RootNavigator = () => {
+  const { hasCompletedOnboarding, isLoading } = useOnboarding();
+
+  if (isLoading) return null;
+
+  return (
+    <Stack.Navigator screenOptions={{ headerShown: false }}>
+      {!hasCompletedOnboarding && (
+        <Stack.Screen name="Onboarding" component={OnboardingScreen} />
+      )}
+      <Stack.Screen name="Home" component={HomeScreen} />
+    </Stack.Navigator>
+  );
+};
+```
+
+## API Reference
+
+### Onboarding Component
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `visible` | `boolean` | *required* | Controls visibility of onboarding |
+| `slides` | `SlideData[]` | `[]` | Array of slide configurations |
+| `theme` | `Partial<OnboardingTheme>` | `modernTheme` | Custom theme configuration |
+| `navigation` | `Partial<NavigationConfig>` | See below | Navigation options |
+| `animation` | `Partial<AnimationConfig>` | See below | Animation settings |
+| `storage` | `Partial<StorageConfig>` | See below | AsyncStorage configuration |
+| `onboardingComplete` | `(data?) => void \| Promise<void>` | - | Called when onboarding completes |
+| `onSlideChange` | `(index: number) => void` | - | Called on slide change |
+| `onSkip` | `() => void \| Promise<void>` | - | Called when user skips |
+| `initialSlide` | `number` | `0` | Starting slide index |
+| `swipeEnabled` | `boolean` | `true` | Enable swipe navigation |
+| `safeAreaEnabled` | `boolean` | `true` | Use SafeAreaView |
+| `darkMode` | `boolean` | `false` | Enable dark mode styling |
+
+## License
+
+MIT
+
+## Author
+
+RubixScript Team
+
+---
+
+For more examples and updates, visit [GitHub](https://github.com/rubixscript/react-native-onboarding).

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@rubixscript/react-native-onboarding",
+  "version": "1.0.0",
+  "description": "A comprehensive React Native onboarding library with customizable slide types, animations, and themes",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "scripts": {
+    "test": "jest",
+    "lint": "eslint src --ext .ts,.tsx",
+    "type-check": "tsc --noEmit"
+  },
+  "keywords": [
+    "react-native",
+    "onboarding",
+    "walkthrough",
+    "tutorial",
+    "user-onboarding",
+    "expo",
+    "react",
+    "slides",
+    "carousel"
+  ],
+  "author": "RubixScript Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rubixscript/react-native-onboarding.git"
+  },
+  "peerDependencies": {
+    "expo": ">=48.0.0",
+    "react": ">=18.0.0",
+    "react-native": ">=0.70.0",
+    "react-native-reanimated": ">=3.0.0"
+  },
+  "dependencies": {
+    "@expo/vector-icons": "^15.0.2",
+    "@react-native-async-storage/async-storage": ">=1.19.0",
+    "expo-blur": "~15.0.7",
+    "expo-linear-gradient": "~15.0.7"
+  },
+  "devDependencies": {
+    "@testing-library/react-native": "^12.0.0",
+    "@types/jest": "^29.5.0",
+    "@types/react": "~19.1.10",
+    "@types/react-native": "^0.73.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "eslint": "^8.0.0",
+    "jest": "^29.0.0",
+    "typescript": "~5.9.2"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}

package/src/components/NavigationButtons.tsx

@@ -0,0 +1,198 @@
+import React, { useMemo } from 'react';
+import { View, Text, TouchableOpacity, StyleSheet, ActivityIndicator, ViewStyle, TextStyle, Platform } from 'react-native';
+import { BlurView } from 'expo-blur';
+import { LinearGradient } from 'expo-linear-gradient';
+import Animated, { FadeIn, FadeOut } from 'react-native-reanimated';
+import { Ionicons } from '@expo/vector-icons';
+import { NavigationButtonProps } from '../types';
+
+const AnimatedTouchableOpacity = Animated.createAnimatedComponent(TouchableOpacity);
+
+export const NavigationButton: React.FC<NavigationButtonProps> = ({
+  label,
+  onPress,
+  theme,
+  variant = 'primary',
+  disabled = false,
+  loading = false,
+  style,
+  textStyle,
+}) => {
+  const buttonStyle = useMemo(() => {
+    const base: ViewStyle = {
+      ...styles.button,
+      minHeight: 48,
+      paddingHorizontal: 24,
+      borderRadius: theme.borderRadius.full,
+      alignItems: 'center',
+      justifyContent: 'center',
+      flexDirection: 'row',
+    };
+
+    switch (variant) {
+      case 'primary':
+        base.backgroundColor = theme.colors.primary;
+        break;
+      case 'secondary':
+        base.backgroundColor = theme.colors.secondary;
+        break;
+      case 'ghost':
+        base.backgroundColor = 'transparent';
+        base.borderWidth = 1.5;
+        base.borderColor = theme.colors.border;
+        break;
+    }
+
+    return base;
+  }, [theme, variant]);
+
+  const buttonText = useMemo(() => {
+    const base: TextStyle = {
+      ...styles.buttonText,
+      color: variant === 'ghost' ? theme.colors.text.primary : theme.colors.text.inverse,
+    };
+
+    return base;
+  }, [theme, variant]);
+
+  return (
+    <AnimatedTouchableOpacity
+      style={[buttonStyle, style]}
+      onPress={onPress}
+      disabled={disabled || loading}
+      activeOpacity={0.8}
+      entering={FadeIn}
+      exiting={FadeOut}
+    >
+      {loading ? (
+        <ActivityIndicator color={variant === 'ghost' ? theme.colors.text.primary : theme.colors.text.inverse} />
+      ) : (
+        <Text style={[buttonText, textStyle]}>{label}</Text>
+      )}
+    </AnimatedTouchableOpacity>
+  );
+};
+
+interface NavigationButtonsProps {
+  currentIndex: number;
+  totalSlides: number;
+  theme: any;
+  config: any;
+  onNext: () => void;
+  onBack: () => void;
+  onSkip: () => void;
+  canGoNext?: boolean;
+  isLastSlide?: boolean;
+  isLoading?: boolean;
+  darkMode?: boolean;
+}
+
+export const NavigationButtons: React.FC<NavigationButtonsProps> = ({
+  currentIndex,
+  totalSlides,
+  theme,
+  config,
+  onNext,
+  onBack,
+  onSkip,
+  canGoNext = true,
+  isLastSlide = false,
+  isLoading = false,
+  darkMode = false,
+}) => {
+  const { showSkip = true, showBack = true, skipLabel = 'Skip', backLabel = 'Back', nextLabel = 'Next', doneLabel = 'Get Started', position = 'bottom' } = config;
+
+  const containerStyle: ViewStyle = useMemo(() => {
+    const base: ViewStyle = {
+      paddingHorizontal: theme.spacing.lg,
+      paddingVertical: theme.spacing.md,
+      gap: theme.spacing.sm,
+    };
+
+    if (position === 'floating') {
+      base.position = 'absolute';
+      base.bottom = theme.spacing.xl;
+      base.left = theme.spacing.lg;
+      base.right = theme.spacing.lg;
+    }
+
+    return base;
+  }, [theme, position]);
+
+  const isAtStart = currentIndex === 0;
+
+  const buttons = (
+    <>
+      {/* Back Button */}
+      {showBack && !isAtStart && (
+        <NavigationButton
+          label={backLabel}
+          onPress={onBack}
+          theme={theme}
+          variant="ghost"
+        />
+      )}
+
+      {/* Skip Button */}
+      {showSkip && !isLastSlide && !isLoading && (
+        <TouchableOpacity
+          style={styles.skipButton}
+          onPress={onSkip}
+          activeOpacity={0.7}
+        >
+          <Text style={[styles.skipButtonText, { color: theme.colors.text.secondary }]}>
+            {skipLabel}
+          </Text>
+        </TouchableOpacity>
+      )}
+
+      {/* Next/Done Button */}
+      <NavigationButton
+        label={isLastSlide ? doneLabel : nextLabel}
+        onPress={onNext}
+        theme={theme}
+        variant="primary"
+        disabled={!canGoNext}
+        loading={isLoading}
+      />
+    </>
+  );
+
+  if (position === 'floating') {
+    return (
+      <BlurView intensity={80} tint={darkMode ? 'dark' : 'light'} style={containerStyle}>
+        <View style={styles.buttonRow}>{buttons}</View>
+      </BlurView>
+    );
+  }
+
+  return <View style={containerStyle}>{buttons}</View>;
+};
+
+const styles = StyleSheet.create({
+  button: {
+    minWidth: 120,
+  },
+  buttonText: {
+    fontSize: 16,
+    fontWeight: '600',
+    letterSpacing: 0.5,
+  },
+  buttonRow: {
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+  },
+  skipButton: {
+    alignSelf: 'flex-end',
+    paddingVertical: 8,
+    paddingHorizontal: 4,
+    marginRight: 8,
+  },
+  skipButtonText: {
+    fontSize: 15,
+    fontWeight: '500',
+  },
+});
+
+export default { NavigationButton, NavigationButtons };