alope-ui 1.2.6 → 1.2.8

package/README.md

@@ -100,19 +100,16 @@ export default App;
 - [📄 Pagination](#pagination) - Page navigation controls
 - [📱 Bottom Navbar](#bottom-navbar) - Mobile bottom navigation bar
 
----
-
 ### Feedback Components
 
 - [⚠️ Alert](#alert) - Status messages and notifications
 - [🍞 Toast](#toast) - Temporary notification messages
+- [🗨️ Popover](#popover) - Contextual interactive content
 - [💡 Tooltip](#tooltip) - Contextual information on hover
 - [⏳ Spinner](#spinner) - Loading indicators
 - [💀 Skeleton](#skeleton) - Content loading placeholders
 - [📅 Date Picker](#datepicker) - Date selection calendar
 
----
-
 ### Data Display
 
 - [🏷️ Badge](#badge) - Status indicators and labels
@@ -124,8 +121,6 @@ export default App;
 - [🕒 Timeline](#timeline) - Chronological event display
 - [📚 Collection](#collection) - Grouped content or list display
 
----
-
 ### Form Controls
 
 - [☑️ Checkbox Input](#checkbox-input) - Multiple choice selections
@@ -138,8 +133,6 @@ export default App;
 - [🔢 Code Input](#codeinput) - Multi-field input for codes or OTPs
 - [🎚️ Slider](#slider) - Range or value selector
 
----
-
 ### Interactive Elements
 
 - [🔘 Button](#button) - Clickable actions
@@ -149,6 +142,20 @@ export default App;
 
 ---
 
+## 🎨 Customization
+
+### Theming
+
+- [⚙️ Setup](#setup) - Wrap your app with ThemeProvider
+- [🎯 Usage](#usage) - Access theme with useTheme hook
+- [🔌 Theme Hook API](#theme-hook-api) - Available properties and methods
+- [🎨 Styling Components](#styling-components) - Theme-aware styling with Tailwind
+- [💾 Persistence](#persistence) - Automatic localStorage integration
+- [📝 Example Implementation](#example-implementation) - Complete theming example
+- [✨ Best Practices](#best-practices) - Guidelines for optimal theming
+
+---
+
 ## 📖 Component Documentation
 
 ## Accordion
@@ -1229,6 +1236,150 @@ const BasicExample = () => {
 
 ---
 
+## Popover
+
+The Popover component displays contextual content or interactive elements over a trigger element. It’s useful for showing details, quick actions, or supplementary information without navigating away from the page.
+
+### Import
+
+```jsx
+import { Popover } from "alope-ui";
+```
+
+### Props
+
+| Prop          | Type                                     | Default   | Description                       |
+| ------------- | ---------------------------------------- | --------- | --------------------------------- |
+| `title`       | `string`                                 | `""`      | Popover header title              |
+| `content`     | `string`                                 | `""`      | Main Popover content              |
+| `placement`   | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'`   | Position relative to trigger      |
+| `trigger`     | `'click' \| 'hover'`                     | `'click'` | How Popover appears               |
+| `dismissible` | `boolean`                                | `false`   | Close by clicking outside         |
+| `disabled`    | `boolean`                                | `false`   | Disable Popover                   |
+| `offset`      | `string`                                 | `'8'`     | Distance from trigger (px)        |
+| `arrow`       | `'arrow' \| 'no-arrow'`                  | `'arrow'` | Show arrow pointing to trigger    |
+| `className`   | `string`                                 | `""`      | Additional CSS classes            |
+| `children`    | `React.ReactNode`                        | required  | Element that triggers the Popover |
+
+### Basic Popover
+
+```jsx
+<Popover
+  title="Default Popover"
+  content="This is the default popover, suitable for displaying brief information."
+>
+  <Button variant="solid">Default Popover</Button>
+</Popover>
+```
+
+### Placement
+
+```jsx
+<Popover placement="top" title="Top Popover" content="Appears above the button">
+  <Button>Top</Button>
+</Popover>
+
+<Popover placement="right" title="Right Popover" content="Appears to the right">
+  <Button>Right</Button>
+</Popover>
+
+<Popover placement="bottom" title="Bottom Popover" content="Appears below">
+  <Button>Bottom</Button>
+</Popover>
+
+<Popover placement="left" title="Left Popover" content="Appears to the left">
+  <Button>Left</Button>
+</Popover>
+```
+
+### Trigger
+
+```jsx
+<Popover trigger="click" title="Click Popover" content="Triggered by click">
+  <Button>Click me</Button>
+</Popover>
+
+<Popover trigger="hover" title="Hover Popover" content="Triggered on hover">
+  <Button>Hover me</Button>
+</Popover>
+```
+
+### Arrow
+
+```jsx
+<Popover arrow="arrow" title="Arrow Popover" content="Popover with arrow">
+  <Button>With arrow</Button>
+</Popover>
+
+<Popover arrow="no-arrow" title="No Arrow" content="Popover without arrow">
+  <Button>No arrow</Button>
+</Popover>
+```
+
+### Offset
+
+```jsx
+<Popover title="Default Offset" content="Default 8px offset">
+  <Button>Default offset</Button>
+</Popover>
+
+<Popover offset="16" title="Custom Offset" content="Custom 16px offset">
+  <Button>Custom offset</Button>
+</Popover>
+```
+
+### Custom Popover
+
+```jsx
+<Popover
+  content={
+    <div className="flex flex-col gap-3 w-64 max-w-full p-4 bg-white dark:bg-gray-900">
+      <div className="flex items-center gap-3">
+        <Avatar fallbackName="John Doe" />
+        <div className="flex flex-col">
+          <span className="font-semibold">Jane Doe</span>
+          <span className="text-sm text-gray-500">@janedoe</span>
+        </div>
+      </div>
+      <p className="text-sm text-gray-600">
+        Frontend developer passionate about React and UI design.
+      </p>
+      <Button variant="solid" variantType="info">
+        Follow
+      </Button>
+    </div>
+  }
+>
+  <Button>Custom Popover</Button>
+</Popover>
+```
+
+### Dismissible Popover
+
+```jsx
+<Popover
+  title="Dismissible Popover"
+  content="Click outside to close this popover."
+  dismissible
+>
+  <Button variant="solid" variantType="error">
+    Dismissible Popover
+  </Button>
+</Popover>
+```
+
+### Disabled Popover
+
+```jsx
+<Popover title="Disabled Popover" content="This popover is disabled." disabled>
+  <Button variant="solid" disabled>
+    Disabled
+  </Button>
+</Popover>
+```
+
+---
+
 ## Checkbox Input
 
 The CheckboxInput component provides checkbox functionality for selecting single or multiple options, with indeterminate state support.
@@ -7238,6 +7389,122 @@ const CompleteExample = () => {
 
 ---
 
+## Theming
+
+ALOPE UI provides built-in theming support with light and dark mode capabilities. The theming system is implemented using React Context, making it easy to toggle themes across your entire application.
+
+### Setup
+
+To enable theming in your application, wrap your app with the `ThemeProvider`:
+
+```tsx
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { ThemeProvider } from "./context/ThemeContext";
+import App from "./App";
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <ThemeProvider>
+      <App />
+    </ThemeProvider>
+  </StrictMode>
+);
+```
+
+### Usage
+
+Once your app is wrapped with `ThemeProvider`, you can access the current theme and toggle function using the `useTheme` hook:
+
+```tsx
+import { useTheme } from "./context/ThemeContext";
+import { Button } from "./components";
+
+function App() {
+  const { theme, toggleTheme } = useTheme();
+
+  return (
+    <div>
+      <Button onClick={toggleTheme}>
+        Toggle {theme.charAt(0).toUpperCase() + theme.slice(1)} Mode
+      </Button>
+
+      <p>Current theme: {theme}</p>
+    </div>
+  );
+}
+```
+
+### Theme Hook API
+
+The `useTheme` hook returns an object with the following properties:
+
+- **`theme`**: `'light' | 'dark'` - The current active theme
+- **`toggleTheme`**: `() => void` - Function to toggle between light and dark modes
+
+### Styling Components
+
+ALOPE UI components automatically respond to theme changes through Tailwind's `dark:` modifier. The theme is applied via a `dark` class on the root element.
+
+Example of theme-aware styling:
+
+```tsx
+<div className="bg-white dark:bg-gray-800">
+  <h1 className="text-gray-800 dark:text-white">Hello World</h1>
+  <p className="text-gray-600 dark:text-gray-300">
+    This text adapts to the current theme
+  </p>
+</div>
+```
+
+### Persistence
+
+The theme preference is automatically saved to `localStorage` and persists across browser sessions.
+
+### Example Implementation
+
+Here's a complete example showing theme integration:
+
+```tsx
+import { Button, Card } from "./components";
+import { useTheme } from "./context/ThemeContext";
+
+function App() {
+  const { theme, toggleTheme } = useTheme();
+
+  return (
+    <div className="min-h-screen bg-gradient-to-br from-primary/25 to-blue-100 dark:from-gray-900 dark:to-gray-700">
+      <div className="max-w-6xl mx-auto p-10">
+        <h1 className="text-4xl font-bold text-gray-800 dark:text-white">
+          ALOPE UI Library
+        </h1>
+
+        <Button onClick={toggleTheme} className="mt-4">
+          Toggle {theme.charAt(0).toUpperCase() + theme.slice(1)} Mode
+        </Button>
+
+        <Card
+          title="Theme-Aware Card"
+          description="This card automatically adapts to your theme preference"
+          titleClassName="dark:text-white"
+          descriptionClassName="dark:text-gray-300"
+          containerClassName="dark:bg-gray-800 dark:border-gray-700"
+        />
+      </div>
+    </div>
+  );
+}
+```
+
+### Best Practices
+
+1. **Wrap at the root level**: Place `ThemeProvider` at the top level of your application, typically in `main.tsx`
+2. **Use dark: modifiers**: Leverage Tailwind's `dark:` prefix for all theme-dependent styles
+3. **Consistent colors**: Use semantic color classes that work well in both themes
+4. **Test both modes**: Always test your components in both light and dark modes
+
+---
+
 ## 💡 Contributing
 
 We welcome contributions! If you want to add features, fix bugs, or improve documentation, feel free to fork this project and submit a pull request.

package/dist/components/Popover/Popover.d.ts

@@ -0,0 +1,14 @@
+import { default as React } from 'react';
+export type PopoverProps = {
+    title?: string;
+    content?: string | React.ReactNode;
+    placement?: "top" | "bottom" | "left" | "right";
+    trigger?: "click" | "hover";
+    dismissible?: boolean;
+    disabled?: boolean;
+    offset?: string;
+    arrow?: "arrow" | "no-arrow";
+    className?: string;
+    children: React.ReactNode;
+};
+export declare const Popover: React.FC<PopoverProps>;