beautiful-snackbar 1.0.0

package/README.md

@@ -0,0 +1,233 @@
+# 🌈 Beautiful Snackbar
+
+A lightweight, premium, highly customizable, and **Reanimated-free** notification system for React Native and Expo. Powered by standard React Native `Animated` with native driver transitions to guarantee buttery-smooth 60fps animations.
+
+<div align="center">
+  <br />
+  <div style="background-color: #1e1e2e; border: 1px solid #313244; padding: 12px; border-radius: 16px; max-width: 320px; box-shadow: 0 10px 30px rgba(0,0,0,0.3);">
+    <div style="background-color: #11111b; border-radius: 10px; overflow: hidden; display: flex; border: 1px solid #45475a;">
+      <video src="https://github.com/user-attachments/assets/acf635cd-dbe8-401c-b3cc-701cde5464c7" width="100%" autoplay loop muted playsinline></video>
+    </div>
+  </div>
+  <br />
+</div>
+
+---
+
+## 💡 Why Beautiful Snackbar?
+
+Most React Native notification libraries either require heavy libraries like `react-native-reanimated` or wrap your entire code in complex React context providers. 
+
+`beautiful-snackbar` was built to solve this by providing:
+* 🔋 **Zero Heavy Dependencies:** Written entirely using React Native's built-in `Animated` API with `useNativeDriver: true`.
+* ⚡ **Singleton Architecture:** Trigger notifications from anywhere—inside a Redux action, an Axios interceptor, or a vanilla helper function—without hooks, contexts, or prop-drilling.
+* 🎹 **True Keyboard Synchronization:** Dynamically adjusts its position as the soft keyboard slides up, taking safe areas into account so that it sits naturally at a configured height without compounding inset paddings.
+
+---
+
+## ✨ Features
+
+* 🚀 **Buttery-Smooth Animations:** Built-in transition presets (`slide`, `fade`, `scale`) that execute entirely on the native thread.
+* ⌨️ **Keyboard & Safe Area Aware:** Intelligently listens to keyboard show/hide events and automatically translates above the keyboard while cleanly canceling out safe area bottom margins.
+* 🛠️ **Custom UI Templates:** Register your own custom layouts at the root, and trigger them dynamically from anywhere by passing custom metadata.
+* ⚙️ **Global Configuration Manager:** Tweak properties (offsets, animations, placement) dynamically at runtime via manager setters.
+* 🧭 **Navigation Listener:** Automatically dismisses active snackbars on navigation transitions to keep user experience clean.
+
+---
+
+## 📦 Installation
+
+Install the package using your favorite package manager:
+
+```bash
+# Using yarn
+yarn add beautiful-snackbar
+
+# Using npm
+npm install beautiful-snackbar
+```
+
+### Peer Dependencies
+To handle safe area offsets and screen layouts cleanly, ensure you have `react-native-safe-area-context` installed:
+
+```bash
+npx expo install react-native-safe-area-context
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Mount the Root Provider
+Render `<BeautifulSnackbar />` at the root of your application (usually inside `_layout.tsx` or `App.tsx`). This acts as the overlay portal.
+
+```tsx
+import React from 'react';
+import { View } from 'react-native';
+import { BeautifulSnackbar } from 'beautiful-snackbar';
+
+export default function Layout() {
+  return (
+    <View style={{ flex: 1 }}>
+      {/* Your main app views (Tabs, Stack, etc.) */}
+      
+      {/* Overlay container */}
+      <BeautifulSnackbar />
+    </View>
+  );
+}
+```
+
+### 2. Trigger Notifications Anywhere
+Simply import the `snackbar` singleton instance and call `.show()` from anywhere in your codebase:
+
+```tsx
+import { snackbar } from 'beautiful-snackbar';
+
+// Trigger a default bottom toast
+snackbar.show({
+  message: '✨ Profile updated successfully!',
+  backgroundColor: '#10B981', // Emerald green
+  duration: 'short',
+});
+```
+
+---
+
+## 🛠️ Advanced Usage & Customization
+
+### 1. Global Configuration Manager
+You can modify the default behaviors dynamically. This is typically done during app startup:
+
+```tsx
+import { snackbar } from 'beautiful-snackbar';
+
+// Set global configuration defaults
+snackbar.setPosition('bottom');      // Set default position ('top' | 'bottom')
+snackbar.setAnimationType('scale');    // Set default entry animation ('slide' | 'fade' | 'scale')
+snackbar.setBottomOffset(24);        // Set default bottom spacing in pixels
+snackbar.setAvoidKeyboard(true);      // Enable/disable soft keyboard avoidance
+```
+
+### 2. Custom UI Template Registration
+Do you need custom cards, badge overlays, or promotional layouts? Register your custom React layouts at the root using the `templates` prop:
+
+```tsx
+import React from 'react';
+import { View, Text, TouchableOpacity } from 'react-native';
+import { BeautifulSnackbar } from 'beautiful-snackbar';
+
+// Define your custom template layout
+const customTemplates = {
+  promoCard: ({ item, dismiss }) => (
+    <View style={{ padding: 16, backgroundColor: '#31115F', borderRadius: 12 }}>
+      <Text style={{ color: '#ffffff', fontWeight: 'bold' }}>{item.message}</Text>
+      <Text style={{ color: '#C084FC' }}>{item.data?.subtitle}</Text>
+      
+      <TouchableOpacity onPress={dismiss}>
+        <Text style={{ color: '#F59E0B', marginTop: 8 }}>Got it</Text>
+      </TouchableOpacity>
+    </View>
+  ),
+};
+
+export default function App() {
+  return (
+    <View style={{ flex: 1 }}>
+      <BeautifulSnackbar templates={customTemplates} />
+    </View>
+  );
+}
+```
+
+Trigger your custom UI card programmatically from anywhere:
+```tsx
+import { snackbar } from 'beautiful-snackbar';
+
+snackbar.show({
+  type: 'promoCard', // Match the template key
+  message: 'Premium Feature Unlocked!',
+  data: {
+    subtitle: 'Enjoy unlimited ad-free streaming.',
+  },
+  duration: 'infinite', // Keep visible until dismissed manually
+});
+```
+
+### 3. Actionable Buttons
+Create standard, actionable snackbars with button press handlers:
+
+```tsx
+snackbar.show({
+  message: '🗑️ Message permanently deleted.',
+  backgroundColor: '#1E293B',
+  actionLabel: 'Undo',
+  actionColor: '#818CF8',
+  onActionPress: () => {
+    // Perform undo action
+    snackbar.show({ message: 'Restored!', backgroundColor: '#10B981' });
+  },
+});
+```
+
+---
+
+## 📖 API Reference
+
+### `<BeautifulSnackbar />` Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `navigation` | `any` | `undefined` | Optional React Navigation controller reference to automatically clear notifications on screen changes. |
+| `avoidKeyboard` | `boolean` | `true` | When `true`, snackbars automatically shift up dynamically when the keyboard appears. |
+| `templates` | `Record<string, Component>` | `undefined` | Map of key-value pairs representing custom templates. |
+
+### `snackbar.show()` Configuration Options
+
+| Property | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `message` | `string` | **Required** | The message string to display inside standard alerts. |
+| `duration` | `'short' \| 'medium' \| 'long' \| 'infinite' \| number` | `'short'` | Time on screen. Short (1500ms), Medium (2750ms), Long (4000ms), Infinite (requires dismissal), or custom duration in milliseconds. |
+| `position` | `'top' \| 'bottom'` | `'bottom'` (config) | Placement on screen. Overrides global manager position. |
+| `animationType` | `'slide' \| 'fade' \| 'scale'` | `'slide'` (config) | Transition style preset. Overrides global manager type. |
+| `bottomOffset` | `number` | `24` (config) | Pixel spacing from screen bottom or soft keyboard. |
+| `topOffset` | `number` | `50` (iOS) / `24` (Android) | Pixel spacing from screen top. |
+| `backgroundColor` | `string` | `'#1E293B'` | Custom container background color. |
+| `textColor` | `string` | `'#F8FAFC'` | Custom color for message text. |
+| `actionLabel` | `string` | `undefined` | Interactive button label text. |
+| `actionColor` | `string` | `'#6366F1'` | Text color of the interactive button. |
+| `onActionPress` | `() => void` | `undefined` | Callback function triggered when action button is clicked. |
+| `icon` | `React.ReactNode` | `undefined` | Optional leading element (e.g. image, custom SVG, text emoji). |
+| `dismissOnNavigation` | `boolean` | `true` | If `true`, dismisses the notification when user changes pages. |
+| `type` | `string` | `undefined` | Key matching a registered custom template component. |
+| `data` | `any` | `undefined` | Arbitrary context payload passed down to custom templates. |
+
+---
+
+## 🛠️ Testing & Running the Example App
+
+To inspect the package interactively, run the local Expo example app:
+
+1. **Clone and Install dependencies:**
+   Ensure `"private": true` is set in the root `package.json` before running `yarn` (this is required to prevent Yarn workspace resolution conflicts).
+   ```bash
+   yarn install
+   ```
+
+2. **Build the parent library:**
+   ```bash
+   yarn run build
+   ```
+
+3. **Start the Expo development server:**
+   ```bash
+   cd example
+   npx expo start
+   ```
+
+4. Press `i` to open in iOS simulator, or `a` to open in Android.
+
+---
+
+## 📄 License
+This project is licensed under the **MIT License**.

package/example/.claude/settings.json

@@ -0,0 +1,5 @@
+{
+  "enabledPlugins": {
+    "expo@claude-plugins-official": true
+  }
+}

package/example/.vscode/extensions.json

@@ -0,0 +1 @@
+{ "recommendations": ["expo.vscode-expo-tools"] }

package/example/.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+  "editor.codeActionsOnSave": {
+    "source.fixAll": "explicit",
+    "source.organizeImports": "explicit",
+    "source.sortMembers": "explicit"
+  }
+}

package/example/AGENTS.md

@@ -0,0 +1,3 @@
+# Expo HAS CHANGED
+
+Read the exact versioned docs at https://docs.expo.dev/versions/v55.0.0/ before writing any code.

package/example/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/example/app.json

@@ -0,0 +1,44 @@
+{
+  "expo": {
+    "name": "example",
+    "slug": "example",
+    "version": "1.0.0",
+    "orientation": "portrait",
+    "icon": "./assets/images/icon.png",
+    "scheme": "example",
+    "userInterfaceStyle": "automatic",
+    "ios": {
+      "icon": "./assets/expo.icon"
+    },
+    "android": {
+      "adaptiveIcon": {
+        "backgroundColor": "#E6F4FE",
+        "foregroundImage": "./assets/images/android-icon-foreground.png",
+        "backgroundImage": "./assets/images/android-icon-background.png",
+        "monochromeImage": "./assets/images/android-icon-monochrome.png"
+      },
+      "predictiveBackGestureEnabled": false
+    },
+    "web": {
+      "output": "static",
+      "favicon": "./assets/images/favicon.png"
+    },
+    "plugins": [
+      "expo-router",
+      [
+        "expo-splash-screen",
+        {
+          "backgroundColor": "#208AEF",
+          "android": {
+            "image": "./assets/images/splash-icon.png",
+            "imageWidth": 76
+          }
+        }
+      ]
+    ],
+    "experiments": {
+      "typedRoutes": true,
+      "reactCompiler": true
+    }
+  }
+}

package/example/assets/expo.icon/Assets/expo-symbol 2.svg

@@ -0,0 +1,3 @@
+<svg width="652" height="606" viewBox="0 0 652 606" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M353.554 0H298.446C273.006 0 249.684 14.6347 237.962 37.9539L4.37994 502.646C-1.04325 513.435 -1.45067 526.178 3.2716 537.313L22.6123 582.918C34.6475 611.297 72.5404 614.156 88.4414 587.885L309.863 222.063C313.34 216.317 319.439 212.826 326 212.826C332.561 212.826 338.659 216.317 342.137 222.063L563.559 587.885C579.46 614.156 617.352 611.297 629.388 582.918L648.728 537.313C653.451 526.178 653.043 513.435 647.62 502.646L414.038 37.9539C402.316 14.6347 378.994 0 353.554 0Z" fill="white"/>
+</svg>

package/example/assets/expo.icon/icon.json

@@ -0,0 +1,40 @@
+{
+  "fill" : {
+    "automatic-gradient" : "extended-srgb:0.00000,0.47843,1.00000,1.00000"
+  },
+  "groups" : [
+    {
+      "layers" : [
+        {
+          "image-name" : "expo-symbol 2.svg",
+          "name" : "expo-symbol 2",
+          "position" : {
+            "scale" : 1,
+            "translation-in-points" : [
+              1.1008400065293245e-05,
+              -16.046875
+            ]
+          }
+        },
+        {
+          "image-name" : "grid.png",
+          "name" : "grid"
+        }
+      ],
+      "shadow" : {
+        "kind" : "neutral",
+        "opacity" : 0.5
+      },
+      "translucency" : {
+        "enabled" : true,
+        "value" : 0.5
+      }
+    }
+  ],
+  "supported-platforms" : {
+    "circles" : [
+      "watchOS"
+    ],
+    "squares" : "shared"
+  }
+}

package/example/metro.config.js

@@ -0,0 +1,24 @@
+const { getDefaultConfig } = require('expo/metro-config');
+const path = require('path');
+
+const projectRoot = __dirname;
+const workspaceRoot = path.resolve(projectRoot, '..');
+
+const config = getDefaultConfig(projectRoot);
+
+config.watchFolders = [workspaceRoot];
+
+config.resolver.unstable_enableSymlinks = true;
+
+config.resolver.nodeModulesPaths = [
+  path.resolve(projectRoot, 'node_modules'),
+  path.resolve(workspaceRoot, 'node_modules'),
+];
+
+config.resolver.extraNodeModules = {
+  'beautiful-snackbar': workspaceRoot,
+  'react': path.resolve(projectRoot, 'node_modules/react'),
+  'react-native': path.resolve(projectRoot, 'node_modules/react-native'),
+};
+
+module.exports = config;

package/example/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "example",
+  "main": "expo-router/entry",
+  "version": "1.0.0",
+  "scripts": {
+    "start": "expo start",
+    "reset-project": "node ./scripts/reset-project.js",
+    "android": "expo start --android",
+    "ios": "expo start --ios",
+    "web": "expo start --web",
+    "lint": "expo lint"
+  },
+  "dependencies": {
+    "@react-navigation/bottom-tabs": "^7.15.5",
+    "@react-navigation/elements": "^2.9.10",
+    "@react-navigation/native": "^7.1.33",
+    "expo": "~55.0.25",
+    "expo-constants": "~55.0.16",
+    "expo-device": "~55.0.17",
+    "expo-font": "~55.0.8",
+    "expo-glass-effect": "~55.0.11",
+    "expo-image": "~55.0.10",
+    "expo-linking": "~55.0.15",
+    "expo-router": "~55.0.15",
+    "expo-splash-screen": "~55.0.21",
+    "expo-status-bar": "~55.0.6",
+    "expo-symbols": "~55.0.9",
+    "expo-system-ui": "~55.0.18",
+    "expo-web-browser": "~55.0.16",
+    "react": "19.2.0",
+    "react-dom": "19.2.0",
+    "react-native": "0.83.6",
+    "beautiful-snackbar": "..",
+    "react-native-gesture-handler": "~2.30.0",
+    "react-native-worklets": "0.7.4",
+    "react-native-reanimated": "4.2.1",
+    "react-native-safe-area-context": "~5.6.2",
+    "react-native-screens": "~4.23.0",
+    "react-native-web": "~0.21.0"
+  },
+  "devDependencies": {
+    "@types/react": "~19.2.2",
+    "typescript": "~5.9.2"
+  },
+  "private": true
+}

package/example/scripts/reset-project.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+
+/**
+ * This script is used to reset the project to a blank state.
+ * It deletes or moves the /src and /scripts directories to /example based on user input and creates a new /src/app directory with an index.tsx and _layout.tsx file.
+ * You can remove the `reset-project` script from package.json and safely delete this file after running it.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const readline = require("readline");
+
+const root = process.cwd();
+const oldDirs = ["src", "scripts"];
+const exampleDir = "example";
+const newAppDir = "src/app";
+const exampleDirPath = path.join(root, exampleDir);
+
+const indexContent = `import { Text, View, StyleSheet } from "react-native";
+
+export default function Index() {
+  return (
+    <View style={styles.container}>
+      <Text>Edit src/app/index.tsx to edit this screen.</Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+});
+`;
+
+const layoutContent = `import { Stack } from "expo-router";
+
+export default function RootLayout() {
+  return <Stack />;
+}
+`;
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+const moveDirectories = async (userInput) => {
+  try {
+    if (userInput === "y") {
+      // Create the app-example directory
+      await fs.promises.mkdir(exampleDirPath, { recursive: true });
+      console.log(`📁 /${exampleDir} directory created.`);
+    }
+
+    // Move old directories to new app-example directory or delete them
+    for (const dir of oldDirs) {
+      const oldDirPath = path.join(root, dir);
+      if (fs.existsSync(oldDirPath)) {
+        if (userInput === "y") {
+          const newDirPath = path.join(root, exampleDir, dir);
+          await fs.promises.rename(oldDirPath, newDirPath);
+          console.log(`➡️ /${dir} moved to /${exampleDir}/${dir}.`);
+        } else {
+          await fs.promises.rm(oldDirPath, { recursive: true, force: true });
+          console.log(`❌ /${dir} deleted.`);
+        }
+      } else {
+        console.log(`➡️ /${dir} does not exist, skipping.`);
+      }
+    }
+
+    // Create new /src/app directory
+    const newAppDirPath = path.join(root, newAppDir);
+    await fs.promises.mkdir(newAppDirPath, { recursive: true });
+    console.log("\n📁 New /src/app directory created.");
+
+    // Create index.tsx
+    const indexPath = path.join(newAppDirPath, "index.tsx");
+    await fs.promises.writeFile(indexPath, indexContent);
+    console.log("📄 src/app/index.tsx created.");
+
+    // Create _layout.tsx
+    const layoutPath = path.join(newAppDirPath, "_layout.tsx");
+    await fs.promises.writeFile(layoutPath, layoutContent);
+    console.log("📄 src/app/_layout.tsx created.");
+
+    console.log("\n✅ Project reset complete. Next steps:");
+    console.log(
+      `1. Run \`npx expo start\` to start a development server.\n2. Edit src/app/index.tsx to edit the main screen.\n3. Put all your application code in /src, only screens and layout files should be in /src/app.${
+        userInput === "y"
+          ? `\n4. Delete the /${exampleDir} directory when you're done referencing it.`
+          : ""
+      }`
+    );
+  } catch (error) {
+    console.error(`❌ Error during script execution: ${error.message}`);
+  }
+};
+
+rl.question(
+  "Do you want to move existing files to /example instead of deleting them? (Y/n): ",
+  (answer) => {
+    const userInput = answer.trim().toLowerCase() || "y";
+    if (userInput === "y" || userInput === "n") {
+      moveDirectories(userInput).finally(() => rl.close());
+    } else {
+      console.log("❌ Invalid input. Please enter 'Y' or 'N'.");
+      rl.close();
+    }
+  }
+);

package/example/src/app/_layout.tsx

@@ -0,0 +1,63 @@
+import { DarkTheme, DefaultTheme, ThemeProvider } from '@react-navigation/native';
+import React from 'react';
+import { View, Text, useColorScheme } from 'react-native';
+import { BeautifulSnackbar } from 'beautiful-snackbar';
+
+import { AnimatedSplashOverlay } from '@/components/animated-icon';
+import AppTabs from '@/components/app-tabs';
+
+const customTemplates = {
+  customCard: ({ item }: { item: any }) => (
+    <View style={{
+      marginHorizontal: 16,
+      padding: 16,
+      backgroundColor: '#31115F', // Premium dark purple/indigo
+      borderRadius: 16,
+      borderColor: '#4c1d95',
+      borderWidth: 1.5,
+      flexDirection: 'row',
+      alignItems: 'center',
+      justifyContent: 'space-between',
+      shadowColor: '#000',
+      shadowOffset: { width: 0, height: 6 },
+      shadowOpacity: 0.25,
+      shadowRadius: 10,
+      elevation: 8,
+    }}>
+      <View style={{ flex: 1, paddingRight: 8 }}>
+        <Text style={{ color: '#F3E8FF', fontWeight: '800', fontSize: 15, letterSpacing: -0.2 }}>
+          {item.message}
+        </Text>
+        {item.data?.subtitle && (
+          <Text style={{ color: '#C084FC', fontSize: 12, marginTop: 2, fontWeight: '500' }}>
+            {item.data.subtitle}
+          </Text>
+        )}
+      </View>
+      {item.data?.badge && (
+        <View style={{
+          backgroundColor: '#F59E0B',
+          paddingHorizontal: 8,
+          paddingVertical: 4,
+          borderRadius: 8,
+        }}>
+          <Text style={{ color: '#000', fontWeight: 'bold', fontSize: 11 }}>
+            {item.data.badge}
+          </Text>
+        </View>
+      )}
+    </View>
+  )
+};
+
+export default function TabLayout() {
+  const colorScheme = useColorScheme();
+
+  return (
+    <ThemeProvider value={colorScheme === 'dark' ? DarkTheme : DefaultTheme}>
+      <AnimatedSplashOverlay />
+      <AppTabs />
+      <BeautifulSnackbar templates={customTemplates} />
+    </ThemeProvider>
+  );
+}