groovinads-ui 1.9.98 → 1.9.99

package/README.md

@@ -13,6 +13,9 @@
 
 The library includes the following components:
 
+- [Context Providers](#context-providers):
+  - [ThemeProvider](#themeprovider): For managing application theme (light, dark, system).
+
 - [Buttons](#buttons):
   - [Button](#button): For user actions.
 
@@ -25,20 +28,24 @@ The library includes the following components:
 
 - [Inputs](#inputs):
   - [Checkbox](#checkbox): For multiple option selections.
+  - [Dropzone](#dropzone): For drag-and-drop file uploads with progress tracking.
   - [Input](#input): For user data entry.
   - [InputChip](#inputChip): For dynamically managing and displaying keywords.
-  - [InputEmail](#inputEmail): For managing email lists, including adding, displaying, and deleting email addresses.
+  - [InputEmail](#inputEmail): For managing email lists.
   - [Radio](#radio): For exclusive selections.
+  - [Slider](#slider): For selecting values using a slider control.
   - [Switch](#switch): For toggle states.
   - [Textarea](#textarea): For multiline text input.
 
 - [Labels](#labels):
   - [Alert](#alert): For displaying alerts.
+  - [BlockIcon](#blockicon): For displaying icons with block containers.
   - [Card](#card): For containing and grouping related content.
   - [EditableContent](#editablecontent): For inline editing of text content.
   - [Icon](#icon): For displaying icons.
   - [LoginSource](#loginsource): For show icons of login sources.
   - [PillComponent](#pillcomponent): For displaying information.
+  - [ProgressBar](#progressbar): For displaying progress indicators.
   - [Spinner](#spinner): For loading animations.
   - [StatusIcon](#statusicon): For displaying status icons.
 
@@ -166,6 +173,150 @@ yarn add groovinads-ui
 
 Here are examples of how to use the components included in the Groovinads UI library:
 
+## Context Providers
+
+### ThemeProvider
+
+The `ThemeProvider` manages the application's theme system, supporting three modes: `'light'`, `'dark'`, and `'default'` (system preference).
+
+#### Features
+
+- **Automatic theme persistence**: Theme preference is saved to browser cookies
+- **Cross-subdomain sharing**: Optional `rootDomain` prop enables theme sharing across subdomains
+- **System integration**: `'default'` mode respects the operating system theme
+- **SSR-safe**: Works correctly with Server-Side Rendering
+- **Auto-sync with DOM**: Automatically sets `data-theme` attribute on `document.documentElement`
+
+#### Basic Usage
+
+Wrap your application root with the `ThemeProvider`:
+
+```jsx
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { ThemeProvider } from 'groovinads-ui';
+import App from './App';
+
+ReactDOM.createRoot(document.getElementById('root')).render(
+  <React.StrictMode>
+    <ThemeProvider>
+      <App />
+    </ThemeProvider>
+  </React.StrictMode>
+);
+```
+
+#### Cross-Subdomain Theme Sharing
+
+By default, theme preferences are automatically shared across all Groovinads subdomains (`.groovinads.com`):
+
+```jsx
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { ThemeProvider } from 'groovinads-ui';
+import App from './App';
+
+// Default behavior - shares theme across all *.groovinads.com subdomains
+ReactDOM.createRoot(document.getElementById('root')).render(
+  <React.StrictMode>
+    <ThemeProvider>
+      <App />
+    </ThemeProvider>
+  </React.StrictMode>
+);
+```
+
+**Custom Domain or Disable Cross-Subdomain:**
+
+```jsx
+// Custom domain
+<ThemeProvider rootDomain=".example.com">
+  <App />
+</ThemeProvider>
+
+// Disable cross-subdomain (current domain only)
+<ThemeProvider rootDomain={null}>
+  <App />
+</ThemeProvider>
+```
+
+**Important Notes:**
+- **Default**: `.groovinads.com` - theme is shared across all subdomains
+- The `rootDomain` should start with a dot (`.`) to work across all subdomains
+- On localhost, the domain attribute is automatically omitted for local development
+- Cookie is stored with a 1-year expiration and `SameSite=Lax` for security
+
+#### Using the useTheme Hook
+
+Access and control the theme from any component:
+
+```jsx
+import React from 'react';
+import { useTheme } from 'groovinads-ui';
+
+function ThemeSelector() {
+  const { theme, setTheme, isLight, isDark, isDefault } = useTheme();
+
+  return (
+    <div>
+      <p>Current theme: {theme}</p>
+      <button onClick={() => setTheme('light')}>Light</button>
+      <button onClick={() => setTheme('dark')}>Dark</button>
+      <button onClick={() => setTheme('default')}>System</button>
+    </div>
+  );
+}
+```
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | **required** | Application content to wrap with theme context |
+| `initialTheme` | `'light' \| 'dark' \| 'default'` | `'default'` | Initial theme value (overrides cookie on mount) |
+| `rootDomain` | `string` | `'.groovinads.com'` | Root domain for cross-subdomain cookies. Theme is automatically shared across all subdomains. Set to `null` to disable cross-subdomain sharing. |
+
+#### useTheme Return Value
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `theme` | `'light' \| 'dark' \| 'default'` | Current active theme |
+| `setTheme` | `(theme: ThemeMode) => void` | Function to change theme |
+| `isLight` | `boolean` | `true` if theme is `'light'` |
+| `isDark` | `boolean` | `true` if theme is `'dark'` |
+| `isDefault` | `boolean` | `true` if theme is `'default'` |
+
+#### Implementation Notes
+
+- **Cookie Storage**: Theme preference is stored in a cookie named `theme_pref`
+- When theme is `'default'`: The `data-theme` attribute is removed from the HTML element and the cookie is deleted
+- When theme is `'light'` or `'dark'`: The `data-theme` attribute is set on `document.documentElement` and the preference is saved to a cookie with 1-year expiration
+- **Cross-Subdomain**: When `rootDomain` is provided, the cookie is set with the `domain` attribute to share across subdomains
+- **Localhost Handling**: On localhost, the domain attribute is automatically omitted to work in local development
+- **SSR-Safe**: The component checks for `window` existence before accessing `document.cookie` or `document`
+- **Security**: Cookies are set with `SameSite=Lax` and `path=/` for security and accessibility
+
+#### Integration with Navbar
+
+The `Navbar` component with `showUserMenu={true}` automatically includes a theme selector in the user dropdown menu when wrapped with `ThemeProvider`.
+
+```jsx
+import React from 'react';
+import { ThemeProvider, Navbar } from 'groovinads-ui';
+
+function App() {
+  return (
+    <ThemeProvider>
+      <Navbar
+        showUserMenu={true}
+        userData={userData}
+      />
+      {/* Rest of your app */}
+    </ThemeProvider>
+  );
+}
+```
+
 ## Buttons
 
 ### Button
@@ -829,6 +980,199 @@ export default ExampleInputChip;
 | `textError`    | String  | No       | n/a            | 'You must enter a valid email address' | Allows adding custom error text when entering an invalid email address.                                                                          |
 | `titleList`    | String  | No       | n/a            | 'Added emails'      					| Allows adding a custom text that will be shown as the title of the email list.                                                                   |
 
+### Dropzone
+
+A generic drag-and-drop file upload component with progress tracking, validation, and full control via props. Perfect for image, video, and document uploads.
+
+```jsx
+import React, { useState } from 'react';
+import { Dropzone } from 'groovinads-ui';
+
+const ExampleDropzone = () => {
+	const [files, setFiles] = useState([]);
+	const [showError, setShowError] = useState(false);
+	const [errorMessage, setErrorMessage] = useState('');
+
+	// Your upload function that returns a Promise
+	const handleUpload = async (file) => {
+		const formData = new FormData();
+		formData.append('file', file);
+
+		const response = await fetch('/api/upload', {
+			method: 'POST',
+			body: formData,
+		});
+
+		const result = await response.json();
+
+		// Return file metadata
+		return {
+			id: result.id,
+			url: result.url,
+			thumbnail: result.thumbnail,
+			name: file.name,
+			size: file.size,
+			type: file.type,
+			width: result.width,
+			height: result.height,
+		};
+	};
+
+	const handleSuccess = (result) => {
+		// Add to files list
+		setFiles((prev) => [...prev, result]);
+		console.log('File uploaded:', result);
+	};
+
+	const handleRemove = (file) => {
+		// Remove from files list
+		setFiles((prev) => prev.filter((f) => f.id !== file.id));
+	};
+
+	const handleError = (error, file) => {
+		console.error('Upload error:', error);
+		setShowError(true);
+		setErrorMessage('Upload failed. Please try again.');
+	};
+
+	const handleValidate = () => {
+		if (files.length === 0) {
+			setShowError(true);
+			setErrorMessage('You must upload at least one file');
+		}
+	};
+
+	return (
+		<Dropzone
+			// Data
+			files={files}
+
+			// Events
+			onUpload={handleUpload}
+			onSuccess={handleSuccess}
+			onRemove={handleRemove}
+			onError={handleError}
+
+			// Configuration
+			accept={{ 'image/*': ['.png', '.jpg', '.jpeg'] }}
+			maxSize={20 * 1024 * 1024} // 20MB
+			multiple={true}
+
+			// Validation
+			showError={showError}
+			requiredText={errorMessage}
+
+			// UI Texts
+			title="Drag and drop your image here"
+			subtitle="PNG, JPG up to 20MB"
+			buttonText="Browse file…"
+		/>
+	);
+};
+
+export default ExampleDropzone;
+```
+
+#### Props
+
+| Property              | Type     | Required | Default                              | Description                                                                                                              |
+| --------------------- | -------- | -------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
+| **Data**              |          |          |                                      |                                                                                                                          |
+| `files`               | Array    | No       | `[]`                                 | Array of uploaded files. Each file should have `id`, `url`, `name`, `size`, etc.                                        |
+| **Events**            |          |          |                                      |                                                                                                                          |
+| `onError`             | Function | No       | n/a                                  | Called on upload or validation errors. Receives `(error, file)`.                                                         |
+| `onRemove`            | Function | No       | n/a                                  | Called when user clicks remove button. Receives the file object.                                                         |
+| `onSuccess`           | Function | No       | n/a                                  | Called when upload succeeds. Receives the result from `onUpload`.                                                       |
+| `onUpload`            | Function | **Yes**  | n/a                                  | Async function that handles file upload. Must return a Promise with file metadata `{ id, url, name, size, ... }`.       |
+| **Configuration**     |          |          |                                      |                                                                                                                          |
+| `accept`              | Object   | No       | n/a                                  | Accepted file types in react-dropzone format: `{ 'image/*': ['.png', '.jpg'] }`.                                        |
+| `disabled`            | Boolean  | No       | `false`                              | Disable the dropzone.                                                                                                    |
+| `maxSize`             | Number   | No       | `20971520` (20MB)                    | Maximum file size in bytes.                                                                                              |
+| `multiple`            | Boolean  | No       | `true`                               | Allow multiple file uploads.                                                                                             |
+| `validator`           | Function | No       | n/a                                  | Custom file validator. Return `{ code, message }` for errors, `null` for valid files.                                   |
+| **Validation**        |          |          |                                      |                                                                                                                          |
+| `requiredText`        | String   | No       | n/a                                  | Error message displayed when `showError` is `true`. Used via the `data-error` attribute.                                |
+| `showError`           | Boolean  | No       | `false`                              | If `true`, displays the dropzone in error state with `not-validated` class. Controlled externally for validation.       |
+| **UI Texts**          |          |          |                                      |                                                                                                                          |
+| `buttonText`          | String   | No       | `'Browse file…'`                     | Browse button text.                                                                                                      |
+| `orLabel`             | String   | No       | `'or'`                               | Text for the separator between dropzone and browse button.                                                              |
+| `subtitle`            | String   | No       | n/a                                  | Subtitle text (e.g., file size limits).                                                                                  |
+| `title`               | String   | No       | `'Drag and drop your files here'`    | Main dropzone title.                                                                                                     |
+| `uploadingText`       | String   | No       | `'Uploading…'`                       | Text shown during upload.                                                                                                |
+| **UI Customization**  |          |          |                                      |                                                                                                                          |
+| `className`           | String   | No       | `''`                                 | Additional CSS classes.                                                                                                  |
+| `icon`                | String   | No       | `'cloud-arrow-up'`                   | FontAwesome icon name.                                                                                                   |
+| `iconScale`           | Number   | No       | `2`                                  | Icon size scale. Options: `0.7`, `1`, `2`, `3`, `4`.                                                                    |
+| **Format Validation** |          |          |                                      |                                                                                                                          |
+| `formatLabel`         | Function | No       | n/a                                  | Function to generate format label for display. Receives file, returns string.                                            |
+| `formatValidator`     | Function | No       | n/a                                  | Function to validate file format. Receives file, returns boolean.                                                        |
+
+#### File Object Structure
+
+The component normalizes file objects to ensure consistency. Your `onUpload` function should return:
+
+```javascript
+{
+  id: string | number,           // Unique identifier
+  url: string,                  // File URL (required)
+  thumbnail?: string,           // Thumbnail URL (optional)
+  name: string,                 // File name
+  size: number,                 // File size in bytes
+  type?: string,                // MIME type
+  width?: number,               // Image/video width
+  height?: number,              // Image/video height
+  duration?: number,            // Video duration
+}
+```
+
+The component also supports legacy formats with fields like `media`, `file_description`, `file_name`, `file_size`, etc.
+
+#### Examples
+
+**Image Upload**
+```jsx
+<Dropzone
+	files={images}
+	onUpload={uploadImage}
+	onSuccess={(result) => setImages([...images, result])}
+	onRemove={(file) => setImages(images.filter(f => f.id !== file.id))}
+	accept={{ 'image/*': ['.png', '.jpg', '.jpeg'] }}
+	maxSize={20 * 1024 * 1024}
+	title="Upload your creative"
+	subtitle="PNG, JPG up to 20MB"
+/>
+```
+
+**Video Upload (Single File)**
+```jsx
+<Dropzone
+	files={video ? [video] : []}
+	onUpload={uploadVideo}
+	onSuccess={setVideo}
+	onRemove={() => setVideo(null)}
+	accept={{ 'video/*': ['.mp4', '.mov'] }}
+	maxSize={100 * 1024 * 1024}
+	multiple={false}
+	icon="video"
+	title="Upload your video"
+	subtitle="MP4, MOV up to 100MB"
+/>
+```
+
+**Document Upload with Format Validation**
+```jsx
+<Dropzone
+	files={documents}
+	onUpload={uploadDocument}
+	onSuccess={(result) => setDocuments([...documents, result])}
+	accept={{ 'application/pdf': ['.pdf'] }}
+	formatValidator={(file) => file.size < 10 * 1024 * 1024}
+	formatLabel={(file) => `${(file.size / 1024).toFixed(0)} KB`}
+	title="Upload PDF document"
+	subtitle="PDF only, max 10MB"
+/>
+```
+
 ### Radio
 
 ```jsx
@@ -1307,37 +1651,144 @@ import { ModalComponent } from 'groovinads-ui';
 
 ## Navigation
 
-### Accordion
+### AccordionComponent
+
+A flexible accordion component built on top of react-bootstrap Accordion. Headers render as `<div>` elements (not buttons) to allow nesting interactive elements like buttons without HTML validation conflicts.
+
 ```jsx
 import React from 'react';
-import { Accordion } from 'react-bootstrap';
-import { AccordionComponent } from 'groovinads-ui';
-
-<AccordionComponent defaultActiveKey="0">
-	<Accordion.Item eventKey="0">
-		<Accordion.Header>Accordion Item #1</Accordion.Header>
-		<Accordion.Body>
-			This is the first item's accordion body.
-		</Accordion.Body>
-	</Accordion.Item>
-	<Accordion.Item eventKey="1">
-		<Accordion.Header>Accordion Item #2</Accordion.Header>
-		<Accordion.Body>
-			This is the second item's accordion body.
-		</Accordion.Body>
-	</Accordion.Item>
+import { AccordionComponent, AccordionItem } from 'groovinads-ui';
+
+// Basic usage
+<AccordionComponent defaultActiveKey="0" iconPosition="start">
+	<AccordionItem eventKey="0" header="Section 1">
+		This is the first item's accordion body.
+	</AccordionItem>
+	<AccordionItem eventKey="1" header="Section 2">
+		This is the second item's accordion body.
+	</AccordionItem>
+	<AccordionItem eventKey="2" header="Section 3">
+		This is the third item's accordion body.
+	</AccordionItem>
 </AccordionComponent>
 ```
 
-| Property          | Type              | Required | Options           | Default | Description                                                                                                |
-| ----------------- | ----------------- | -------- | ----------------- | ------- | ---------------------------------------------------------------------------------------------------------- |
-| `activeKey`       | String / String[] | No       | n/a               | n/a     | Currently active accordion item key(s). String for single, array for multiple when alwaysOpen is true.    |
-| `alwaysOpen`      | Boolean           | No       | `true` `false`    | `false` | Allow multiple accordion items to stay open at the same time.                                              |
-| `caretPosition`   | String            | No       | `start` `end`     | `start` | Position of the caret icon. `start` places it before the content, `end` places it after.                  |
-| `children`        | Node              | Yes      | n/a               | n/a     | Accordion.Item components from react-bootstrap.                                                            |
-| `className`       | String            | No       | n/a               | `''`    | Additional CSS classes.                                                                                    |
-| `defaultActiveKey`| String / String[] | No       | n/a               | n/a     | Default active key for uncontrolled mode. String for single, array for multiple when alwaysOpen is true.  |
-| `size`            | String            | No       | `sm` `md` `lg`    | `md`    | Size variant for the accordion.                                                                            |
+**Advanced usage with complex headers:**
+
+```jsx
+import React from 'react';
+import { AccordionComponent, AccordionItem } from 'groovinads-ui';
+import { Button } from 'groovinads-ui';
+
+const AdvancedAccordion = () => {
+	const handleEdit = (e, id) => {
+		e.stopPropagation(); // Prevent accordion toggle
+		console.log('Edit clicked for:', id);
+	};
+
+	return (
+		<AccordionComponent defaultActiveKey="0" iconPosition="start">
+			<AccordionItem
+				eventKey="0"
+				header={
+					<div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', width: '100%' }}>
+						<div>
+							<strong>Campaign Name</strong>
+							<div style={{ fontSize: '12px', color: '#888' }}>
+								Budget: $50,000 | Status: Active
+							</div>
+						</div>
+						<Button size="sm" onClick={(e) => handleEdit(e, 1)}>
+							Edit
+						</Button>
+					</div>
+				}
+			>
+				<p>Campaign details go here...</p>
+			</AccordionItem>
+			<AccordionItem
+				eventKey="1"
+				header={
+					<div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', width: '100%' }}>
+						<div>
+							<strong>Another Campaign</strong>
+							<div style={{ fontSize: '12px', color: '#888' }}>
+								Budget: $35,000 | Status: Scheduled
+							</div>
+						</div>
+						<Button size="sm" onClick={(e) => handleEdit(e, 2)}>
+							Edit
+						</Button>
+					</div>
+				}
+			>
+				<p>More campaign details...</p>
+			</AccordionItem>
+		</AccordionComponent>
+	);
+};
+```
+
+**Props for AccordionComponent:**
+
+| Property          | Type              | Required | Options       | Default | Description                                                                                                |
+| ----------------- | ----------------- | -------- | ------------- | ------- | ---------------------------------------------------------------------------------------------------------- |
+| `activeKey`       | String / String[] | No       | n/a           | n/a     | Currently active key(s) for controlled mode. Use with state to control which items are open. String for single item, array for multiple when alwaysOpen is true. |
+| `alwaysOpen`      | Boolean           | No       | `true` `false`| `false` | If true, allows multiple accordion items to stay open at the same time. If false, opening one closes others. |
+| `children`        | Node              | Yes      | n/a           | n/a     | AccordionItem components that define the accordion sections.                                               |
+| `className`       | String            | No       | n/a           | `''`    | Additional CSS classes to apply to the accordion container.                                                |
+| `defaultActiveKey`| String / String[] | No       | n/a           | n/a     | Default active key(s) for uncontrolled mode. Use string for single item, array for multiple when alwaysOpen is true. |
+| `iconPosition`    | String            | No       | `start` `end` | `start` | Position of the caret icon. `start` places it before the content (left), `end` places it after (right).   |
+| `onSelect`        | Function          | No       | n/a           | n/a     | Callback fired when the active item changes. Receives `(eventKey: string \| string[] \| null) => void`. Use with `activeKey` for controlled mode. |
+| `size`            | String            | No       | `sm` `md` `lg`| `md`    | Size variant for the accordion. `sm` for compact, `md` for default, `lg` for larger spacing.              |
+
+**Props for AccordionItem:**
+
+| Property   | Type   | Required | Description                                                                  |
+| ---------- | ------ | -------- | ---------------------------------------------------------------------------- |
+| `eventKey` | String | Yes      | Unique identifier for this accordion item. Used to control which item is open. |
+| `children` | Node   | Yes      | Content to display in the accordion body when the item is expanded.          |
+| `header`   | Node   | Yes      | Content to display in the accordion header. Can be text, JSX, or complex components. |
+
+**Controlled Mode Example:**
+
+```jsx
+import React, { useState } from 'react';
+import { AccordionComponent, AccordionItem } from 'groovinads-ui';
+
+const ControlledAccordion = () => {
+	const [activeKey, setActiveKey] = useState('0');
+
+	const handleSelect = (eventKey) => {
+		console.log('Selected:', eventKey);
+		setActiveKey(eventKey);
+	};
+
+	return (
+		<AccordionComponent activeKey={activeKey} onSelect={handleSelect}>
+			<AccordionItem eventKey="0" header="Section 1">
+				Content 1
+			</AccordionItem>
+			<AccordionItem eventKey="1" header="Section 2">
+				Content 2
+			</AccordionItem>
+			<AccordionItem eventKey="2" header="Section 3">
+				Content 3
+			</AccordionItem>
+		</AccordionComponent>
+	);
+};
+```
+
+**Key Features:**
+
+- **Headers as divs**: Headers render as `<div>` elements instead of `<button>` elements, allowing you to nest interactive elements (buttons, links, inputs) inside headers without HTML validation errors or click event conflicts.
+- **Flexible headers**: Headers accept any React node, so you can create complex, multi-line headers with custom layouts, icons, badges, and buttons.
+- **Icon positioning**: Caret icon can be positioned at the start (left) or end (right) of the header.
+- **Multiple open items**: Use `alwaysOpen={true}` to allow multiple sections to be expanded simultaneously.
+- **Controlled/Uncontrolled**: Works in both controlled (with `activeKey` and `onSelect` props) and uncontrolled (`defaultActiveKey`) modes. In controlled mode, use `activeKey` with `onSelect` to manage state externally.
+
+**Note:** When nesting buttons or other interactive elements in headers, make sure to call `e.stopPropagation()` in their click handlers to prevent the accordion from toggling when clicking the nested elements.
 
 ### Aside
 ```jsx
@@ -1368,15 +1819,39 @@ import { Navbar } from 'groovinads-ui';
 const NavbarComponent = () => {
 	const [show, setShow] = useState(false);
 
+	// Mock data - en una app real, esto vendría de tu AuthContext o similar
+	const applications = [
+		{
+			id_application: 1,
+			application_name: 'Dashboard',
+			application_url: '/dashboard',
+			application_icon: 'grid-2',
+			favorite: true,
+		},
+		// ... más aplicaciones
+	];
+
+	const userData = {
+		auth_data: {
+			oauth_username: 'John Doe',
+			oauth_picture: 'https://example.com/avatar.jpg',
+			email: 'john.doe@example.com',
+			oauth_name: 'Google',
+		},
+	};
+
 	return (
 		<div>
 			<Button onClick={() => setShow((prev) => !prev)}>Toggle Sidebar</Button>
 			<Navbar
-				logoUrl='https://ui.groovinads.com/assets/groovinads-logo.svg' // custom url
+				logoUrl='https://ui.groovinads.com/assets/groovinads-logo.svg'
 				showDeckMenu={true}
 				showUserMenu={true}
 				show={show}
 				setShow={setShow}
+				// Nuevas props: pasar datos para evitar fetches internos
+				applications={applications}
+				userData={userData}
 			>
 				<div>Custom Content</div>
 			</Navbar>
@@ -1387,15 +1862,72 @@ const NavbarComponent = () => {
 export default NavbarComponent;
 ```
 
-| Property       	| Type     | Required | Options        | Default 			 | Description                                                                                                   			|
-| ----------------- | -------- | -------- | -------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `children`     	| Node     | No       | n/a            | n/a     			 | Allows inserting custom content within the Navbar.                                                            			|
-| `logoUrl`      	| String   | No       | n/a            | Groovinads logo     | Accepts a URL to customize the logo image. If empty, show the Groovinads logo.                                			|
-| `logoUrlMobile`	| String   | No       | n/a            | Groovinads logo     | Accepts a URL for the mobile version of the logo. If not provided, uses `logoUrl` on mobile devices.          			|
-| `setShow`      	| Function | No       | n/a            | n/a     			 | Function to toggle the visibility state between visible and hidden.                                           			|
-| `show`         	| Boolean  | No       | `true` `false` | n/a      			 | Controls the visibility of the sidebar. If `true`, the sidebar is displayed; if `false`, it is hidden.        			|
-| `showDeckMenu` 	| Boolean  | No       | `true` `false` | `false` 			 | Controls the visibility of the deck menu in the navbar. If `true`, it is displayed; if `false`, it is hidden. 			|
-| `showUserMenu` 	| Boolean  | No       | `true` `false` | `false` 			 | Controls the visibility of the user menu. If `true`, the user menu is shown; if `false`, it is hidden.        			|
+| Property       	   | Type     | Required | Options        | Default 			      | Description                                                                                                   																		                                    |
+| -------------------- | -------- | -------- | -------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `applications` 	   | Array    | No       | n/a            | n/a 			          | Array of application objects for the deck menu. When provided, prevents internal API calls. Each object should have: `id_application`, `application_name`, `application_url`, `application_icon`, `favorite`. The component automatically maps `application_name` → `app_name` and `application_icon` → `app_icon_sm` internally. |
+| `applicationsLoading`| Boolean  | No       | `true` `false` | `false` 			      | Loading state for applications data. Shows skeleton loader when `true`.        																				                                                            |
+| `children`     	   | Node     | No       | n/a            | n/a     			      | Allows inserting custom content within the Navbar.                                                            																		                                    |
+| `favoritesTitle`     | String   | No       | n/a            | `'Favorites'` 		  | Title for the favorites section in the deck menu. Allows customization of the favorites label.                                                                                                                             |
+| `logoUrl`      	   | String   | No       | n/a            | Groovinads logo        | Accepts a URL to customize the logo image. If empty, show the Groovinads logo.                                																	                                        |
+| `logoUrlMobile`	   | String   | No       | n/a            | Groovinads logo        | Accepts a URL for the mobile version of the logo. If not provided, uses `logoUrl` on mobile devices.          																	                                        |
+| `onApplicationClick` | Function | No       | n/a            | n/a 			          | Callback fired when user clicks an application. Receives the application object. If not provided, opens application in new tab (default behavior).                                                                          |
+| `onFavoriteToggle`   | Function | No       | n/a            | n/a 			          | Callback fired when user toggles favorite status. Receives `(applicationId, isFavorite)`. Must return a Promise. If not provided, makes internal API call (default behavior).                                              |
+| `setShow`      	   | Function | No       | n/a            | n/a     			      | Function to toggle the visibility state of the sidebar. When provided (along with `show`), the sidebar toggle button is rendered. When omitted, the button is hidden.        	                                            |
+| `show`         	   | Boolean  | No       | `true` `false` | n/a      			      | Controls the visibility of the sidebar. When provided (along with `setShow`), the sidebar toggle button is rendered. When omitted, the button is hidden.        					                                        |
+| `showDeckMenu` 	   | Boolean  | No       | `true` `false` | `false` 			      | Controls the visibility of the deck menu in the navbar. If `true`, it is displayed; if `false`, it is hidden. Applications open in a new tab when clicked. 																	                                            |
+| `showUserMenu` 	   | Boolean  | No       | `true` `false` | `false` 			      | Controls the visibility of the user menu. If `true`, the user menu is shown; if `false`, it is hidden.        																	                                            |
+| `userData` 	       | Object   | No       | n/a            | n/a 			          | User data object for the user menu. When provided, prevents internal API calls. Should contain `auth_data` with: `oauth_username`, `oauth_picture`, `email`, `oauth_name`.                                                 |
+| `userDataLoading`    | Boolean  | No       | `true` `false` | `false` 			      | Loading state for user data. Shows skeleton loader when `true`.        																					                                                                |
+
+**⚠️ Important Note on Data Props:**
+- When `showDeckMenu={true}` is used **without** providing `applications` prop, the component will make an internal API call to `/v2/applications`
+- When `showUserMenu={true}` is used **without** providing `userData` prop, the component will make an internal API call to `/v2/auth/status`
+- To avoid duplicate API calls in your app, always provide `applications` and `userData` props from your app's state management (e.g., AuthContext, Redux, etc.)
+
+**💡 Event Handlers for Custom Navigation:**
+
+If you need to integrate the Navbar with your application's routing (e.g., react-router) or handle favorites with your own state management, use the event handler props:
+
+```jsx
+import { useNavigate } from 'react-router-dom';
+
+const NavbarComponent = () => {
+	const navigate = useNavigate();
+	const [applications, setApplications] = useState([...]);
+
+	// Custom navigation handler
+	const handleApplicationClick = (app) => {
+		// Navigate using react-router instead of opening new tab
+		navigate(app.application_url);
+	};
+
+	// Custom favorite toggle handler
+	const handleFavoriteToggle = async (appId, isFavorite) => {
+		// Update in your API
+		await updateFavoriteAPI(appId, isFavorite);
+
+		// Update local state
+		setApplications(prev =>
+			prev.map(app =>
+				app.id_application === appId
+					? { ...app, favorite: isFavorite }
+					: app
+			)
+		);
+	};
+
+	return (
+		<Navbar
+			showDeckMenu={true}
+			applications={applications}
+			onApplicationClick={handleApplicationClick}
+			onFavoriteToggle={handleFavoriteToggle}
+		/>
+	);
+};
+```
+
+**Note:** If you don't provide these handlers, the component uses default behavior (opens in new tab for clicks, makes internal API call for favorites).
 
 ### Pagination