@erquhart/heroui-native 1.0.0-beta.10.1

package/src/providers/hero-ui-native/provider.md

@@ -0,0 +1,332 @@
+# HeroUINativeProvider
+
+The `HeroUINativeProvider` is the root provider component that configures and initializes HeroUI Native in your React Native application. It provides global configuration and portal management for your application.
+
+## Overview
+
+The provider serves as the main entry point for HeroUI Native, wrapping your application with essential contexts and configurations:
+
+- **Safe Area Insets**: Automatically handles safe area insets updates via `SafeAreaListener` and syncs them with Uniwind for use in Tailwind classes (e.g., `pb-safe-offset-3`)
+- **Text Configuration**: Global text component settings for consistency across all HeroUI components
+- **Animation Configuration**: Global animation control to disable all animations across the application
+- **Toast Configuration**: Global toast system configuration including insets, default props, and wrapper components
+- **Portal Management**: Handles overlays, modals, and other components that render on top of the app hierarchy
+
+## Installation & Setup
+
+### Basic Setup
+
+Wrap your application root with the provider:
+
+```tsx
+import { HeroUINativeProvider } from 'heroui-native';
+
+export default function App() {
+  return <HeroUINativeProvider>{/* Your app content */}</HeroUINativeProvider>;
+}
+```
+
+### With Configuration
+
+```tsx
+import { HeroUINativeProvider } from 'heroui-native';
+
+export default function App() {
+  return (
+    <HeroUINativeProvider
+      config={{
+        textProps: {
+          maxFontSizeMultiplier: 1.5,
+        },
+      }}
+    >
+      {/* Your app content */}
+    </HeroUINativeProvider>
+  );
+}
+```
+
+## Configuration Options
+
+The provider accepts a `config` prop with the following options:
+
+### Text Component Configuration
+
+Global settings for all Text components within HeroUI Native. These props are carefully selected to include only those that make sense to configure globally across all Text components in the application:
+
+```tsx
+config={{
+  textProps: {
+    // Disable font scaling for accessibility
+    allowFontScaling: false,
+
+    // Auto-adjust font size to fit container
+    adjustsFontSizeToFit: false,
+
+    // Maximum font size multiplier when scaling
+    maxFontSizeMultiplier: 1.5,
+
+    // Minimum font scale (iOS only, 0.01-1.0)
+    minimumFontScale: 0.5,
+  },
+}}
+```
+
+### Animation Configuration
+
+Global animation configuration for the entire application:
+
+```tsx
+config={{
+  // Disable all animations across the application (cascades to all children)
+  animation: 'disable-all',
+}}
+```
+
+**Note**: When set to `'disable-all'`, all animations across the application will be disabled, including animations in child components. This is useful for accessibility or performance optimization.
+
+### Toast Configuration
+
+Configure the global toast system including insets, default props, and wrapper components:
+
+```tsx
+config={{
+  toast: {
+    // Global toast configuration (used as defaults for all toasts)
+    defaultProps: {
+      variant: 'default',
+      placement: 'top',
+      isSwipeable: true,
+      animation: true,
+    },
+    // Insets for spacing from screen edges (added to safe area insets)
+    insets: {
+      top: 0,      // Default: iOS = 0, Android = 12
+      bottom: 6,   // Default: iOS = 6, Android = 12
+      left: 12,    // Default: 12
+      right: 12,   // Default: 12
+    },
+    // Maximum number of visible toasts before opacity starts fading
+    maxVisibleToasts: 3,
+    // Custom wrapper function to wrap the toast content
+    contentWrapper: (children) => (
+      <KeyboardAvoidingView
+        behavior="padding"
+        keyboardVerticalOffset={24}
+        className="flex-1"
+      >
+        {children}
+      </KeyboardAvoidingView>
+    ),
+  },
+}}
+```
+
+## Architecture
+
+### Provider Hierarchy
+
+The `HeroUINativeProvider` internally composes multiple providers:
+
+```
+HeroUINativeProvider
+├── SafeAreaListener (handles safe area insets updates)
+│   └── GlobalAnimationSettingsProvider (animation configuration)
+│       └── TextComponentProvider (text configuration)
+│           └── ToastProvider (toast configuration)
+│               └── Your App
+│               └── PortalHost (for overlays)
+```
+
+### Safe Area Insets Handling
+
+The provider automatically wraps your application with [`SafeAreaListener`](https://appandflow.github.io/react-native-safe-area-context/api/safe-area-listener) from `react-native-safe-area-context`. This component listens to safe area insets and frame changes without triggering re-renders, and automatically updates Uniwind with the latest insets via the `onChange` callback.
+
+## Complete Example
+
+Here's a comprehensive example showing all configuration options:
+
+```tsx
+import { HeroUINativeProvider } from 'heroui-native';
+import type { HeroUINativeConfig } from 'heroui-native';
+
+const config: HeroUINativeConfig = {
+  // Global text configuration
+  textProps: {
+    minimumFontScale: 0.5,
+    maxFontSizeMultiplier: 1.5,
+    allowFontScaling: true,
+    adjustsFontSizeToFit: false,
+  },
+  // Global animation configuration
+  animation: 'disable-all', // Optional: disable all animations
+  // Global toast configuration
+  toast: {
+    defaultProps: {
+      variant: 'default',
+      placement: 'top',
+    },
+    insets: {
+      top: 0,
+      bottom: 6,
+      left: 12,
+      right: 12,
+    },
+    maxVisibleToasts: 3,
+  },
+};
+
+export default function App() {
+  return (
+    <HeroUINativeProvider config={config}>
+      <YourApp />
+    </HeroUINativeProvider>
+  );
+}
+```
+
+## Integration with Expo Router
+
+When using Expo Router, wrap your root layout:
+
+```tsx
+// app/_layout.tsx
+import { HeroUINativeProvider } from 'heroui-native';
+import { Stack } from 'expo-router';
+
+export default function RootLayout() {
+  return (
+    <HeroUINativeProvider
+      config={{
+        textProps: {
+          minimumFontScale: 0.5,
+          maxFontSizeMultiplier: 1.5,
+        },
+      }}
+    >
+      <Stack />
+    </HeroUINativeProvider>
+  );
+}
+```
+
+## Best Practices
+
+### 1. Single Provider Instance
+
+Always use a single `HeroUINativeProvider` at the root of your app. Don't nest multiple providers:
+
+```tsx
+// ❌ Bad
+<HeroUINativeProvider>
+  <SomeComponent>
+    <HeroUINativeProvider> {/* Don't do this */}
+      <AnotherComponent />
+    </HeroUINativeProvider>
+  </SomeComponent>
+</HeroUINativeProvider>
+
+// ✅ Good
+<HeroUINativeProvider>
+  <SomeComponent>
+    <AnotherComponent />
+  </SomeComponent>
+</HeroUINativeProvider>
+```
+
+### 2. Configuration Object
+
+Define your configuration outside the component to prevent recreating on each render:
+
+```tsx
+// ❌ Bad
+function App() {
+  return (
+    <HeroUINativeProvider
+      config={{
+        textProps: {
+          /* inline config */
+        },
+      }}
+    >
+      {/* ... */}
+    </HeroUINativeProvider>
+  );
+}
+
+// ✅ Good
+const config: HeroUINativeConfig = {
+  textProps: {
+    maxFontSizeMultiplier: 1.5,
+  },
+};
+
+function App() {
+  return (
+    <HeroUINativeProvider config={config}>{/* ... */}</HeroUINativeProvider>
+  );
+}
+```
+
+### 3. Text Configuration
+
+Consider accessibility when configuring text props:
+
+```tsx
+config={{
+  textProps: {
+    // Allow font scaling for accessibility
+    allowFontScaling: true,
+    // But limit maximum scale
+    maxFontSizeMultiplier: 1.5,
+  },
+}}
+```
+
+## TypeScript Support
+
+The provider is fully typed. Import types for better IDE support:
+
+```tsx
+import { HeroUINativeProvider, type HeroUINativeConfig } from 'heroui-native';
+
+const config: HeroUINativeConfig = {
+  // Full type safety and autocomplete
+  textProps: {
+    allowFontScaling: true,
+    maxFontSizeMultiplier: 1.5,
+  },
+  animation: 'disable-all', // Optional: disable all animations
+  toast: {
+    defaultProps: {
+      variant: 'default',
+      placement: 'top',
+    },
+    insets: {
+      top: 0,
+      bottom: 6,
+      left: 12,
+      right: 12,
+    },
+  },
+};
+```
+
+## Troubleshooting
+
+### Type Errors
+
+Ensure you're using the correct import paths:
+
+```tsx
+// ✅ Correct imports
+import { HeroUINativeProvider } from 'heroui-native';
+import type { HeroUINativeConfig } from 'heroui-native';
+
+// ❌ Incorrect (internal path)
+import { HeroUINativeProvider } from 'heroui-native/providers';
+```
+
+## See Also
+
+- [Component Documentation](../../components/README.md) - Using HeroUI Native components

package/src/providers/hero-ui-native/provider.tsx

@@ -0,0 +1,92 @@
+import React, { useEffect } from 'react';
+import { SafeAreaListener } from 'react-native-safe-area-context';
+import { Uniwind } from 'uniwind';
+import { PortalHost } from '../../primitives/portal';
+import { GlobalAnimationSettingsProvider } from '../animation-settings';
+import { TextComponentProvider } from '../text-component/provider';
+import { ToastProvider } from '../toast/provider';
+import type { HeroUINativeProviderProps } from './types';
+
+const LOG_COLOR = {
+  BLUE: '\x1b[34m',
+  RESET: '\x1b[0m',
+};
+
+/**
+ * HeroUINativeProvider Component
+ *
+ * @description
+ * Main provider component for HeroUI Native that configures the application
+ * with global settings. This component should wrap your entire application
+ * or the section where you want to use HeroUI Native components.
+ *
+ * Currently provides:
+ * - Global animation settings
+ * - Global text component configuration
+ * - Toast notification system
+ * - Portal management for overlays
+ *
+ * @param {HeroUINativeProviderProps} props - Provider configuration props
+ * @param {ReactNode} props.children - Child components to wrap
+ * @param {HeroUINativeConfig} [props.config] - Configuration object
+ *
+ */
+export const HeroUINativeProvider: React.FC<HeroUINativeProviderProps> = ({
+  children,
+  config = {},
+}) => {
+  const { textProps, toast, animation } = config;
+  const { ...toastProps } = toast || {};
+
+  useEffect(() => {
+    if (__DEV__) {
+      console.info(
+        `${LOG_COLOR.BLUE}HeroUI Native Styling Principles${LOG_COLOR.RESET}\n` +
+          `• className: this is your go-to styling solution. Use Tailwind CSS classes via className prop on all components.\n` +
+          `• StyleSheet precedence: The style prop (StyleSheet API) has precedence over className when both are provided. This allows you to override Tailwind classes when needed.\n` +
+          `• Animated styles: Some style properties are animated using react-native-reanimated and have precedence over className. To identify which styles are animated:\n` +
+          `  - Hover over className in your IDE - TypeScript definitions show which properties are occupied by animated styles\n` +
+          `  - Check component documentation - Each component page includes a link to the component's style source\n` +
+          `• If styles are occupied by animation, modify them via the animation prop on components that support it.\n` +
+          `• To deactivate animated style completely and apply your own styles, use isAnimatedStyleActive prop.`
+      );
+    }
+  }, []);
+
+  return (
+    <SafeAreaListener
+      onChange={({ insets }) => {
+        Uniwind.updateInsets(insets);
+      }}
+    >
+      <GlobalAnimationSettingsProvider animation={animation}>
+        <TextComponentProvider value={{ textProps }}>
+          <ToastProvider {...toastProps}>
+            {children}
+            <PortalHost />
+          </ToastProvider>
+        </TextComponentProvider>
+      </GlobalAnimationSettingsProvider>
+    </SafeAreaListener>
+  );
+};
+
+/**
+ * Re-export PortalHost for advanced use cases.
+ *
+ * @description
+ * Allows consumers to manually mount a portal host in custom layouts
+ * (e.g. for BottomSheet, Modal, or any overlay components).
+ */
+export { PortalHost };
+
+/**
+ * Default export for convenience
+ *
+ * @description
+ * Allows importing the provider without destructuring:
+ * ```tsx
+ * import HeroUINativeProvider from '@heroui/native/provider';
+ * ```
+ */
+export default HeroUINativeProvider;

package/src/providers/hero-ui-native/types.ts

@@ -0,0 +1,82 @@
+import type { ReactNode } from 'react';
+import type { AnimationRootDisableAll } from '../../helpers/types/animation';
+import type { TextComponentContextValue } from '../text-component/types';
+import type { ToastProviderProps } from '../toast/types';
+
+/**
+ * Configuration object for HeroUINativeProvider
+ *
+ * @interface HeroUINativeConfig
+ * @extends TextComponentContextValue
+ *
+ * @description
+ * Contains configuration options for the HeroUI Native provider.
+ * Additional configuration options can be added in future versions.
+ */
+export interface HeroUINativeConfig extends TextComponentContextValue {
+  /**
+   * Global animation configuration
+   *
+   * @description
+   * When set to 'disable-all', all animations across the application will be disabled.
+   */
+  animation?: AnimationRootDisableAll;
+  /**
+   * Toast configuration
+   *
+   * @description
+   * Configure the global toast system including insets and wrapper components.
+   */
+  toast?: ToastProviderProps;
+}
+
+/**
+ * Props for HeroUINativeProvider component
+ *
+ * @interface HeroUINativeProviderProps
+ *
+ * @description
+ * Main provider component props that wraps the entire application
+ * or a section of it to provide HeroUI Native functionality.
+ *
+ * @example
+ * ```tsx
+ * <HeroUINativeProvider config={{
+ *   textProps: {
+ *     allowFontScaling: false,
+ *     maxFontSizeMultiplier: 1.5
+ *   }
+ * }}>
+ *   <App />
+ * </HeroUINativeProvider>
+ * ```
+ */
+export interface HeroUINativeProviderProps {
+  /**
+   * Child components to render within the provider
+   *
+   * @description
+   * All children will have access to HeroUI Native theme
+   * and configuration through the provider.
+   */
+  children: ReactNode;
+
+  /**
+   * Configuration object for the provider
+   *
+   * @description
+   * Contains all configuration options including global text component configuration.
+   *
+   * @example
+   * ```tsx
+   * const config: HeroUINativeConfig = {
+   *   textProps: {
+   *     allowFontScaling: false,
+   *     adjustsFontSizeToFit: false,
+   *     maxFontSizeMultiplier: 1.5
+   *   }
+   * };
+   * ```
+   */
+  config?: HeroUINativeConfig;
+}

package/src/providers/text-component/index.ts

@@ -0,0 +1,2 @@
+export * from './provider';
+export * from './types';

package/src/providers/text-component/provider.tsx

@@ -0,0 +1,9 @@
+import { createContext } from '../../helpers/utils';
+import type { TextComponentContextValue } from './types';
+
+const [TextComponentProvider, useTextComponent] =
+  createContext<TextComponentContextValue>({
+    name: 'TextComponentContext',
+  });
+
+export { TextComponentProvider, useTextComponent };

package/src/providers/text-component/types.ts

@@ -0,0 +1,52 @@
+import type { TextProps } from 'react-native';
+
+/**
+ * Global text component configuration props.
+ * These props are carefully selected to include only those that make sense
+ * to configure globally across all Text components in the application.
+ *
+ * @description
+ * Includes accessibility and font scaling settings that typically
+ * should be consistent throughout the app for better UX.
+ */
+export type TextComponentProps = {
+  /**
+   * Specifies whether fonts should be scaled down automatically to fit given style constraints.
+   *
+   * @default false
+   */
+  adjustsFontSizeToFit?: TextProps['adjustsFontSizeToFit'];
+  /**
+   * Specifies whether fonts should scale to respect Text Size accessibility settings.
+   *
+   * @default true
+   */
+  allowFontScaling?: TextProps['allowFontScaling'];
+  /**
+   * Specifies the largest possible scale a font can reach when `allowFontScaling` is enabled.
+   *
+   * Possible values:
+   *
+   * - `null` or `undefined`: inherit from the parent node or the global default (0)
+   * - `0`: no max, ignore parent/global default
+   * - `>= 1`: sets the `maxFontSizeMultiplier` of this node to this value
+   *
+   * @default `undefined`
+   */
+  maxFontSizeMultiplier?: TextProps['maxFontSizeMultiplier'];
+  /**
+   * Specifies the smallest possible scale a font can reach when adjustsFontSizeToFit is enabled. (values 0.01-1.0).
+   *
+   * iOS only
+   *
+   * @default `undefined`
+   */
+  minimumFontScale?: TextProps['minimumFontScale'];
+};
+
+/**
+ * Context value for text component configuration
+ */
+export interface TextComponentContextValue {
+  textProps?: TextComponentProps;
+}

package/src/providers/toast/index.ts

@@ -0,0 +1,3 @@
+export { ToastProvider, useToast } from './provider';
+export { useToastConfig } from './toast-config.context';
+export type * from './types';

package/src/providers/toast/insets-container.tsx

@@ -0,0 +1,74 @@
+import type { ReactNode } from 'react';
+import { Fragment, useMemo } from 'react';
+import { Platform, View } from 'react-native';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { FullWindowOverlay } from 'react-native-screens';
+import type { ToastInsets } from './types';
+
+interface InsetsContainerProps {
+  /**
+   * Optional inset values for all edges
+   * If not provided, defaults to platform-specific values:
+   * - iOS: safe area insets + 0px (top), + 6px (bottom), + 12px (left/right)
+   * - Android: safe area insets + 12px (all edges)
+   */
+  insets?: ToastInsets;
+  /**
+   * Custom wrapper function to wrap the toast content
+   * Receives children and should return a component that wraps them
+   * The wrapper should apply flex: 1 (via className or style) to ensure proper layout
+   * Can be any component wrapper - KeyboardAvoidingView, View, or any custom component
+   */
+  contentWrapper?: (children: ReactNode) => React.ReactElement;
+  /**
+   * Children to render inside the container
+   */
+  children: ReactNode;
+}
+
+/**
+ * Container component that applies inset padding to position toasts
+ * away from screen edges and safe areas
+ *
+ * Combines custom insets with safe area insets:
+ * - If custom inset is provided, it overrides safe area + default padding
+ * - If not provided, uses platform-specific defaults:
+ *   - iOS: safe area inset + 0px for top, + 6px for bottom, + 12px for left/right
+ *   - Android: safe area inset + 12px for all edges
+ */
+export function InsetsContainer({
+  insets,
+  contentWrapper,
+  children,
+}: InsetsContainerProps) {
+  const safeAreaInsets = useSafeAreaInsets();
+
+  const finalInsets = useMemo(() => {
+    return {
+      top: insets?.top ?? safeAreaInsets.top + (Platform.OS === 'ios' ? 0 : 12),
+      bottom:
+        insets?.bottom ??
+        safeAreaInsets.bottom + (Platform.OS === 'ios' ? 6 : 12),
+      left: insets?.left ?? safeAreaInsets.left + 12,
+      right: insets?.right ?? safeAreaInsets.right + 12,
+    };
+  }, [safeAreaInsets, insets]);
+
+  const WindowOverlay = Platform.OS === 'ios' ? FullWindowOverlay : Fragment;
+
+  return (
+    <WindowOverlay>
+      <View
+        className="absolute inset-0 pointer-events-box-none"
+        style={{
+          paddingTop: finalInsets.top,
+          paddingBottom: finalInsets.bottom,
+          paddingLeft: finalInsets.left,
+          paddingRight: finalInsets.right,
+        }}
+      >
+        {contentWrapper ? contentWrapper(children) : children}
+      </View>
+    </WindowOverlay>
+  );
+}