@axzydev/axzy_ui_system 1.2.7 → 1.2.8

package/src/components/textarea/textarea.props.ts

@@ -1,15 +1,26 @@
 import { InputHTMLAttributes } from "react";
 
 export interface ITTextareaProps {
+  /** Controlled value of the textarea. */
   value?: string;
+  /** Callback fired when the value changes, receiving the new string. */
   onChange?: (value: string) => void;
+  /** Label text rendered above the textarea. */
   label?: string;
+  /** Placeholder text shown when the textarea is empty. */
   placeholder?: string;
+  /** Number of visible text rows (default 4). */
   rows?: number;
+  /** Disables the textarea when true. */
   disabled?: boolean;
+  /** Validation error message displayed below the textarea. */
   error?: string;
+  /** Additional CSS classes for the wrapper. */
   className?: string;
+  /** Name attribute for form submission and label association via `htmlFor`. */
   name?: string;
+  /** Maximum number of characters allowed. */
   maxLength?: number;
+  /** Resize behavior of the textarea: "none" | "vertical" | "horizontal" | "both". */
   resize?: "none" | "vertical" | "horizontal" | "both";
 }

package/src/components/textarea/textarea.tsx

@@ -10,6 +10,22 @@ const resizeMap = {
   both: "resize",
 };
 
