react-native-earl-toastify 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-01-17
+
+### Added
+
+- 🎉 Initial release of react-native-earl-toastify
+
+#### Toast Types
+
+- `success` - Green themed toast for successful operations
+- `warning` - Amber themed toast for warnings
+- `error` - Red themed toast for errors
+- `info` - Blue themed toast for informational messages
+- `default` - Gray themed neutral toast
+- `custom` - Fully customizable toast with custom colors
+
+#### Animations
+
+- `fade` - Smooth opacity fade in/out
+- `up` - Slide up animation (from bottom for bottom position, to top for top position)
+- `down` - Slide down animation (from top for top position, to bottom for bottom position)
+- `left` - Slide from right to left
+- `right` - Slide from left to right
+- `none` - Instant appear/disappear without animation
+
+#### Positioning
+
+- `top` - Full-width positioning at top of screen with status bar padding
+- `bottom` - Full-width positioning at bottom with home indicator padding
+- `center` - Centered positioning with rounded corners and margins
+
+#### Configuration Options
+
+- `title` - Optional title (larger, bolder text displayed above the message)
+- `message` - Main text or description (smaller when title is present)
+- Flexible API: `toast.success("message")` OR `toast.success("title", "description")`
+- `duration` - Auto-dismiss duration in milliseconds (0 for no auto-dismiss)
+- `dismissable` - Toggle tap-to-dismiss functionality
+- `icon` - Custom icon support (works with any icon library like lucide-react-native)
+- `hideIcon` - Option to hide default icons
+- `backgroundColor`, `textColor`, `borderColor` - Custom color overrides
+- `style`, `textStyle` - Custom style overrides
+- `onShow`, `onHide`, `onPress` - Event callbacks
+
+#### Accessibility
+
+- WCAG 2.1 AA compliant color schemes (4.5:1 contrast ratio)
+- Screen reader announcements via AccessibilityInfo
+- Proper accessibility roles and live regions
+- Clear accessibility hints for dismissable toasts
+
+#### API
+
+- `ToastProvider` - Context provider component
+- `useToast` - Hook for showing toasts with `success()`, `warning()`, `error()`, `info()`, `show()`
+- `hide(id)` - Hide specific toast by ID
+- `hideAll()` - Hide all visible toasts
+- Full TypeScript support with exported types
+
+#### Global Toast Utility Pattern
+
+- Documented pattern for creating a global Toast utility
+- Supports calling `Toast.success()`, `Toast.error()` etc. from anywhere in your app
+- Customizable defaults for colors, animations, icons per toast type
+- No deprecated APIs - uses simple variable-based context storage

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rin
+
+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,513 @@
+# react-native-earl-toastify
+
+A beautiful, customizable toast notification library for React Native with smooth animations, multiple toast types, and full accessibility support.
+
+![GitHub stars](https://img.shields.io/github/stars/Swif7ify/react-native-earl-toastify?style=social)
+![npm](https://img.shields.io/npm/v/react-native-earl-toastify)
+![downloads](https://img.shields.io/npm/dm/react-native-earl-toastify)
+![license](https://img.shields.io/npm/l/react-native-earl-toastify)
+
+## ✨ Features
+
+- 🎬 **6 Animation Types**: fade, slide-up, slide-down, slide-left, slide-right, none
+- 🎨 **5 Toast Types**: success, warning, error, info, default + fully customizable
+- 📍 **3 Positions**: top, bottom, center
+- ♿ **Accessible**: WCAG 2.1 AA compliant color schemes & screen reader support
+- 🎯 **Always on Top**: Toasts render above all other content
+- 🔧 **Highly Configurable**: duration, dismissable, custom icons, custom styles
+- 📱 **Full-Width Edge Styling**: No rounded corners for top/bottom toasts
+- 🪶 **Zero Dependencies**: Uses only React Native's built-in Animated API
+
+## 📦 Installation
+
+```bash
+npm install react-native-earl-toastify
+# or
+yarn add react-native-earl-toastify
+```
+
+## 🚀 Quick Start
+
+### 1. Wrap your app with ToastProvider
+
+```tsx
+import { ToastProvider } from "react-native-earl-toastify";
+
+export default function App() {
+	return (
+		<ToastProvider>
+			<YourApp />
+		</ToastProvider>
+	);
+}
+```
+
+### 2. Use the useToast hook
+
+```tsx
+import { useToast } from "react-native-earl-toastify";
+
+function MyComponent() {
+	const toast = useToast();
+
+	const handleSuccess = () => {
+		toast.success("Operation completed successfully!");
+	};
+
+	const handleError = () => {
+		toast.error("Something went wrong");
+	};
+
+	return (
+		<View>
+			<Button title="Success" onPress={handleSuccess} />
+			<Button title="Error" onPress={handleError} />
+		</View>
+	);
+}
+```
+
+## 🛠️ Creating a Toast Utility (Recommended)
+
+For easier usage across your app, create a utility file that exposes toast functions globally with **your own custom defaults**:
+
+### 1. Create `utils/Toast.tsx`
+
+```tsx
+// utils/Toast.tsx
+import { ToastContextValue, ToastConfig } from "react-native-earl-toastify";
+// Optional: import your icon library
+// import { CheckCircle, AlertTriangle, XCircle, Info } from "lucide-react-native";
+
+// ============================================
+// Store toast context reference (simple variable)
+// ============================================
+let toastContext: ToastContextValue | null = null;
+
+export const setToastContext = (context: ToastContextValue) => {
+	toastContext = context;
+};
+
+// ============================================
+// 🎨 CUSTOMIZE YOUR TOAST DEFAULTS HERE
+// ============================================
+
+const CUSTOM_DEFAULTS: Record<string, Partial<ToastConfig>> = {
+	// Custom success style - your own green, animation, etc.
+	success: {
+		backgroundColor: "#D1FAE5", // Light green
+		textColor: "#065F46", // Dark green
+		borderColor: "#10B981", // Green border
+		animationIn: "up",
+		animationOut: "down",
+		position: "bottom",
+		duration: 3000,
+		// icon: <CheckCircle color="#10B981" size={20} />,
+	},
+
+	// Custom error style
+	error: {
+		backgroundColor: "#FEE2E2", // Light red
+		textColor: "#991B1B", // Dark red
+		borderColor: "#EF4444", // Red border
+		animationIn: "fade",
+		animationOut: "fade",
+		position: "top",
+		duration: 5000,
+		// icon: <XCircle color="#EF4444" size={20} />,
+	},
+
+	// Custom warning style
+	warning: {
+		backgroundColor: "#FEF3C7", // Light amber
+		textColor: "#92400E", // Dark amber
+		borderColor: "#F59E0B", // Amber border
+		animationIn: "right",
+		animationOut: "left",
+		position: "top",
+		duration: 4000,
+		// icon: <AlertTriangle color="#F59E0B" size={20} />,
+	},
+
+	// Custom info style
+	info: {
+		backgroundColor: "#DBEAFE", // Light blue
+		textColor: "#1E40AF", // Dark blue
+		borderColor: "#3B82F6", // Blue border
+		animationIn: "left",
+		animationOut: "right",
+		position: "top",
+		duration: 3000,
+		// icon: <Info color="#3B82F6" size={20} />,
+	},
+};
+
+// ============================================
+// Helper to parse flexible arguments
+// ============================================
+const parseArgs = (
+	titleOrMessage: string,
+	descriptionOrConfig?: string | Partial<ToastConfig>,
+	config?: Partial<ToastConfig>,
+): { title?: string; message: string; config?: Partial<ToastConfig> } => {
+	if (typeof descriptionOrConfig === "string") {
+		return { title: titleOrMessage, message: descriptionOrConfig, config };
+	}
+	return { message: titleOrMessage, config: descriptionOrConfig };
+};
+
+// ============================================
+// Toast utility with custom defaults
+// ============================================
+const Toast = {
+	success: (
+		titleOrMessage: string,
+		descriptionOrConfig?: string | Partial<ToastConfig>,
+		config?: Partial<ToastConfig>,
+	) => {
+		const {
+			title,
+			message,
+			config: cfg,
+		} = parseArgs(titleOrMessage, descriptionOrConfig, config);
+		toastContext?.show({
+			...CUSTOM_DEFAULTS.success,
+			...cfg,
+			title,
+			message,
+			type: "custom", // Use custom to apply our colors
+		});
+	},
+
+	error: (
+		titleOrMessage: string,
+		descriptionOrConfig?: string | Partial<ToastConfig>,
+		config?: Partial<ToastConfig>,
+	) => {
+		const {
+			title,
+			message,
+			config: cfg,
+		} = parseArgs(titleOrMessage, descriptionOrConfig, config);
+		toastContext?.show({
+			...CUSTOM_DEFAULTS.error,
+			...cfg,
+			title,
+			message,
+			type: "custom",
+		});
+	},
+
+	warning: (
+		titleOrMessage: string,
+		descriptionOrConfig?: string | Partial<ToastConfig>,
+		config?: Partial<ToastConfig>,
+	) => {
+		const {
+			title,
+			message,
+			config: cfg,
+		} = parseArgs(titleOrMessage, descriptionOrConfig, config);
+		toastContext?.show({
+			...CUSTOM_DEFAULTS.warning,
+			...cfg,
+			title,
+			message,
+			type: "custom",
+		});
+	},
+
+	info: (
+		titleOrMessage: string,
+		descriptionOrConfig?: string | Partial<ToastConfig>,
+		config?: Partial<ToastConfig>,
+	) => {
+		const {
+			title,
+			message,
+			config: cfg,
+		} = parseArgs(titleOrMessage, descriptionOrConfig, config);
+		toastContext?.show({
+			...CUSTOM_DEFAULTS.info,
+			...cfg,
+			title,
+			message,
+			type: "custom",
+		});
+	},
+
+	// Generic show for full customization
+	show: (config: ToastConfig) => {
+		toastContext?.show(config);
+	},
+
+	hide: (id: string) => {
+		toastContext?.hide(id);
+	},
+
+	hideAll: () => {
+		toastContext?.hideAll();
+	},
+};
+
+export default Toast;
+```
+
+### 2. Create a wrapper component `components/ToastWrapper.tsx`
+
+```tsx
+// components/ToastWrapper.tsx
+import React, { useEffect } from "react";
+import { useToast } from "react-native-earl-toastify";
+import { setToastContext } from "../utils/Toast";
+
+export const ToastWrapper: React.FC<{ children: React.ReactNode }> = ({
+	children,
+}) => {
+	const toast = useToast();
+
+	useEffect(() => {
+		// Set the toast context when component mounts
+		setToastContext(toast);
+	}, [toast]);
+
+	return <>{children}</>;
+};
+```
+
+### 3. Update your App.tsx
+
+```tsx
+// App.tsx
+import { ToastProvider } from "react-native-earl-toastify";
+import { ToastWrapper } from "./components/ToastWrapper";
+
+export default function App() {
+	return (
+		<ToastProvider>
+			<ToastWrapper>
+				<YourApp />
+			</ToastWrapper>
+		</ToastProvider>
+	);
+}
+```
+
+### 4. Use anywhere in your app!
+
+```tsx
+// ANY file - no hooks needed!
+import Toast from "../utils/Toast";
+
+// Simple message (no title)
+Toast.success("Data loaded successfully!");
+
+// With title + description
+Toast.success("Success!", "Data loaded successfully");
+Toast.error("Error", "Failed to load data");
+Toast.warning("Warning", "Please review before submitting");
+Toast.info("Info", "New update available");
+
+// With title, description, AND config
+Toast.success("Uploaded!", "Your file is ready", { position: "bottom" });
+
+// Custom toast
+Toast.show({
+	message: "Custom notification",
+	type: "custom",
+	backgroundColor: "#8B5CF6",
+	textColor: "#FFFFFF",
+	position: "bottom",
+	animationIn: "up",
+});
+```
+
+> [!TIP]
+> This pattern lets you call `Toast.success()`, `Toast.error()`, etc. from **anywhere** - including utility functions, API handlers, and non-component files!
+
+### ToastProvider Props
+
+| Prop     | Type                  | Default | Description                         |
+| -------- | --------------------- | ------- | ----------------------------------- |
+| `config` | `ToastProviderConfig` | `{}`    | Global configuration for all toasts |
+
+#### ToastProviderConfig
+
+```typescript
+interface ToastProviderConfig {
+	defaultPosition?: "top" | "bottom" | "center"; // Default: 'top'
+	defaultDuration?: number; // Default: 3000 (ms)
+	defaultAnimationIn?: ToastAnimation; // Default: 'fade'
+	defaultAnimationOut?: ToastAnimation; // Default: 'fade'
+	defaultAnimationDuration?: number; // Default: 300 (ms)
+	maxToasts?: number; // Default: 5
+}
+```
+
+### useToast Hook
+
+```typescript
+const toast = useToast();
+
+// Quick methods
+toast.success(message: string, config?: Partial<ToastConfig>);
+toast.warning(message: string, config?: Partial<ToastConfig>);
+toast.error(message: string, config?: Partial<ToastConfig>);
+toast.info(message: string, config?: Partial<ToastConfig>);
+
+// Custom toast
+toast.show(config: ToastConfig);
+
+// Control methods
+toast.hide(id: string);    // Hide specific toast
+toast.hideAll();           // Hide all toasts
+```
+
+### ToastConfig
+
+| Option              | Type                                                                   | Default      | Description                                   |
+| ------------------- | ---------------------------------------------------------------------- | ------------ | --------------------------------------------- |
+| `message`           | `string`                                                               | **required** | Toast message                                 |
+| `type`              | `'success' \| 'warning' \| 'error' \| 'info' \| 'default' \| 'custom'` | `'default'`  | Toast type                                    |
+| `position`          | `'top' \| 'bottom' \| 'center'`                                        | `'top'`      | Screen position                               |
+| `duration`          | `number`                                                               | `3000`       | Auto-dismiss time in ms (0 = no auto-dismiss) |
+| `animationIn`       | `ToastAnimation`                                                       | `'fade'`     | Enter animation                               |
+| `animationOut`      | `ToastAnimation`                                                       | `'fade'`     | Exit animation                                |
+| `animationDuration` | `number`                                                               | `300`        | Animation duration in ms                      |
+| `dismissable`       | `boolean`                                                              | `true`       | Can dismiss by tapping                        |
+| `icon`              | `ReactNode`                                                            | -            | Custom icon element                           |
+| `hideIcon`          | `boolean`                                                              | `false`      | Hide the icon                                 |
+| `backgroundColor`   | `string`                                                               | -            | Custom background color                       |
+| `textColor`         | `string`                                                               | -            | Custom text color                             |
+| `borderColor`       | `string`                                                               | -            | Custom border color                           |
+| `style`             | `ViewStyle`                                                            | -            | Custom container style                        |
+| `textStyle`         | `TextStyle`                                                            | -            | Custom text style                             |
+| `onShow`            | `() => void`                                                           | -            | Callback when shown                           |
+| `onHide`            | `() => void`                                                           | -            | Callback when hidden                          |
+| `onPress`           | `() => void`                                                           | -            | Callback when pressed                         |
+
+### Animation Types
+
+```typescript
+type ToastAnimation = "fade" | "up" | "down" | "left" | "right" | "none";
+```
+
+| Animation | Description              |
+| --------- | ------------------------ |
+| `fade`    | Fade in/out              |
+| `up`      | Slide from bottom        |
+| `down`    | Slide from top           |
+| `left`    | Slide from right         |
+| `right`   | Slide from left          |
+| `none`    | Instant appear/disappear |
+
+## 🎨 Examples
+
+### Custom Styled Toast
+
+```tsx
+toast.show({
+	message: "Custom purple toast!",
+	type: "custom",
+	backgroundColor: "#8B5CF6",
+	textColor: "#FFFFFF",
+	borderColor: "#7C3AED",
+	position: "bottom",
+	animationIn: "up",
+	animationOut: "down",
+});
+```
+
+### With Custom Icon (react-native-lucide)
+
+```tsx
+import { CheckCircle } from "lucide-react-native";
+
+toast.success("Saved!", {
+	icon: <CheckCircle color="#10B981" size={20} />,
+});
+```
+
+### Non-Dismissable with Long Duration
+
+```tsx
+toast.info("Please wait...", {
+	dismissable: false,
+	duration: 0, // Won't auto-dismiss
+});
+
+// Later, dismiss programmatically
+const id = toast.info("Loading...", { dismissable: false, duration: 0 });
+// ... after loading complete
+toast.hide(id);
+```
+
+### Centered Toast with Callback
+
+```tsx
+toast.warning("Session expiring soon", {
+	position: "center",
+	duration: 5000,
+	onPress: () => {
+		// Handle press - e.g., refresh session
+		refreshSession();
+	},
+	onHide: () => {
+		console.log("Toast dismissed");
+	},
+});
+```
+
+### Different Animations
+
+```tsx
+// Slide from bottom
+toast.success("Uploaded!", {
+	position: "bottom",
+	animationIn: "up",
+	animationOut: "down",
+});
+
+// Slide from side
+toast.info("New message", {
+	animationIn: "right",
+	animationOut: "left",
+});
+
+// Instant (no animation)
+toast.error("Error!", {
+	animationIn: "none",
+	animationOut: "none",
+});
+```
+
+## 🎯 Positioning Behavior
+
+| Position | Behavior                                                    |
+| -------- | ----------------------------------------------------------- |
+| `top`    | Full-width, no rounded corners, accounts for status bar     |
+| `bottom` | Full-width, no rounded corners, accounts for home indicator |
+| `center` | Centered with margins and rounded corners                   |
+
+## 🎨 Default Color Schemes
+
+| Type    | Background | Text      | Border    |
+| ------- | ---------- | --------- | --------- |
+| Success | `#ECFDF5`  | `#065F46` | `#10B981` |
+| Warning | `#FFFBEB`  | `#92400E` | `#F59E0B` |
+| Error   | `#FEF2F2`  | `#991B1B` | `#EF4444` |
+| Info    | `#EFF6FF`  | `#1E40AF` | `#3B82F6` |
+| Default | `#F9FAFB`  | `#374151` | `#D1D5DB` |
+
+All color combinations meet **WCAG 2.1 AA** contrast requirements (4.5:1 minimum).
+
+## ♿ Accessibility
+
+- All toasts are announced to screen readers via `AccessibilityInfo.announceForAccessibility`
+- Proper `accessibilityRole="alert"` and `accessibilityLiveRegion="polite"` attributes
+- Dismissable toasts have clear accessibility hints
+- Color contrasts meet WCAG 2.1 AA standards
+
+## 📄 License
+
+MIT © Earl

package/dist/Toast.d.ts

@@ -0,0 +1,12 @@
+import React from "react";
+import { Toast as ToastData, ToastPosition } from "./types";
+export interface ToastProps {
+    toast: ToastData;
+    position: ToastPosition;
+    onHide: (id: string) => void;
+}
+/**
+ * Individual Toast component with animations
+ */
+export declare const Toast: React.FC<ToastProps>;
+//# sourceMappingURL=Toast.d.ts.map

package/dist/Toast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Toast.d.ts","sourceRoot":"","sources":["../src/Toast.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAyC,MAAM,OAAO,CAAC;AAS9D,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,aAAa,EAAkB,MAAM,SAAS,CAAC;AAe5E,MAAM,WAAW,UAAU;IAC1B,KAAK,EAAE,SAAS,CAAC;IACjB,QAAQ,EAAE,aAAa,CAAC;IACxB,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED;;GAEG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC,UAAU,CAgNtC,CAAC"}