@erquhart/heroui-native 1.0.0-beta.10.1

package/lib/module/providers/hero-ui-native/provider.js

@@ -0,0 +1,92 @@
+"use strict";
+
+import React, { useEffect } from 'react';
+import { SafeAreaListener } from 'react-native-safe-area-context';
+import { Uniwind } from 'uniwind';
+import { PortalHost } from "../../primitives/portal/index.js";
+import { GlobalAnimationSettingsProvider } from "../animation-settings/index.js";
+import { TextComponentProvider } from "../text-component/provider.js";
+import { ToastProvider } from "../toast/provider.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+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 = ({
+  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 /*#__PURE__*/_jsx(SafeAreaListener, {
+    onChange: ({
+      insets
+    }) => {
+      Uniwind.updateInsets(insets);
+    },
+    children: /*#__PURE__*/_jsx(GlobalAnimationSettingsProvider, {
+      animation: animation,
+      children: /*#__PURE__*/_jsx(TextComponentProvider, {
+        value: {
+          textProps
+        },
+        children: /*#__PURE__*/_jsxs(ToastProvider, {
+          ...toastProps,
+          children: [children, /*#__PURE__*/_jsx(PortalHost, {})]
+        })
+      })
+    })
+  });
+};
+
+/**
+ * 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;
+//# sourceMappingURL=provider.js.map

package/lib/module/providers/hero-ui-native/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["React","useEffect","SafeAreaListener","Uniwind","PortalHost","GlobalAnimationSettingsProvider","TextComponentProvider","ToastProvider","jsx","_jsx","jsxs","_jsxs","LOG_COLOR","BLUE","RESET","HeroUINativeProvider","children","config","textProps","toast","animation","toastProps","__DEV__","console","info","onChange","insets","updateInsets","value"],"sourceRoot":"../../../../src","sources":["providers/hero-ui-native/provider.tsx"],"mappings":";;AAAA,OAAOA,KAAK,IAAIC,SAAS,QAAQ,OAAO;AACxC,SAASC,gBAAgB,QAAQ,gCAAgC;AACjE,SAASC,OAAO,QAAQ,SAAS;AACjC,SAASC,UAAU,QAAQ,kCAAyB;AACpD,SAASC,+BAA+B,QAAQ,gCAAuB;AACvE,SAASC,qBAAqB,QAAQ,+BAA4B;AAClE,SAASC,aAAa,QAAQ,sBAAmB;AAAC,SAAAC,GAAA,IAAAC,IAAA,EAAAC,IAAA,IAAAC,KAAA;AAGlD,MAAMC,SAAS,GAAG;EAChBC,IAAI,EAAE,UAAU;EAChBC,KAAK,EAAE;AACT,CAAC;;AAED;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,oBAAyD,GAAGA,CAAC;EACxEC,QAAQ;EACRC,MAAM,GAAG,CAAC;AACZ,CAAC,KAAK;EACJ,MAAM;IAAEC,SAAS;IAAEC,KAAK;IAAEC;EAAU,CAAC,GAAGH,MAAM;EAC9C,MAAM;IAAE,GAAGI;EAAW,CAAC,GAAGF,KAAK,IAAI,CAAC,CAAC;EAErClB,SAAS,CAAC,MAAM;IACd,IAAIqB,OAAO,EAAE;MACXC,OAAO,CAACC,IAAI,CACV,GAAGZ,SAAS,CAACC,IAAI,mCAAmCD,SAAS,CAACE,KAAK,IAAI,GACrE,oHAAoH,GACpH,4KAA4K,GAC5K,kKAAkK,GAClK,uHAAuH,GACvH,2GAA2G,GAC3G,4GAA4G,GAC5G,sGACJ,CAAC;IACH;EACF,CAAC,EAAE,EAAE,CAAC;EAEN,oBACEL,IAAA,CAACP,gBAAgB;IACfuB,QAAQ,EAAEA,CAAC;MAAEC;IAAO,CAAC,KAAK;MACxBvB,OAAO,CAACwB,YAAY,CAACD,MAAM,CAAC;IAC9B,CAAE;IAAAV,QAAA,eAEFP,IAAA,CAACJ,+BAA+B;MAACe,SAAS,EAAEA,SAAU;MAAAJ,QAAA,eACpDP,IAAA,CAACH,qBAAqB;QAACsB,KAAK,EAAE;UAAEV;QAAU,CAAE;QAAAF,QAAA,eAC1CL,KAAA,CAACJ,aAAa;UAAA,GAAKc,UAAU;UAAAL,QAAA,GAC1BA,QAAQ,eACTP,IAAA,CAACL,UAAU,IAAE,CAAC;QAAA,CACD;MAAC,CACK;IAAC,CACO;EAAC,CAClB,CAAC;AAEvB,CAAC;;AAED;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASA,UAAU;;AAEnB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,eAAeW,oBAAoB","ignoreList":[]}

package/lib/module/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/lib/module/providers/hero-ui-native/types.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=types.js.map

package/lib/module/providers/hero-ui-native/types.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../../../src","sources":["providers/hero-ui-native/types.ts"],"mappings":"","ignoreList":[]}

package/lib/module/providers/text-component/index.js

@@ -0,0 +1,5 @@
+"use strict";
+
+export * from "./provider.js";
+export * from "./types.js";
+//# sourceMappingURL=index.js.map

package/lib/module/providers/text-component/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../../../src","sources":["providers/text-component/index.ts"],"mappings":";;AAAA,cAAc,eAAY;AAC1B,cAAc,YAAS","ignoreList":[]}

package/lib/module/providers/text-component/provider.js

@@ -0,0 +1,8 @@
+"use strict";
+
+import { createContext } from "../../helpers/utils/index.js";
+const [TextComponentProvider, useTextComponent] = createContext({
+  name: 'TextComponentContext'
+});
+export { TextComponentProvider, useTextComponent };
+//# sourceMappingURL=provider.js.map

package/lib/module/providers/text-component/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["createContext","TextComponentProvider","useTextComponent","name"],"sourceRoot":"../../../../src","sources":["providers/text-component/provider.tsx"],"mappings":";;AAAA,SAASA,aAAa,QAAQ,8BAAqB;AAGnD,MAAM,CAACC,qBAAqB,EAAEC,gBAAgB,CAAC,GAC7CF,aAAa,CAA4B;EACvCG,IAAI,EAAE;AACR,CAAC,CAAC;AAEJ,SAASF,qBAAqB,EAAEC,gBAAgB","ignoreList":[]}

package/lib/module/providers/text-component/types.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=types.js.map

package/lib/module/providers/text-component/types.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../../../src","sources":["providers/text-component/types.ts"],"mappings":"","ignoreList":[]}

package/lib/module/providers/toast/index.js

@@ -0,0 +1,5 @@
+"use strict";
+
+export { ToastProvider, useToast } from "./provider.js";
+export { useToastConfig } from "./toast-config.context.js";
+//# sourceMappingURL=index.js.map

package/lib/module/providers/toast/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["ToastProvider","useToast","useToastConfig"],"sourceRoot":"../../../../src","sources":["providers/toast/index.ts"],"mappings":";;AAAA,SAASA,aAAa,EAAEC,QAAQ,QAAQ,eAAY;AACpD,SAASC,cAAc,QAAQ,2BAAwB","ignoreList":[]}

package/lib/module/providers/toast/insets-container.js

@@ -0,0 +1,46 @@
+"use strict";
+
+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 { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * 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
+}) {
+  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 /*#__PURE__*/_jsx(WindowOverlay, {
+    children: /*#__PURE__*/_jsx(View, {
+      className: "absolute inset-0 pointer-events-box-none",
+      style: {
+        paddingTop: finalInsets.top,
+        paddingBottom: finalInsets.bottom,
+        paddingLeft: finalInsets.left,
+        paddingRight: finalInsets.right
+      },
+      children: contentWrapper ? contentWrapper(children) : children
+    })
+  });
+}
+//# sourceMappingURL=insets-container.js.map