+/**
+ * Multi-line text input with optional label, validation error display,
+ * character limit, and configurable resize behavior.
+ *
+ * @example
+ * <ITTextarea
+ *   name="bio"
+ *   label="Biography"
+ *   value={bio}
+ *   onChange={setBio}
+ *   maxLength={500}
+ *   rows={6}
+ *   resize="vertical"
+ *   error={bio.length > 500 ? "Max 500 characters" : undefined}
+ * />
+ */
 export default function ITTextarea({
   value,
   onChange,

package/src/components/theme-provider/themeProvider.doc.mdx

@@ -0,0 +1,75 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './themeProvider.stories';
+
+<Meta of={Stories} />
+
+# ITThemeProvider
+
+Root theme context that injects CSS custom properties into the entire component tree. Provides a centralized color palette with semantic tokens (primary, secondary, ternary, danger, success, info, alert, warning) plus overridable layout and table sections. Includes a floating action button that opens an in-app real-time theme designer drawer for live palette editing, dark/light/system mode switching, and preset themes.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `theme` | `Partial<ITThemePalette>` | — | Partial palette overrides merged with the default theme. Supports primary, secondary, ternary, danger, success, info, alert, warning, layout, and table colors. |
+| `children` | `React.ReactNode` | — | The subtree that receives the theme context and CSS variables. |
+| `showFab` | `boolean` | `false` | Whether to show the floating action button for opening the theme designer drawer. |
+
+### ITThemePalette Shape
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `primary` | `string` | Primary color for buttons, links, active states. |
+| `secondary` | `string` | Secondary/muted color. |
+| `ternary` | `string` | Tertiary accent color. |
+| `danger` | `string` | Destructive action color. |
+| `success` | `string` | Positive/success color. |
+| `info` | `string` | Informational color. |
+| `alert` | `string` | Alert/warning highlight color. |
+| `warning` | `string` | Cautionary yellow color. |
+| `layout.sidebarBg` | `string` | Sidebar background color. |
+| `layout.sidebarText` | `string` | Sidebar text color. |
+| `layout.navbarBg` | `string` | Navbar background color. |
+| `layout.navbarText` | `string` | Navbar text color. |
+| `table.headerBg` | `string` | Table header background color. |
+| `table.headerText` | `string` | Table header text color. |
+| `table.rowBg` | `string` | Table row background color. |
+| `table.rowText` | `string` | Table row text color. |
+
+## Usage
+
+```tsx
+import { ITThemeProvider } from '@axzydev/axzy_ui_system';
+
+<ITThemeProvider
+  theme={{
+    primary: '#8b5cf6',
+    success: '#22c55e',
+    layout: {
+      sidebarBg: '#0b1120',
+      sidebarText: '#94a3b8',
+    },
+  }}
+>
+  <App />
+</ITThemeProvider>
+
+<ITThemeProvider showFab>
+  <App />
+</ITThemeProvider>
+```
+
+## Notes
+
+- Wrap your entire application in `ITThemeProvider` once at the root level.
+- The default palette uses cyan (`#06b6d4`) as primary and supports all semantic color tokens.
+- **showFab** renders a floating palette icon. Clicking it opens a drawer with color pickers for each token, dark/light/system mode toggle, preset theme cards, live preview, and persistent localStorage save.
+- Theme preferences are persisted to localStorage under the `it-theme-palette` key.
+- All child components consume theme colors via CSS custom properties (e.g., `var(--it-primary)`) injected by the provider.
+- Custom palettes can override any subset of tokens; unset keys fall back to the default palette.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/theme-provider/themeProvider.props.ts

@@ -22,7 +22,10 @@ export interface ITThemePalette {
 }
 
 export interface ITThemeProviderProps {
+  /** Partial palette overrides merged with the default theme. Supports primary, secondary, tertiary, danger, success, info, alert, warning, layout, and table colors. */
   theme?: Partial<ITThemePalette>;
+  /** The subtree that receives the theme context and CSS variables. */
   children: React.ReactNode;
+  /** Whether to show the floating action button for opening the theme designer drawer. */
   showFab?: boolean;
 }

package/src/components/theme-provider/themeProvider.stories.tsx

@@ -0,0 +1,59 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import ITThemeProvider from './themeProvider';
+import ITCard from '../card/card';
+import ITButton from '../button/button';
+import ITText from '../text/text';
+
+const meta = {
+  title: 'Components/System/ITThemeProvider',
+  component: ITThemeProvider,
+  parameters: { layout: 'centered' },
+  tags: ['autodocs'],
+  argTypes: {
+    theme: { control: false, description: 'Custom theme palette to override defaults' },
+    children: { control: false, description: 'App content wrapped by the theme context' },
+    showFab: { control: 'boolean', description: 'Show the floating action button to open the theme designer' },
+  },
+} satisfies Meta<typeof ITThemeProvider>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const ThemedContent = () => (
+  <div className="p-8 space-y-4">
+    <ITCard title="Theme Demo" className="max-w-sm">
+      <div className="space-y-3">
+        <ITText as="p" className="text-sm text-slate-600 dark:text-slate-300">
+          This content is wrapped in ITThemeProvider and uses the current theme.
+        </ITText>
+        <div className="flex gap-2">
+          <ITButton label="Primary" color="primary" />
+          <ITButton label="Success" color="success" />
+          <ITButton label="Danger" color="danger" />
+        </div>
+      </div>
+    </ITCard>
+  </div>
+);
+
+export const Default: Story = {
+  args: {
+    children: <ThemedContent />,
+    showFab: false,
+  },
+};
+
+export const CustomPrimaryColor: Story = {
+  args: {
+    theme: { primary: '#8b5cf6', success: '#22c55e' },
+    children: <ThemedContent />,
+    showFab: false,
+  },
+};
+
+export const WithThemeFab: Story = {
+  args: {
+    children: <ThemedContent />,
+    showFab: true,
+  },
+};

package/src/components/theme-provider/themeProvider.tsx

@@ -246,6 +246,20 @@ const isVeryDarkColor = (hex: string) => {
   return brightness < 50;
 };
 
+/**
+ * Root theme context provider that injects CSS custom properties for all components,
+ * supports custom color palettes, dark/light mode, and an optional in-app theme designer FAB.
+ *
+ * @example
+ * <ITThemeProvider theme={{ primary: "#3b82f6", danger: "#ef4444" }}>
+ *   <App />
+ * </ITThemeProvider>
+ *
+ * @example
+ * <ITThemeProvider showFab={false}>
+ *   <Dashboard />
+ * </ITThemeProvider>
+ */
 export default function ITThemeProvider({
   children,
   theme,

package/src/components/time-picker/timePicker.doc.mdx

@@ -0,0 +1,68 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './timePicker.stories';
+
+<Meta of={Stories} />
+
+# ITTimePicker
+
+Time selection input with a dual-column dropdown (hours / minutes). Supports manual typing with auto-formatting to `HH:MM`, validation, 12h and 24h format display, configurable minute steps, and keyboard-friendly picker navigation.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | — | Form field name attribute and key for the change event. |
+| `value` | `string` | — | Controlled time value in `"HH:MM"` format. |
+| `label` | `string` | — | Label text displayed above the input. |
+| `placeholder` | `string` | `"HH:MM"` | Placeholder text when no value is set. |
+| `onChange` | `(e: any) => void` | — | Callback fired on valid time selection, receives event-like object with `target.name` and `target.value`. |
+| `onBlur` | `(e: any) => void` | — | Callback fired when the input loses focus. |
+| `required` | `boolean` | — | Marks the field as required. |
+| `touched` | `boolean` | — | Whether the input has been interacted with. |
+| `error` | `string \| boolean` | — | Validation error message or boolean to show error state. |
+| `disabled` | `boolean` | `false` | Disables the time picker when true. |
+| `className` | `string` | — | Additional CSS classes for the wrapper. |
+| `size` | `"small" \| "medium" \| "large"` | `"medium"` | Size preset controlling padding and font size. |
+| `variant` | `"primary" \| "secondary" \| "danger" \| "success" \| "warning" \| "info" \| "purple"` | `"primary"` | Style variant for the input. |
+| `color` | `"primary" \| "secondary" \| "danger" \| "success" \| "warning" \| "info" \| "purple" \| string` | `"primary"` | Theme color used for the dropdown highlight and confirm button. Accepts semantic keys or raw hex. |
+
+## Usage
+
+```tsx
+import { ITTimePicker } from '@axzydev/axzy_ui_system';
+
+<ITTimePicker
+  name="startTime"
+  label="Start Time"
+  value={startTime}
+  onChange={(e) => setStartTime(e.target.value)}
+  color="primary"
+/>
+
+<ITTimePicker
+  name="endTime"
+  label="End Time"
+  value={endTime}
+  onChange={(e) => setEndTime(e.target.value)}
+  error={isInvalid ? "Invalid time range" : undefined}
+  touched={true}
+/>
+```
+
+## Notes
+
+- The dropdown opens on input focus and can be navigated via scroll or keyboard.
+- Hour and minute columns scroll independently for quick selection.
+- A **Set** button at the bottom of the dropdown confirms the selection.
+- Supports both 12-hour and 24-hour format display via the internal formatting logic.
+- **minuteStep** is available internally (1, 5, 10, 15, 30 minutes) for granular control over the minute column.
+- Invalid times (e.g., "25:99") trigger validation and display an error state.
+- **touched** prop combined with an empty value or bad time forces error visibility.
+- Clearable via clearing the input field; the dropdown resets accordingly.
+- Colors available: primary, secondary, success, danger, warning, info, purple — plus any raw hex string.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/time-picker/timePicker.props.ts

@@ -1,16 +1,30 @@
 export interface ITTimePickerProps {
+  /** Form field name attribute and key for the change event. */
   name: string;
+  /** Controlled time value in "HH:MM" format. */
   value?: string;
+  /** Label text displayed above the input. */
   label?: string;
+  /** Placeholder text when no value is set (default "HH:MM"). */
   placeholder?: string;
+  /** Callback fired on valid time selection, receives event-like object with `target.name` and `target.value`. */
   onChange: (e: any) => void;
+  /** Callback fired when the input loses focus. */
   onBlur?: (e: any) => void;
+  /** Marks the field as required. */
   required?: boolean;
+  /** Whether the input has been touched (interacted with). */
   touched?: boolean;
+  /** Validation error message or boolean to show error state. */
   error?: string | boolean;
+  /** Disables the time picker when true. */
   disabled?: boolean;
+  /** Additional CSS classes for the wrapper. */
   className?: string;
+  /** Size preset: "small" | "medium" | "large". */
   size?: "small" | "medium" | "large";
+  /** Style variant for the input: "primary" | "secondary" | "danger" | "success" | "warning" | "info" | "purple". */
   variant?: "primary" | "secondary" | "danger" | "success" | "warning" | "info" | "purple";
+  /** Theme color used for the dropdown highlight and confirm button. Accepts semantic keys or raw hex. */
   color?: "primary" | "secondary" | "danger" | "success" | "warning" | "info" | "purple" | string;
 }

package/src/components/time-picker/timePicker.tsx

@@ -8,6 +8,27 @@ import { theme } from "@/theme/theme";
 import { ITTimePickerProps } from "./timePicker.props";
 import ITText from "@/components/text/text";
 
+/**
+ * Time selection input with a dual-column dropdown (hours / minutes).
+ * Supports manual typing with auto-formatting, validation, and keyboard-friendly picker.
+ *
+ * @example
+ * <ITTimePicker
+ *   name="startTime"
+ *   label="Start Time"
+ *   value={startTime}
+ *   onChange={(e) => setStartTime(e.target.value)}
+ *   color="primary"
+ * />
+ *
+ * @example
+ * <ITTimePicker
+ *   name="endTime"
+ *   value={endTime}
+ *   onChange={(e) => setEndTime(e.target.value)}
+ *   error={isInvalid ? "Invalid time range" : undefined}
+ * />
+ */
 export default function ITTimePicker({
   name,
   value,
@@ -197,7 +218,7 @@ export default function ITTimePicker({
               "cursor-pointer transition-colors",
               disabled
                 ? "text-slate-400 cursor-not-allowed"
-                : "text-slate-900 hover:text-slate-600"
+                : "text-slate-500 dark:text-slate-400 hover:text-slate-700 dark:hover:text-slate-200"
             )}
           />
         }

package/src/components/toast/toast.doc.mdx

@@ -0,0 +1,50 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './toast.stories';
+
+<Meta of={Stories} />
+
+# ITToast
+
+Floating notification with automatic dismiss and severity-based styling. Renders a positioned alert with an icon, message, and optional action button. Supports six on-screen positions and four semantic types — success, error, warning, and info — plus primary and danger variants.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `message` | `string` | — | Toast message text to display. |
+| `type` | `"success" \| "error" \| "warning" \| "info" \| "primary" \| "danger" \| string` | `"info"` | Severity type determining icon and background color. |
+| `duration` | `number` | `1500` | Auto-dismiss duration in milliseconds. |
+| `position` | `"top-right" \| "top-center" \| "top-left" \| "bottom-right" \| "bottom-center" \| "bottom-left"` | `"top-right"` | On-screen placement of the toast. |
+| `onClose` | `() => void` | — | Callback invoked after the toast finishes its dismiss transition animation. |
+
+## Usage
+
+```tsx
+import { ITToast } from '@axzydev/axzy_ui_system';
+
+<ITToast message="Operation completed successfully!" type="success" />
+
+<ITToast
+  message="There was a critical error processing your request."
+  type="error"
+  position="top-center"
+  duration={5000}
+  onClose={() => console.log("dismissed")}
+/>
+```
+
+## Notes
+
+- **type** values map to icons: `success` → check circle, `error` → times circle, `warning` → exclamation triangle, `info` → info circle. Unknown types fall back to the info icon.
+- **duration** starts counting after mount; the toast fades out with a 300ms transition after the timer expires.
+- The toast renders with `position: fixed`, so it overlays all page content at the chosen screen edge.
+- A close button (`×`) is always present for manual dismissal.
+- **onClose** fires after the fade-out transition completes — useful for unmounting the toast from a list.
+- For managing multiple toasts simultaneously, wrap with a toast provider context pattern outside `ITToast`.
+- All types also accept raw hex color strings, which get applied as background behind the themed icon.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/toast/toast.props.ts

@@ -1,7 +1,11 @@
 export interface ITToastProps {
+  /** Toast message text to display. */
   message: string;
+  /** Severity type determining icon and background color. One of "success", "error", "warning", "info", "primary", or "danger". @default "info" */
   type?: "success" | "error" | "warning" | "info" | "primary" | "danger" | string;
+  /** Auto-dismiss duration in milliseconds. @default 1500 */
   duration?: number;
+  /** On-screen placement. One of "top-right", "top-center", "top-left", "bottom-right", "bottom-center", "bottom-left". @default "top-right" */
   position?:
     | "top-right"
     | "top-center"
@@ -9,5 +13,6 @@ export interface ITToastProps {
     | "bottom-right"
     | "bottom-center"
     | "bottom-left";
+  /** Callback invoked after the toast finishes its dismiss transition animation. */
   onClose?: () => void;
 }

package/src/components/toast/toast.tsx

@@ -7,6 +7,27 @@ import { ITToastProps } from "./toast.props";
 import { FaTimesCircle, FaCheckCircle, FaExclamationTriangle, FaInfoCircle, FaTimes } from "react-icons/fa";
 import ITText from "@/components/text/text";
 
+/**
+ * ITToast — floating notification with automatic dismiss and severity-based styling.
+ *
+ * Renders a positioned alert with an icon, message, and close button.
+ * Supports "success", "error", "warning", "info", "primary", and "danger" types.
+ * Auto-dismisses after the configured duration and calls `onClose` on completion.
+ *
+ * @example
+ * // Basic info toast
+ * <ITToast message="Item saved" type="success" />
+ *
+ * @example
+ * // Error toast with custom position and duration
+ * <ITToast
+ *   message="Something went wrong"
+ *   type="error"
+ *   position="bottom-center"
+ *   duration={5000}
+ *   onClose={() => console.log("dismissed")}
+ * />
+ */
 export default function ITToast({
   message,
   type = "info",

package/src/components/tooltip/tooltip.doc.mdx

@@ -0,0 +1,47 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './tooltip.stories';
+
+<Meta of={Stories} />
+
+# ITTooltip
+
+Hover and focus tooltip that wraps a trigger element and displays contextual information in a small popup. Supports four placement positions with a triangular arrow pointing toward the trigger, configurable show delay, and customizable max-width.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `content` | `ReactNode` | — | The tooltip content to display on hover/focus. Accepts text or any ReactNode. |
+| `children` | `ReactNode` | — | The trigger element that reveals the tooltip on interaction. |
+| `position` | `"top" \| "bottom" \| "left" \| "right"` | `"top"` | Placement relative to children. |
+| `delay` | `number` | `200` | Delay in milliseconds before the tooltip becomes visible. |
+| `className` | `string` | — | Additional CSS classes applied to the wrapper element. |
+
+## Usage
+
+```tsx
+import { ITTooltip } from '@axzydev/axzy_ui_system';
+
+<ITTooltip content="Click to save" position="bottom">
+  <button>Save</button>
+</ITTooltip>
+
+<ITTooltip content={<span>Delete this item?</span>} position="top" delay={500}>
+  <IconButton icon={TrashIcon} />
+</ITTooltip>
+```
+
+## Notes
+
+- The tooltip appears after a **delay** (default 200ms) once the mouse enters the trigger, and disappears immediately on mouse leave.
+- **position** controls both the popup placement and the arrow direction: `top` (tooltip above, arrow pointing down), `bottom` (below, arrow up), `left` (to the left, arrow right), `right` (to the right, arrow left).
+- An optional triangular **arrow** is always rendered, styled with CSS borders pointing toward the trigger.
+- Tooltip body uses dark slate (`slate-800`) background with white text and rounded corners.
+- The wrapper is `inline-flex` by default, so it only takes as much width as the trigger — add `className` to constrain max-width on the tooltip content.
+- Supports keyboard focus: the tooltip also appears when the trigger element receives focus.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/tooltip/tooltip.props.ts

@@ -1,11 +1,17 @@
 import { ReactNode } from "react";
 
+/** Available placement positions relative to the trigger element. */
 export type TooltipPosition = "top" | "bottom" | "left" | "right";
 
 export interface ITTooltipProps {
+  /** The tooltip content to display on hover / focus. Accepts text or any ReactNode. */
   content: ReactNode;
+  /** The trigger element that reveals the tooltip on interaction. */
   children: ReactNode;
+  /** Placement relative to children. One of "top", "bottom", "left", "right". @default "top" */
   position?: TooltipPosition;
+  /** Delay in milliseconds before the tooltip becomes visible. @default 200 */
   delay?: number;
+  /** Additional CSS classes applied to the wrapper element. */
   className?: string;
 }

package/src/components/tooltip/tooltip.tsx

@@ -17,6 +17,25 @@ const arrowClasses: Record<TooltipPosition, string> = {
   right: "right-full top-1/2 -translate-y-1/2 border-t-4 border-b-4 border-r-4 border-transparent border-r-slate-800",
 };
 
+/**
+ * ITTooltip — hover / focus info tooltip with position control and optional arrow indicator.
+ *
+ * Wraps a trigger element and displays a small popup with explanatory text
+ * after a configurable delay. Supports "top", "bottom", "left", and "right" placement
+ * with a triangular arrow pointing toward the trigger.
+ *
+ * @example
+ * // Basic tooltip
+ * <ITTooltip content="Click to save" position="bottom">
+ *   <button>Save</button>
+ * </ITTooltip>
+ *
+ * @example
+ * // Tooltip with custom delay
+ * <ITTooltip content="Delete this item?" position="top" delay={500}>
+ *   <IconButton icon={TrashIcon} />
+ * </ITTooltip>
+ */
 export default function ITTooltip({
   content,
   children,

package/src/components/topbar/topbar.doc.mdx

@@ -0,0 +1,69 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './topbar.stories';
+
+<Meta of={Stories} />
+
+# ITTopBar
+
+Sticky top navigation bar with glassmorphism effect, logo, breadcrumb-style nav items, and a floating user avatar dropdown. Themed via CSS variables. Designed as a full-width header for dashboards and admin panels.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `logo` | `ReactNode` | — | Optional logo element (e.g. an `<img>` or SVG component). |
+| `logoText` | `string` | — | Text displayed next to the logo as the brand/title. |
+| `userMenu` | `object` | — | User dropdown configuration with name, email, avatar, and menu items. |
+| `userMenu.userName` | `string` | — | Display name shown in the trigger button and dropdown header. |
+| `userMenu.userEmail` | `string` | — | User email shown in the trigger button and dropdown header. |
+| `userMenu.userImage` | `string` | — | Optional avatar image URL. Falls back to a user-circle icon when omitted. |
+| `userMenu.menuItems` | `{ label: string; onClick: () => void }[]` | — | Array of dropdown menu actions. Items containing "salir", "cerrar", or "logout" are styled as destructive. |
+| `navItems` | `ITTopBarNavItem[]` | — | Desktop navigation items rendered beside the logo. Each has `id`, `label`, `icon`, and `action`. |
+| `onNavItemClick` | `(id: string) => void` | — | Callback fired when a navigation item is clicked. Receives the item's `id`. |
+| `showMobileMenuButton` | `boolean` | `false` | Whether to show the mobile hamburger menu toggle button. |
+| `onToggleMobileMenu` | `() => void` | — | Callback fired when the mobile menu toggle button is clicked. |
+
+## Usage
+
+```tsx
+import { ITTopBar } from '@axzydev/axzy_ui_system';
+import { FaChartBar, FaUserCog } from 'react-icons/fa';
+
+<ITTopBar
+  logoText="AXZY SYSTEM"
+  showMobileMenuButton
+  userMenu={{
+    userName: 'Alejandro G.',
+    userEmail: 'alejandro@axzy.io',
+    userImage: 'https://i.pravatar.cc/48',
+    menuItems: [
+      { label: 'Mi Perfil', onClick: () => {} },
+      { label: 'Configuración', onClick: () => {} },
+      { label: 'Cerrar Sesión', onClick: () => {} },
+    ],
+  }}
+  navItems={[
+    { id: '1', label: 'Monitor', icon: <FaChartBar />, action: () => {} },
+    { id: '2', label: 'Admin', icon: <FaUserCog />, action: () => {} },
+  ]}
+  onNavItemClick={(id) => console.log('Nav:', id)}
+  onToggleMobileMenu={() => setSidebarOpen(v => !v)}
+/>
+```
+
+## Notes
+
+- The bar uses a **glassmorphism** backdrop blur effect (`backdrop-blur-xl`), giving it a translucent appearance over scrolling content.
+- Navigation items support **icons** and highlight the active item with the primary color and an underline indicator.
+- The **user menu** dropdown opens on avatar click and closes on outside click (via `useClickOutside` hook).
+- Menu items containing "salir", "cerrar", or "logout" (case-insensitive) are automatically styled red as destructive actions.
+- When `userImage` is omitted, a `FaUserCircle` fallback icon is displayed.
+- **showMobileMenuButton** renders a hamburger icon (`<FaBars />`) for toggling a sidebar — the actual sidebar is managed externally via `onToggleMobileMenu`.
+- All color tokens are sourced from CSS custom properties set by `ITThemeProvider`.
+- The bar is `sticky` by default and sits at `top: 0` with a high z-index.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/topbar/topbar.props.ts

@@ -1,21 +1,36 @@
 export interface ITTopBarNavItem {
+  /** Unique identifier for the navigation item. */
   id: string;
+  /** Display label shown in the navigation bar. */
   label: string;
+  /** Optional icon element rendered beside the label. */
   icon?: any;
+  /** Click handler for this navigation item (legacy, prefer onNavItemClick). */
   action: () => void;
 }
 
 export interface ITTopBarProps {
+  /** Optional logo element (e.g. an `<img>` or SVG component). */
   logo?: any;
+  /** Text displayed next to the logo. */
   logoText?: string;
+  /** User dropdown configuration including name, email, avatar, and menu items. */
   userMenu?: {
+    /** Display name shown in the trigger button and dropdown header. */
     userName: string;
+    /** User email shown in the trigger button and dropdown header. */
     userEmail: string;
+    /** Optional avatar image URL. Falls back to a user-circle icon when omitted. */
     userImage?: string;
+    /** Array of dropdown menu actions: `{ label: string, onClick: () => void }`. Items containing "salir", "cerrar", or "logout" are styled as destructive. */
     menuItems: { label: string; onClick: () => void }[];
   };
+  /** Desktop navigation items rendered beside the logo. */
   navItems?: ITTopBarNavItem[];
+  /** Callback fired when a navigation item is clicked. Receives the item's `id`. */
   onNavItemClick?: (id: string) => void;
+  /** Whether to show the mobile hamburger menu toggle button. @default false */
   showMobileMenuButton?: boolean;
+  /** Callback fired when the mobile menu toggle button is clicked. */
   onToggleMobileMenu?: () => void;
 }