@godgpt/lumen-popup

A beautiful, animated popup component for Lumen with full i18n support using react-i18next.

✨ Features

• 🌍 Full i18n Support - Works seamlessly with react-i18next
• 🎨 Beautiful Animations - Smooth transitions with Framer Motion
• 📱 Responsive - Works on all screen sizes
• 📐 Flexible Positioning - Static or dynamic vertical offset support
• ⚡ Lightweight - Minimal dependencies
• 🎯 TypeScript - Full type definitions included
• 🔧 Zero Config - Just install and use

📦 Installation

npm install @godgpt/lumen-popup
# or
yarn add @godgpt/lumen-popup
# or
pnpm add @godgpt/lumen-popup

🚀 Quick Start

1. Install Dependencies

The component requires these peer dependencies:

npm install react-i18next i18next framer-motion lucide-react

2. Setup i18n (if not already configured)

// src/i18n/config.ts
import i18n from "i18next";
import { initReactI18next } from "react-i18next";

i18n.use(initReactI18next).init({
  resources: {
    en: {
      translation: {
        lumenPopup: {
          title: "Introducing: Lumen",
          description:
            "The most comprehensive astrology app, combining <bold>Bazi</bold>, <bold>Eastern</bold>, and <bold>Western</bold> astrology to give you a complete reading of your universe, with personalized <bold>GodGPT</bold> guidance when you need deeper understanding. <bold>Completely free</bold>. ⭐",
          cta: "Join the Waitlist",
        },
      },
    },
  },
  lng: "en",
  fallbackLng: "en",
  interpolation: {
    escapeValue: false,
  },
});

export default i18n;

// src/main.tsx
import "./i18n/config";
import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

3. Add Translation Keys

Add these keys to your locale files (en.json, es.json, etc.):

{
  "lumenPopup": {
    "title": "Introducing: Lumen",
    "description": "The most comprehensive astrology app, combining <bold>Bazi</bold>, <bold>Eastern</bold>, and <bold>Western</bold> astrology...",
    "cta": "Join the Waitlist"
  }
}

Note: The <bold> tags in the description are parsed by the component and rendered as bold text.

4. Use the Component

import LumenPopup from "@godgpt/lumen-popup";

function App() {
  return (
    <div>
      <LumenPopup />
      {/* Your app content */}
    </div>
  );
}

export default App;

That's it! The popup will automatically:

• ✅ Show after page load (with 300ms delay)
• ✅ Use your current i18n language
• ✅ Display with smooth animations
• ✅ Be fully responsive

🌍 Internationalization

The component automatically uses react-i18next from your app's context. It requires these translation keys:

| Key | Description | Type | | ------------------------ | ------------------------------------------ | -------- | | lumenPopup.title | Popup title | string | | lumenPopup.description | Popup description (supports <bold> tags) | string | | lumenPopup.cta | Button text | string |

Supported Languages (Example Translations Included)

Example translations for multiple languages:

English (en.json)

{
  "lumenPopup": {
    "title": "Introducing: Lumen",
    "description": "The most comprehensive astrology app...",
    "cta": "Join the Waitlist"
  }
}

Spanish (es.json)

{
  "lumenPopup": {
    "title": "Presentamos: Lumen",
    "description": "La aplicación de astrología más completa...",
    "cta": "Únete a la Lista de Espera"
  }
}

Chinese Simplified (zh-CN.json)

{
  "lumenPopup": {
    "title": "隆重推出：Lumen",
    "description": "最全面的占星应用...",
    "cta": "加入候补名单"
  }
}

Chinese Traditional (zh-TW.json)

{
  "lumenPopup": {
    "title": "隆重推出：Lumen",
    "description": "最全面的占星應用...",
    "cta": "加入候補名單"
  }
}

Bold Text Formatting

The description supports <bold> tags for inline bold formatting:

{
  "description": "Text with <bold>bold content</bold> and <bold>more bold</bold> text."
}

Renders as: Text with bold content and more bold text.

🎨 Customization

The component uses Tailwind CSS utility classes. Make sure your tailwind.config.js includes:

export default {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/@godgpt/lumen-popup/dist/**/*.{js,mjs}",
  ],
  // ... rest of config
};

Styling

The component uses these design tokens:

• Background: #303030
• Button: #575757 with #757575 border
• Text: White with various opacity levels
• Max Width: max-w-sm (384px)

To customize styling, you can wrap the component and override with CSS or create a fork.

📋 Requirements

• React: >=18.0.0
• react-i18next: >=13.0.0
• i18next: >=23.0.0
• framer-motion: Installed automatically
• lucide-react: Installed automatically
• Tailwind CSS: Required for styling

🔧 API

import LumenPopup from "@godgpt/lumen-popup";

<LumenPopup />;

Props

| Prop | Type | Default | Description | | ---- | ---- | ------- | ----------- | | verticalOffset | number | 0 | Static vertical offset in pixels. Positive values move the popup down, negative values move it up. | | setVerticalOffset | (dimensions) => number | undefined | Dynamic offset function that receives the popup's bounding rect and returns the offset. Takes priority over verticalOffset. |

setVerticalOffset Dimensions Object

{
  x: number;      // Left position of the popup
  y: number;      // Top position of the popup
  width: number;  // Width of the popup
  height: number; // Height of the popup
}

Usage Examples

Basic (no offset):

<LumenPopup />

Static offset (move down 100px):

<LumenPopup verticalOffset={100} />

Static offset (move up 50px):

<LumenPopup verticalOffset={-50} />

Dynamic offset based on popup dimensions:

<LumenPopup 
  setVerticalOffset={({ height }) => {
    // Move up by 20% of popup height
    return -(height * 0.2);
  }}
/>

Responsive offset (avoid navigation bar):

<LumenPopup 
  setVerticalOffset={({ y }) => {
    const navHeight = 80;
    // If popup overlaps nav, push it down
    if (y < navHeight + 20) {
      return navHeight + 20 - y;
    }
    return 0;
  }}
/>

The component automatically integrates with your app's react-i18next context.

📁 What's Included

• ✅ Compiled JavaScript (ESM & CJS)
• ✅ TypeScript definitions
• ✅ GIF asset
• ✅ Source maps

🛠️ Development

Building the Package

# Install dependencies
npm install

# Build for production
npm run build

# Watch mode (for development)
npm run dev

Publishing to npm

# Login to npm (first time only)
npm login

# Publish
npm publish --access public

📝 Example Translations

Full example translation files are available in the src/locales/ directory:

• en.json - English
• es.json - Spanish
• zh-CN.json - Simplified Chinese
• zh-TW.json - Traditional Chinese

⚡ Performance

• Bundle Size: ~15KB gzipped (excluding dependencies)
• GIF Preloading: The component preloads the animated GIF before showing
• Lazy Rendering: Only renders when open
• No Re-renders: Optimized with React hooks

🐛 Troubleshooting

Popup Not Showing

1. Ensure i18next is initialized before the component renders
2. Check that translation keys exist in your locale files
3. Verify Tailwind CSS is properly configured

Translations Not Working

// Make sure i18n is initialized in your entry file
import "./i18n/config"; // ← Add this at the top of main.tsx

Styling Issues

Add the package to your Tailwind content paths:

content: ["./node_modules/@godgpt/lumen-popup/dist/**/*.{js,mjs}"];

TypeScript Errors

If you get type errors, ensure you have the peer dependencies installed:

npm install --save-dev @types/react @types/react-dom

📄 License

MIT © GodGPT Team

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📧 Support

For issues and questions, please open an issue on GitHub.

Made with ❤️ by the GodGPT Team