@umituz/react-native-onboarding 3.6.11 → 3.6.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-onboarding",
-  "version": "3.6.11",
+  "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

@@ -95,12 +95,32 @@ export interface OnboardingSlide {
 
   /**
    * Layout pattern for multiple background images
-   * 'grid' - Equal sized grid
+   * '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' | 'masonry' | 'collage';
+  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)

package/src/index.ts

@@ -69,9 +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 } from "./presentation/components/BackgroundImageCollage";
+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

@@ -4,48 +4,81 @@
  */
 
 import React, { useMemo } from "react";
-import { View, StyleSheet, Dimensions } from "react-native";
+import { View, StyleSheet } from "react-native";
 import { Image } from "expo-image";
-
-const { width: SCREEN_WIDTH, height: SCREEN_HEIGHT } = Dimensions.get("window");
-
-interface BackgroundImageCollageProps {
-  images: any[];
-  layout?: 'grid' | 'masonry' | 'collage';
+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;
 }
 
-interface ImageLayout {
-  source: any;
-  style: {
-    position: 'absolute';
-    top: number;
-    left: number;
-    width: number;
-    height: 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',
+  layout = "grid",
+  columns,
+  gap,
+  borderRadius,
+  opacity = 1,
 }) => {
+  const safeImages = ensureArray(images);
+
   const imageLayouts = useMemo(() => {
-    if (images.length === 0) return [];
+    if (safeImages.length === 0) return [];
+
+    const generator = getLayoutGenerator(layout);
+    const config: LayoutConfig = { columns, gap, borderRadius };
 
-    switch (layout) {
-      case 'grid':
-        return generateGridLayout(images);
-      case 'masonry':
-        return generateMasonryLayout(images);
-      case 'collage':
-        return generateCollageLayout(images);
-      default:
-        return generateGridLayout(images);
-    }
-  }, [images, layout]);
+    return generator(safeImages, config);
+  }, [safeImages, layout, columns, gap, borderRadius]);
+
+  if (imageLayouts.length === 0) {
+    return null;
+  }
 
   return (
-    <View style={StyleSheet.absoluteFill} pointerEvents="none">
+    <View style={[StyleSheet.absoluteFill, { opacity }]} pointerEvents="none">
       {imageLayouts.map((item, index) => (
         <Image
           key={index}
@@ -58,102 +91,3 @@ export const BackgroundImageCollage: React.FC<BackgroundImageCollageProps> = ({
     </View>
   );
 };
-
-const generateGridLayout = (images: any[]): ImageLayout[] => {
-  const count = images.length;
-  const cols = Math.ceil(Math.sqrt(count));
-  const rows = Math.ceil(count / cols);
-  const cellWidth = SCREEN_WIDTH / cols;
-  const cellHeight = SCREEN_HEIGHT / 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,
-        top: row * cellHeight,
-        width: cellWidth,
-        height: cellHeight,
-      },
-    };
-  });
-};
-
-const generateMasonryLayout = (images: any[]): ImageLayout[] => {
-  const cols = 3;
-  const colWidth = SCREEN_WIDTH / cols;
-  const columnHeights = new Array(cols).fill(0);
-
-  return images.map((source, _index) => {
-    const shortestCol = columnHeights.indexOf(Math.min(...columnHeights));
-    const height = colWidth * (0.7 + Math.random() * 0.6);
-    
-    const layout: ImageLayout = {
-      source,
-      style: {
-        position: 'absolute' as const,
-        left: shortestCol * colWidth,
-        top: columnHeights[shortestCol],
-        width: colWidth,
-        height,
-      },
-    };
-
-    columnHeights[shortestCol] += height;
-    return layout;
-  });
-};
-
-const generateCollageLayout = (images: any[]): ImageLayout[] => {
-  const layouts: ImageLayout[] = [];
-  const minSize = Math.min(SCREEN_WIDTH, SCREEN_HEIGHT) * 0.25;
-  const maxSize = Math.min(SCREEN_WIDTH, SCREEN_HEIGHT) * 0.45;
-
-  images.forEach((source, _index) => {
-    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) {
-        if (
-          left < existing.style.left + existing.style.width &&
-          left + size > existing.style.left &&
-          top < existing.style.top + existing.style.height &&
-          top + size > existing.style.top
-        ) {
-          overlaps = true;
-          break;
-        }
-      }
-
-      attempts++;
-    }
-
-    layouts.push({
-      source,
-      style: {
-        position: 'absolute' as const,
-        left,
-        top,
-        width: size,
-        height: size,
-      },
-    });
-  });
-
-  return layouts;
-};

package/src/presentation/components/OnboardingBackground.tsx

@@ -40,7 +40,10 @@ export const OnboardingBackground: React.FC<OnboardingBackgroundProps> = ({
       return (
         <BackgroundImageCollage
           images={currentSlide.backgroundImages}
-          layout={currentSlide.backgroundImagesLayout || 'grid'}
+          layout={currentSlide.backgroundImagesLayout || "grid"}
+          columns={currentSlide.backgroundImagesColumns}
+          gap={currentSlide.backgroundImagesGap}
+          borderRadius={currentSlide.backgroundImagesBorderRadius}
         />
       );
     }

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 (