package/lib/module/providers/toast/insets-container.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["Fragment","useMemo","Platform","View","useSafeAreaInsets","FullWindowOverlay","jsx","_jsx","InsetsContainer","insets","contentWrapper","children","safeAreaInsets","finalInsets","top","OS","bottom","left","right","WindowOverlay","className","style","paddingTop","paddingBottom","paddingLeft","paddingRight"],"sourceRoot":"../../../../src","sources":["providers/toast/insets-container.tsx"],"mappings":";;AACA,SAASA,QAAQ,EAAEC,OAAO,QAAQ,OAAO;AACzC,SAASC,QAAQ,EAAEC,IAAI,QAAQ,cAAc;AAC7C,SAASC,iBAAiB,QAAQ,gCAAgC;AAClE,SAASC,iBAAiB,QAAQ,sBAAsB;AAAC,SAAAC,GAAA,IAAAC,IAAA;AAwBzD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,eAAeA,CAAC;EAC9BC,MAAM;EACNC,cAAc;EACdC;AACoB,CAAC,EAAE;EACvB,MAAMC,cAAc,GAAGR,iBAAiB,CAAC,CAAC;EAE1C,MAAMS,WAAW,GAAGZ,OAAO,CAAC,MAAM;IAChC,OAAO;MACLa,GAAG,EAAEL,MAAM,EAAEK,GAAG,IAAIF,cAAc,CAACE,GAAG,IAAIZ,QAAQ,CAACa,EAAE,KAAK,KAAK,GAAG,CAAC,GAAG,EAAE,CAAC;MACzEC,MAAM,EACJP,MAAM,EAAEO,MAAM,IACdJ,cAAc,CAACI,MAAM,IAAId,QAAQ,CAACa,EAAE,KAAK,KAAK,GAAG,CAAC,GAAG,EAAE,CAAC;MAC1DE,IAAI,EAAER,MAAM,EAAEQ,IAAI,IAAIL,cAAc,CAACK,IAAI,GAAG,EAAE;MAC9CC,KAAK,EAAET,MAAM,EAAES,KAAK,IAAIN,cAAc,CAACM,KAAK,GAAG;IACjD,CAAC;EACH,CAAC,EAAE,CAACN,cAAc,EAAEH,MAAM,CAAC,CAAC;EAE5B,MAAMU,aAAa,GAAGjB,QAAQ,CAACa,EAAE,KAAK,KAAK,GAAGV,iBAAiB,GAAGL,QAAQ;EAE1E,oBACEO,IAAA,CAACY,aAAa;IAAAR,QAAA,eACZJ,IAAA,CAACJ,IAAI;MACHiB,SAAS,EAAC,0CAA0C;MACpDC,KAAK,EAAE;QACLC,UAAU,EAAET,WAAW,CAACC,GAAG;QAC3BS,aAAa,EAAEV,WAAW,CAACG,MAAM;QACjCQ,WAAW,EAAEX,WAAW,CAACI,IAAI;QAC7BQ,YAAY,EAAEZ,WAAW,CAACK;MAC5B,CAAE;MAAAP,QAAA,EAEDD,cAAc,GAAGA,cAAc,CAACC,QAAQ,CAAC,GAAGA;IAAQ,CACjD;EAAC,CACM,CAAC;AAEpB","ignoreList":[]}