@umituz/react-native-onboarding 3.6.10 → 3.6.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-onboarding",
-  "version": "3.6.10",
+  "version": "3.6.12",
   "description": "Advanced onboarding flow for React Native apps with personalization questions, theme-aware colors, animations, and customizable slides. SOLID, DRY, KISS principles applied.",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/domain/entities/OnboardingSlide.ts

@@ -86,6 +86,42 @@ export interface OnboardingSlide {
    */
   backgroundImage?: any;
 
+  /**
+   * Optional multiple background images (URLs or require paths)
+   * Displayed in a collage/grid pattern behind content
+   * If provided, takes precedence over single backgroundImage
+   */
+  backgroundImages?: any[];
+
+  /**
+   * Layout pattern for multiple background images
+   * 'grid' - Equal sized grid (auto columns)
+   * 'dense' - Dense grid with many small images (6 columns)
+   * 'masonry' - Pinterest-style masonry layout
+   * 'collage' - Random sizes and positions
+   * 'scattered' - Small randomly placed images
+   * 'tiles' - Fixed size tiles centered
+   * 'honeycomb' - Hexagonal pattern
+   * Default: 'grid'
+   */
+  backgroundImagesLayout?: 'grid' | 'dense' | 'masonry' | 'collage' | 'scattered' | 'tiles' | 'honeycomb';
+
+  /**
+   * Number of columns for grid-based layouts
+   * Only applies to: grid, dense, masonry, tiles
+   */
+  backgroundImagesColumns?: number;
+
+  /**
+   * Gap between images in pixels
+   */
+  backgroundImagesGap?: number;
+
+  /**
+   * Border radius for images
+   */
+  backgroundImagesBorderRadius?: number;
+
   /**
    * Optional background video (URL or require path)
    * Plays in loop behind content

package/src/index.ts

@@ -69,8 +69,16 @@ export { OnboardingScreen, type OnboardingScreenProps } from "./presentation/scr
 export { OnboardingHeader, type OnboardingHeaderProps } from "./presentation/components/OnboardingHeader";
 export { OnboardingFooter, type OnboardingFooterProps } from "./presentation/components/OnboardingFooter";
 export { OnboardingProvider, type OnboardingProviderProps, useOnboardingProvider } from "./presentation/providers/OnboardingProvider";
+export { BackgroundImageCollage, type CollageLayout, type BackgroundImageCollageProps } from "./presentation/components/BackgroundImageCollage";
 export type { OnboardingTheme, OnboardingColors } from "./presentation/types/OnboardingTheme";
 
+// =============================================================================
+// UTILITIES - Helper functions
+// =============================================================================
+
+export { ensureArray, safeIncludes, safeFilter } from "./infrastructure/utils/arrayUtils";
+export type { ImageLayoutItem, LayoutConfig } from "./infrastructure/utils/imageLayoutUtils";
+
 // Export OnboardingSlide component
 // Note: TypeScript doesn't allow exporting both a type and a value with the same name
 // The type is exported above as OnboardingSlide

package/src/infrastructure/utils/arrayUtils.ts

@@ -0,0 +1,28 @@
+/**
+ * Array Utilities
+ * Safe array operations for onboarding components
+ */
+
+/**
+ * Ensures the value is a valid array, returns empty array if not
+ */
+export const ensureArray = <T>(value: T[] | undefined | null): T[] => {
+  return Array.isArray(value) ? value : [];
+};
+
+/**
+ * Safe includes check that handles undefined/null values
+ */
+export const safeIncludes = <T>(array: T[] | undefined | null, item: T): boolean => {
+  return ensureArray(array).includes(item);
+};
+
+/**
+ * Safe filter that handles undefined/null values
+ */
+export const safeFilter = <T>(
+  array: T[] | undefined | null,
+  predicate: (item: T) => boolean,
+): T[] => {
+  return ensureArray(array).filter(predicate);
+};

package/src/infrastructure/utils/imageLayoutUtils.ts

@@ -0,0 +1,280 @@
+/**
+ * Image Layout Utilities
+ * Layout generators for BackgroundImageCollage component
+ */
+
+import { Dimensions } from "react-native";
+
+const { width: SCREEN_WIDTH, height: SCREEN_HEIGHT } = Dimensions.get("window");
+
+export interface ImageLayoutStyle {
+  position: "absolute";
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+  borderRadius?: number;
+}
+
+export interface ImageLayoutItem {
+  source: unknown;
+  style: ImageLayoutStyle;
+}
+
+export interface LayoutConfig {
+  columns?: number;
+  gap?: number;
+  borderRadius?: number;
+  randomizeSize?: boolean;
+}
+
+/**
+ * Generate a uniform grid layout
+ */
+export const generateGridLayout = (
+  images: unknown[],
+  config: LayoutConfig = {},
+): ImageLayoutItem[] => {
+  const { columns, gap = 0, borderRadius = 0 } = config;
+  const count = images.length;
+  const cols = columns ?? Math.ceil(Math.sqrt(count));
+  const rows = Math.ceil(count / cols);
+  const totalGapX = gap * (cols - 1);
+  const totalGapY = gap * (rows - 1);
+  const cellWidth = (SCREEN_WIDTH - totalGapX) / cols;
+  const cellHeight = (SCREEN_HEIGHT - totalGapY) / rows;
+
+  return images.map((source, index) => {
+    const col = index % cols;
+    const row = Math.floor(index / cols);
+
+    return {
+      source,
+      style: {
+        position: "absolute" as const,
+        left: col * (cellWidth + gap),
+        top: row * (cellHeight + gap),
+        width: cellWidth,
+        height: cellHeight,
+        borderRadius,
+      },
+    };
+  });
+};
+
+/**
+ * Generate a dense grid layout with many small images
+ */
+export const generateDenseGridLayout = (
+  images: unknown[],
+  config: LayoutConfig = {},
+): ImageLayoutItem[] => {
+  const { columns = 6, gap = 2, borderRadius = 4 } = config;
+  const count = images.length;
+  const rows = Math.ceil(count / columns);
+  const totalGapX = gap * (columns - 1);
+  const totalGapY = gap * (rows - 1);
+  const cellWidth = (SCREEN_WIDTH - totalGapX) / columns;
+  const cellHeight = (SCREEN_HEIGHT - totalGapY) / rows;
+
+  return images.map((source, index) => {
+    const col = index % columns;
+    const row = Math.floor(index / columns);
+
+    return {
+      source,
+      style: {
+        position: "absolute" as const,
+        left: col * (cellWidth + gap),
+        top: row * (cellHeight + gap),
+        width: cellWidth,
+        height: cellHeight,
+        borderRadius,
+      },
+    };
+  });
+};
+
+/**
+ * Generate a masonry-style layout (Pinterest-like)
+ */
+export const generateMasonryLayout = (
+  images: unknown[],
+  config: LayoutConfig = {},
+): ImageLayoutItem[] => {
+  const { columns = 3, gap = 2, borderRadius = 4 } = config;
+  const colWidth = (SCREEN_WIDTH - gap * (columns - 1)) / columns;
+  const columnHeights = new Array(columns).fill(0);
+
+  return images.map((source) => {
+    const shortestCol = columnHeights.indexOf(Math.min(...columnHeights));
+    const aspectRatio = 0.7 + Math.random() * 0.6;
+    const height = colWidth * aspectRatio;
+
+    const layout: ImageLayoutItem = {
+      source,
+      style: {
+        position: "absolute" as const,
+        left: shortestCol * (colWidth + gap),
+        top: columnHeights[shortestCol],
+        width: colWidth,
+        height,
+        borderRadius,
+      },
+    };
+
+    columnHeights[shortestCol] += height + gap;
+    return layout;
+  });
+};
+
+/**
+ * Generate a random collage layout with varying sizes
+ */
+export const generateCollageLayout = (
+  images: unknown[],
+  config: LayoutConfig = {},
+): ImageLayoutItem[] => {
+  const { borderRadius = 8 } = config;
+  const layouts: ImageLayoutItem[] = [];
+  const minSize = Math.min(SCREEN_WIDTH, SCREEN_HEIGHT) * 0.15;
+  const maxSize = Math.min(SCREEN_WIDTH, SCREEN_HEIGHT) * 0.35;
+
+  images.forEach((source) => {
+    const size = minSize + Math.random() * (maxSize - minSize);
+    const maxX = SCREEN_WIDTH - size;
+    const maxY = SCREEN_HEIGHT - size;
+
+    let attempts = 0;
+    let overlaps = true;
+    let left = 0;
+    let top = 0;
+
+    while (overlaps && attempts < 50) {
+      left = Math.random() * maxX;
+      top = Math.random() * maxY;
+      overlaps = false;
+
+      for (const existing of layouts) {
+        const overlapThreshold = 20;
+        if (
+          left < existing.style.left + existing.style.width - overlapThreshold &&
+          left + size > existing.style.left + overlapThreshold &&
+          top < existing.style.top + existing.style.height - overlapThreshold &&
+          top + size > existing.style.top + overlapThreshold
+        ) {
+          overlaps = true;
+          break;
+        }
+      }
+
+      attempts++;
+    }
+
+    layouts.push({
+      source,
+      style: {
+        position: "absolute" as const,
+        left,
+        top,
+        width: size,
+        height: size,
+        borderRadius,
+      },
+    });
+  });
+
+  return layouts;
+};
+
+/**
+ * Generate a scattered layout with small images
+ */
+export const generateScatteredLayout = (
+  images: unknown[],
+  config: LayoutConfig = {},
+): ImageLayoutItem[] => {
+  const { borderRadius = 6 } = config;
+  const minSize = 60;
+  const maxSize = 100;
+
+  return images.map((source) => {
+    const size = minSize + Math.random() * (maxSize - minSize);
+    const left = Math.random() * (SCREEN_WIDTH - size);
+    const top = Math.random() * (SCREEN_HEIGHT - size);
+
+    return {
+      source,
+      style: {
+        position: "absolute" as const,
+        left,
+        top,
+        width: size,
+        height: size,
+        borderRadius,
+      },
+    };
+  });
+};
+
+/**
+ * Generate a tiles layout with fixed small size
+ */
+export const generateTilesLayout = (
+  images: unknown[],
+  config: LayoutConfig = {},
+): ImageLayoutItem[] => {
+  const { columns = 5, gap = 4, borderRadius = 8 } = config;
+  const tileSize = (SCREEN_WIDTH - gap * (columns + 1)) / columns;
+  const rows = Math.ceil(images.length / columns);
+  const startY = (SCREEN_HEIGHT - rows * (tileSize + gap)) / 2;
+
+  return images.map((source, index) => {
+    const col = index % columns;
+    const row = Math.floor(index / columns);
+
+    return {
+      source,
+      style: {
+        position: "absolute" as const,
+        left: gap + col * (tileSize + gap),
+        top: startY + row * (tileSize + gap),
+        width: tileSize,
+        height: tileSize,
+        borderRadius,
+      },
+    };
+  });
+};
+
+/**
+ * Generate a honeycomb/hex layout
+ */
+export const generateHoneycombLayout = (
+  images: unknown[],
+  config: LayoutConfig = {},
+): ImageLayoutItem[] => {
+  const { borderRadius = 50 } = config;
+  const size = 80;
+  const horizontalSpacing = size * 0.85;
+  const verticalSpacing = size * 0.75;
+  const columns = Math.floor(SCREEN_WIDTH / horizontalSpacing);
+
+  return images.map((source, index) => {
+    const row = Math.floor(index / columns);
+    const col = index % columns;
+    const offsetX = row % 2 === 1 ? horizontalSpacing / 2 : 0;
+
+    return {
+      source,
+      style: {
+        position: "absolute" as const,
+        left: col * horizontalSpacing + offsetX,
+        top: row * verticalSpacing,
+        width: size,
+        height: size,
+        borderRadius,
+      },
+    };
+  });
+};

package/src/presentation/components/BackgroundImageCollage.tsx

@@ -0,0 +1,93 @@
+/**
+ * Background Image Collage Component
+ * Displays multiple images in various layout patterns
+ */
+
+import React, { useMemo } from "react";
+import { View, StyleSheet } from "react-native";
+import { Image } from "expo-image";
+import {
+  generateGridLayout,
+  generateDenseGridLayout,
+  generateMasonryLayout,
+  generateCollageLayout,
+  generateScatteredLayout,
+  generateTilesLayout,
+  generateHoneycombLayout,
+  type ImageLayoutItem,
+  type LayoutConfig,
+} from "../../infrastructure/utils/imageLayoutUtils";
+import { ensureArray } from "../../infrastructure/utils/arrayUtils";
+
+export type CollageLayout =
+  | "grid"
+  | "dense"
+  | "masonry"
+  | "collage"
+  | "scattered"
+  | "tiles"
+  | "honeycomb";
+
+export interface BackgroundImageCollageProps {
+  images: unknown[];
+  layout?: CollageLayout;
+  columns?: number;
+  gap?: number;
+  borderRadius?: number;
+  opacity?: number;
+}
+
+const getLayoutGenerator = (layout: CollageLayout) => {
+  const generators: Record<
+    CollageLayout,
+    (images: unknown[], config: LayoutConfig) => ImageLayoutItem[]
+  > = {
+    grid: generateGridLayout,
+    dense: generateDenseGridLayout,
+    masonry: generateMasonryLayout,
+    collage: generateCollageLayout,
+    scattered: generateScatteredLayout,
+    tiles: generateTilesLayout,
+    honeycomb: generateHoneycombLayout,
+  };
+
+  return generators[layout] ?? generateGridLayout;
+};
+
+export const BackgroundImageCollage: React.FC<BackgroundImageCollageProps> = ({
+  images,
+  layout = "grid",
+  columns,
+  gap,
+  borderRadius,
+  opacity = 1,
+}) => {
+  const safeImages = ensureArray(images);
+
+  const imageLayouts = useMemo(() => {
+    if (safeImages.length === 0) return [];
+
+    const generator = getLayoutGenerator(layout);
+    const config: LayoutConfig = { columns, gap, borderRadius };
+
+    return generator(safeImages, config);
+  }, [safeImages, layout, columns, gap, borderRadius]);
+
+  if (imageLayouts.length === 0) {
+    return null;
+  }
+
+  return (
+    <View style={[StyleSheet.absoluteFill, { opacity }]} pointerEvents="none">
+      {imageLayouts.map((item, index) => (
+        <Image
+          key={index}
+          source={item.source}
+          style={item.style}
+          contentFit="cover"
+          transition={300}
+        />
+      ))}
+    </View>
+  );
+};

package/src/presentation/components/OnboardingBackground.tsx

@@ -9,6 +9,7 @@ import { LinearGradient } from "expo-linear-gradient";
 import { Image } from "expo-image";
 import type { OnboardingSlide } from "../../domain/entities/OnboardingSlide";
 import { BackgroundVideo } from "./BackgroundVideo";
+import { BackgroundImageCollage } from "./BackgroundImageCollage";
 
 interface OnboardingBackgroundProps {
   currentSlide: OnboardingSlide | undefined;
@@ -35,6 +36,18 @@ export const OnboardingBackground: React.FC<OnboardingBackgroundProps> = ({
       );
     }
 
+    if (currentSlide.backgroundImages && currentSlide.backgroundImages.length > 0) {
+      return (
+        <BackgroundImageCollage
+          images={currentSlide.backgroundImages}
+          layout={currentSlide.backgroundImagesLayout || "grid"}
+          columns={currentSlide.backgroundImagesColumns}
+          gap={currentSlide.backgroundImagesGap}
+          borderRadius={currentSlide.backgroundImagesBorderRadius}
+        />
+      );
+    }
+
     if (currentSlide.backgroundImage) {
       return (
         <Image

package/src/presentation/components/OnboardingScreenContent.tsx

@@ -53,7 +53,9 @@ export const OnboardingScreenContent = ({
   });
 
   const hasMedia =
-    !!currentSlide?.backgroundImage || !!currentSlide?.backgroundVideo;
+    !!currentSlide?.backgroundImage || 
+    !!currentSlide?.backgroundVideo ||
+    (!!currentSlide?.backgroundImages && currentSlide.backgroundImages.length > 0);
   const overlayOpacity = currentSlide?.overlayOpacity ?? 0.5;
   const effectivelyUseGradient = useGradient || hasMedia;
 

package/src/presentation/components/questions/MultipleChoiceQuestion.tsx

@@ -2,6 +2,7 @@ import React from "react";
 import { View, TouchableOpacity, StyleSheet } from "react-native";
 import { AtomicIcon, AtomicText } from "@umituz/react-native-design-system";
 import { useOnboardingProvider } from "../../providers/OnboardingProvider";
+import { ensureArray } from "../../../infrastructure/utils/arrayUtils";
 import type { OnboardingQuestion, QuestionOption } from "../../../domain/entities/OnboardingQuestion";
 
 export interface MultipleChoiceQuestionProps {
@@ -12,17 +13,19 @@ export interface MultipleChoiceQuestionProps {
 
 export const MultipleChoiceQuestion = ({
   question,
-  value = [],
+  value,
   onChange,
 }: MultipleChoiceQuestionProps) => {
   const {
     theme: { colors },
   } = useOnboardingProvider();
 
+  const safeValue = ensureArray(value);
+
   const handleToggle = (optionId: string) => {
-    const newValue = value.includes(optionId)
-      ? value.filter((id) => id !== optionId)
-      : [...value, optionId];
+    const newValue = safeValue.includes(optionId)
+      ? safeValue.filter((id) => id !== optionId)
+      : [...safeValue, optionId];
 
     if (question.validation?.maxSelections && newValue.length > question.validation.maxSelections) {
       return;
@@ -30,7 +33,7 @@ export const MultipleChoiceQuestion = ({
     onChange(newValue);
   };
   const renderOption = (option: QuestionOption) => {
-    const isSelected = value.includes(option.id);
+    const isSelected = safeValue.includes(option.id);
     const isEmoji = option.iconType === 'emoji';
 
     return (