@axzydev/axzy_ui_system 1.2.6 → 1.2.8

package/src/components/input/input.doc.mdx

@@ -0,0 +1,70 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './input.stories';
+
+<Meta of={Stories} />
+
+# ITInput
+
+A versatile form input component supporting text, password, email, number, textarea, checkbox, and radio types. Features labels, validation errors, left/right icons, helper text with character count, currency formatting, and configurable sizes.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | required | Field name used for form identification. |
+| `type` | `'text' \| 'password' \| 'number' \| 'email' \| 'checkbox' \| 'radio' \| 'textarea'` | `'text'` | Input type. |
+| `label` | `string` | `undefined` | Label displayed above the input. |
+| `placeholder` | `string` | `undefined` | Placeholder text. |
+| `value` | `any` | `undefined` | Current input value. |
+| `onChange` | `(event: any) => void` | required | Change event handler. |
+| `onBlur` | `(event) => void` | `undefined` | Blur event handler. |
+| `onKeyDown` | `(event) => void` | `undefined` | Keydown event handler. |
+| `error` | `string \| boolean` | `undefined` | Validation error message. Pass `true` for generic error styling. |
+| `touched` | `boolean` | `undefined` | Whether the field has been touched by the user. |
+| `required` | `boolean` | `false` | Mark the field as required (adds asterisk to label). |
+| `disabled` | `boolean` | `false` | Disable the input. |
+| `size` | `SizesTypes` | `'md'` | Size preset: `xs`, `sm`, `md`, `lg`, `xl`. |
+| `variant` | `ColorsTypes` | `undefined` | Color variant from the theme palette. |
+| `iconLeft` | `ReactNode` | `undefined` | Icon element rendered on the left side. |
+| `iconRight` | `ReactNode` | `undefined` | Icon element rendered on the right side. |
+| `maxLength` | `number` | `undefined` | Maximum allowed character length. |
+| `minLength` | `number` | `undefined` | Minimum allowed character length. |
+| `showHintLength` | `boolean` | `false` | Show character count hint below the input. |
+| `currencyFormat` | `boolean` | `false` | Enable currency formatting for number inputs (MX locale). |
+| `formatNumber` | `boolean` | `false` | Enable number formatting on blur. |
+| `autoFocus` | `boolean` | `false` | Auto-focus the input on mount. |
+| `focusContent` | `boolean` | `false` | Select all content on click/focus. |
+| `readOnly` | `boolean` | `false` | Render the input in read-only mode. |
+| `min` | `number` | `undefined` | Minimum numeric value for number inputs. |
+| `max` | `number` | `undefined` | Maximum numeric value for number inputs. |
+| `rows` | `number` | `undefined` | Number of visible rows for textarea. |
+| `checked` | `boolean` | `undefined` | Checked state for checkbox and radio types. |
+| `containerClassName` | `string` | `undefined` | Additional CSS classes for the outer container. |
+| `labelClassName` | `string` | `undefined` | Additional CSS classes for the label. |
+| `className` | `string` | `undefined` | Additional CSS classes for the input element. |
+| `onClick` | `() => void` | `undefined` | Click handler for the input. |
+
+## Usage
+
+```tsx
+import { ITInput } from '@axzydev/axzy_ui_system';
+
+<ITInput name="email" label="Email" type="email" placeholder="example@mail.com" />
+<ITInput name="password" label="Password" type="password" iconLeft={<FaLock />} />
+<ITInput name="bio" label="Bio" type="textarea" rows={4} />
+<ITInput name="qty" label="Quantity" type="number" min={0} max={100} />
+```
+
+## Notes
+
+- Error message only displays when both `error` and `touched` are truthy.
+- `showHintLength` with `maxLength` displays a counter (e.g. "45/200").
+- Currency formatting uses MX locale by default when `currencyFormat` is true.
+- Icons rendered via `iconLeft`/`iconRight` can be clickable React nodes (e.g. a toggle visibility button).
+- Checkbox and radio types render inline labels instead of stacked layout.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/input/input.props.ts

@@ -3,7 +3,9 @@ import { SizesTypes } from "@app/types/sizes.types";
 import { ReactNode } from "react";
 
 export interface ITInputProps {
+  /** Field name used for form identification */
   name: string;
+  /** Input type: "text" | "password" | "number" | "email" | "checkbox" | "radio" | "textarea" */
   type?:
     | "text"
     | "password"
@@ -12,38 +14,68 @@ export interface ITInputProps {
     | "checkbox"
     | "radio"
     | "textarea";
+  /** Label displayed above the input */
   label?: string;
+  /** Enable currency formatting for number inputs (MX locale) */
   currencyFormat?: boolean;
+  /** Placeholder text */
   placeholder?: string;
+  /** Current input value */
   value?: any;
+  /** Change event handler */
   onChange: (event: any) => void;
+  /** Blur event handler */
   onBlur?: (
     event:
       | React.FocusEvent<HTMLInputElement>
       | React.FocusEvent<HTMLTextAreaElement, Element>
   ) => void;
+  /** Keydown event handler */
   onKeyDown?: (event: React.KeyboardEvent) => void;
+  /** Show character count hint below the input */
   showHintLength?: boolean;
+  /** Maximum allowed character length */
   maxLength?: number;
+  /** Minimum allowed character length */
   minLength?: number;
+  /** Color variant from the theme palette */
   variant?: ColorsTypes;
+  /** Size preset: "xs" | "sm" | "md" | "lg" | "xl" */
   size?: SizesTypes;
+  /** Disable the input */
   disabled?: boolean;
+  /** Additional CSS classes for the outer container */
   containerClassName?: string;
+  /** Additional CSS classes for the label */
   labelClassName?: string;
+  /** Additional CSS classes for the input element */
   className?: string;
+  /** Whether the field has been touched by the user */
   touched?: boolean;
+  /** Validation error message. Pass `true` for a generic error, or a string for a custom message */
   error?: string | boolean;
+  /** Mark the field as required */
   required?: boolean;
-  formatNumber?:boolean;
+  /** Enable number formatting on blur */
+  formatNumber?: boolean;
+  /** Auto-focus the input on mount */
   autoFocus?: boolean;
-  focusContent?:boolean;
+  /** Select all content on click */
+  focusContent?: boolean;
+  /** Click handler for the input */
   onClick?: () => void;
+  /** Icon element rendered on the left side of the input */
   iconLeft?: ReactNode;
+  /** Icon element rendered on the right side of the input */
   iconRight?: ReactNode;
+  /** Checked state for checkbox and radio types */
   checked?: boolean;
+  /** Number of visible rows for textarea type */
   rows?: number;
+  /** Minimum numeric value for number inputs */
   min?: number;
+  /** Maximum numeric value for number inputs */
   max?: number;
+  /** Render the input in read-only mode */
   readOnly?: boolean;
 }

package/src/components/input/input.tsx

@@ -6,6 +6,35 @@ import { theme } from "@/theme/theme";
 import { disabledOverlay, iconAbsoluteLeft, iconAbsoluteRight, inputError, inputLabel } from "@/utils/styles";
 import ITText from "@/components/text/text";
 
+/**
+ * Text input component with label, validation error display, icon slots,
+ * and helper text. Supports text, password, email, number (with currency
+ * and thousand formatting), checkbox, radio, and textarea types.
+ *
+ * @example
+ * <ITInput
+ *   name="email"
+ *   label="Email Address"
+ *   type="email"
+ *   placeholder="you@example.com"
+ *   value={email}
+ *   onChange={handleChange}
+ *   error={errors.email}
+ *   required
+ * />
+ *
+ * @example
+ * <ITInput
+ *   name="amount"
+ *   label="Amount"
+ *   type="number"
+ *   currencyFormat
+ *   iconLeft={<FaDollarSign />}
+ *   value={amount}
+ *   onChange={handleChange}
+ *   maxLength={10}
+ * />
+ */
 export default function ITInput({
   name,
   type = "text",

package/src/components/layout/layout.doc.mdx

@@ -0,0 +1,51 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './layout.stories';
+
+<Meta of={Stories} />
+
+# ITLayout
+
+The application shell layout component that combines a topbar, sidebar, and main content area into a full-page interface. The sidebar supports collapse/expand via hover, and all visual styles are driven by ITThemeProvider CSS variables.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `topBar` | `ITTopBarProps` | required | Top bar configuration including logo, nav items, and user menu. |
+| `sidebar` | `ITSidebarProps` | required | Sidebar configuration including navigation items. |
+| `children` | `ReactNode` | required | Main content rendered in the center area. |
+| `className` | `string` | `undefined` | Additional CSS classes for the outermost wrapper. |
+| `contentClassName` | `string` | `undefined` | Additional CSS classes for the content container. |
+
+## Usage
+
+```tsx
+import { ITLayout } from '@axzydev/axzy_ui_system';
+
+<ITLayout
+  topBar={{
+    logoText: 'AXZY',
+    userMenu: { userName: 'Jane', userEmail: 'jane@axzy.io', menuItems: [...] },
+    navItems: [...]
+  }}
+  sidebar={{
+    navigationItems: [...]
+  }}
+>
+  <div>Your page content here</div>
+</ITLayout>
+```
+
+## Notes
+
+- The topbar spans the full viewport width at the top of the page.
+- The sidebar sits under the topbar on the left and floats over content when expanded via hover.
+- Sidebar in collapsed state shows only icons; expanding reveals labels.
+- Themed entirely through CSS custom properties from ITThemeProvider.
+- Includes mobile responsive behavior with a hamburger-style toggle.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/layout/layout.props.ts

@@ -2,9 +2,14 @@ import { ITTopBarProps } from "../topbar/topbar.props";
 import { ITSidebarProps } from "../sidebar/sidebar.props";
 
 export interface ITLayoutProps {
+  /** Top bar configuration and props */
   topBar: ITTopBarProps;
+  /** Sidebar configuration and props */
   sidebar: ITSidebarProps;
+  /** Main content rendered in the center area */
   children: React.ReactNode;
+  /** Additional CSS classes for the outermost wrapper */
   className?: string;
+  /** Additional CSS classes for the content container */
   contentClassName?: string;
 } 

package/src/components/layout/layout.tsx

@@ -3,6 +3,31 @@ import clsx from "clsx";
 import ITTopBar from "../topbar/topbar";
 import ITSidebar from "../sidebar/sidebar";
 import { ITLayoutProps } from "./layout.props";
+import { theme } from "@/theme/theme";
+
+/**
+ * Main application shell with sidebar, topbar, and content area.
+ * Provides a responsive layout with a collapsible desktop sidebar,
+ * a sliding mobile sidebar overlay, and a scrollable main content region.
+ *
+ * @example
+ * <ITLayout
+ *   topBar={{ title: "Dashboard", userMenu: [...] }}
+ *   sidebar={{ items: [...], activeKey: "overview" }}
+ * >
+ *   <p>Page content goes here</p>
+ * </ITLayout>
+ *
+ * @example
+ * <ITLayout
+ *   topBar={{ title: "Settings" }}
+ *   sidebar={{ items: navItems }}
+ *   className="min-h-screen"
+ *   contentClassName="max-w-5xl"
+ * >
+ *   <SettingsPage />
+ * </ITLayout>
+ */
 export default function ITLayout({
   topBar,
   sidebar,
@@ -10,37 +35,37 @@ export default function ITLayout({
   className = "",
   contentClassName = "",
 }: ITLayoutProps) {
+  const [internalCollapsed, setInternalCollapsed] = useState(true);
+  const [mobileSidebarOpen, setMobileSidebarOpen] = useState(false);
 
-  // Desktop states
-  const [desktopCollapsed, setDesktopCollapsed] = useState(true); // Default to collapsed
+  const isControlled = sidebar.isCollapsed !== undefined;
+  const desktopCollapsed = isControlled ? sidebar.isCollapsed : internalCollapsed;
+  const handleToggleCollapse = isControlled ? (sidebar.onToggleCollapse ?? (() => {})) : () => setInternalCollapsed(v => !v);
 
-  // Mobile drawer state
-  const [mobileSidebarOpen, setMobileSidebarOpen] = useState(false);
+  const layoutTokens = theme.layout;
 
   return (
     <div className={`flex flex-col h-screen overflow-hidden w-full ${className}`}>
-      
-      {/* TOPBAR - Full Width at Top */}
       <ITTopBar
         {...topBar}
         showMobileMenuButton
         onToggleMobileMenu={() => setMobileSidebarOpen(v => !v)}
       />
 
-      <div className="flex flex-1 overflow-hidden relative" style={{ backgroundColor: "var(--layout-bg, #f8fafc)" }}>
-        
-        {/* DESKTOP SIDEBAR - Floating over content when expanded */}
+      <div
+        className="flex flex-1 overflow-hidden relative"
+        style={{ backgroundColor: layoutTokens.backgroundColor }}
+      >
+        {/* DESKTOP SIDEBAR */}
         <div className="hidden lg:block relative z-40 h-full">
-          {/* Spacer to keep main content from shifting. Width matches collapsed sidebar. */}
           <div className="w-[88px] h-full flex-shrink-0" />
-          
           <div className="absolute top-0 left-0 h-full">
             <ITSidebar
               {...sidebar}
               isCollapsed={desktopCollapsed}
-              onToggleCollapse={() => setDesktopCollapsed(v => !v)}
+              onToggleCollapse={handleToggleCollapse}
               visibleOnMobile={false}
-              className={`h-full drop-shadow-2xl transition-all duration-400 ease-[cubic-bezier(0.2,0,0,1)] flex-shrink-0`}
+              className="h-full drop-shadow-2xl transition-all duration-400 ease-[cubic-bezier(0.2,0,0,1)] flex-shrink-0"
             />
           </div>
         </div>
@@ -51,11 +76,11 @@ export default function ITLayout({
             className="lg:hidden fixed inset-0 z-50 transition-opacity duration-300 backdrop-blur-sm bg-black/40"
             onClick={() => setMobileSidebarOpen(false)}
           >
-            <div 
+            <div
               className="h-full w-fit flex transform transition-transform duration-300 ease-[cubic-bezier(0.2,0,0,1)]"
-              onClick={(e) => e.stopPropagation()} 
+              onClick={(e) => e.stopPropagation()}
             >
-               <ITSidebar
+              <ITSidebar
                 {...sidebar}
                 isCollapsed={false}
                 visibleOnMobile={true}
@@ -74,7 +99,6 @@ export default function ITLayout({
             {children}
           </div>
         </main>
-
       </div>
     </div>
   );

package/src/components/loader/loader.doc.mdx

@@ -0,0 +1,43 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './loader.stories';
+
+<Meta of={Stories} />
+
+# ITLoader
+
+A loading indicator with four animation variants and customizable sizing and color. Useful for async operations, data fetching states, and any in-progress feedback.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `'spinner' \| 'dots' \| 'bar' \| 'pulse'` | `'spinner'` | Animation style. |
+| `size` | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Size preset. |
+| `color` | `string` | `'primary'` | Color value. Accepts theme semantic keys (`primary`, `secondary`, `success`, `danger`, `warning`, `info`, `purple`), hex, rgb, or CSS class. |
+| `className` | `string` | `undefined` | Additional CSS classes. |
+
+## Usage
+
+```tsx
+import { ITLoader } from '@axzydev/axzy_ui_system';
+
+<ITLoader />
+<ITLoader variant="dots" color="secondary" size="lg" />
+<ITLoader variant="bar" color="success" />
+<ITLoader variant="pulse" color="danger" size="xl" />
+```
+
+## Notes
+
+- `spinner` — rotating circular indicator.
+- `dots` — bouncing dots sequence.
+- `pulse` — pulsing circle with scaling animation.
+- `bar` — horizontal indeterminate progress bar (intended for use in a container with explicit width).
+- Color mapping is handled through the theme system; semantic keys resolve to CSS custom properties.
+- All animations use CSS keyframes with GPU-accelerated transforms where possible.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/loader/loader.props.ts

@@ -1,8 +1,12 @@
 import { LoaderSize, LoaderVariant } from "@/types/loader.types";
 
 export interface LoaderProps {
+  /** Loader size: "sm" | "md" | "lg" | "xl" */
   size?: LoaderSize;
+  /** Animation variant: "spinner" | "dots" | "bar" | "pulse" */
   variant?: LoaderVariant;
+  /** Color value. Can be a theme semantic color key, hex string, rgb string, or CSS class */
   color?: string;
+  /** Additional CSS classes */
   className?: string;
 }

package/src/components/loader/loader.tsx

@@ -3,6 +3,23 @@ import { LoaderSize, sizeClasses } from "@/types/loader.types";
 import { LoaderProps } from "./loader.props";
 import ITText from "@/components/text/text";
 
+/**
+ * Loading indicators with multiple animation types: spinner, dots, pulse,
+ * and bar. Supports configurable size, color (theme semantic or custom),
+ * and inline/padded rendering.
+ *
+ * @example
+ * <ITLoader variant="spinner" size="lg" color="primary" />
+ *
+ * @example
+ * <ITLoader variant="dots" size="md" color="#06b6d4" />
+ *
+ * @example
+ * <ITLoader variant="bar" size="sm" color="secondary" className="w-48" />
+ *
+ * @example
+ * <ITLoader variant="pulse" size="xl" color="red-500" />
+ */
 export default function ITLoader({
   size = "md",
   variant = "spinner",

package/src/components/navbar/navbar.doc.mdx

@@ -0,0 +1,77 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './navbar.stories';
+
+<Meta of={Stories} />
+
+# ITNavbar
+
+A full sidebar navigation shell for application layouts. Provides collapsible submenus with expand/collapse animation, active state highlighting via `isActive`, and an optional user menu dropdown with avatar, name, and email.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `navigationItems` | `ITNavigationItem[]` | `undefined` | Navigation items with labels, icons, subitems, and active states. |
+| `logo` | `ReactNode` | `undefined` | Logo element rendered in the sidebar header. |
+| `logoText` | `string` | `undefined` | Text displayed next to the logo. |
+| `userMenu` | `{ userImage?, userName, userEmail, menuItems }` | `undefined` | User dropdown configuration. |
+| `children` | `ReactNode` | `undefined` | Main content rendered next to the sidebar. |
+| `navItems` | `ReactNode` | `undefined` | **Deprecated.** Use `navigationItems` instead. |
+| `showSidebar` | `boolean` | `undefined` | **Deprecated.** Legacy flag. |
+| `showSidebarOnMobile` | `boolean` | `undefined` | **Deprecated.** Legacy flag. |
+| `sidebarItems` | `ReactNode` | `undefined` | **Deprecated.** Use `navigationItems` instead. |
+
+### ITNavigationItem
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `string` | required | Unique identifier. |
+| `label` | `string` | required | Display label. |
+| `icon` | `ReactNode` | `undefined` | Icon rendered next to the label. |
+| `action` | `() => void` | `undefined` | Callback on click. |
+| `isActive` | `boolean` | `false` | Whether the item is currently highlighted as active. |
+| `subitems` | `ITNavigationSubItem[]` | `undefined` | Nested items shown on expand. |
+
+### ITNavigationSubItem
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `id` | `string` | required | Unique identifier. |
+| `label` | `string` | required | Display label. |
+| `action` | `() => void` | required | Callback on click. |
+| `isActive` | `boolean` | `false` | Whether the sub-item is highlighted. |
+
+## Usage
+
+```tsx
+import { ITNavbar } from '@axzydev/axzy_ui_system';
+import { FaHome, FaChartBar } from 'react-icons/fa';
+
+<ITNavbar
+  logoText="AXZY"
+  navigationItems={[
+    { id: 'home', label: 'Dashboard', icon: <FaHome />, isActive: true },
+    { id: 'analytics', label: 'Analytics', icon: <FaChartBar />,
+      subitems: [{ id: 'reports', label: 'Reports', action: () => {} }]
+    }
+  ]}
+  userMenu={{ userName: 'John', userEmail: 'john@axzy.dev', menuItems: [...] }}
+>
+  <div>Content area</div>
+</ITNavbar>
+```
+
+## Notes
+
+- Sidebar has a collapsed state where only icons are visible; expanding shows labels.
+- Submenus animate open/closed with a height transition.
+- Items with `isActive` are visually highlighted.
+- `userMenu` renders a dropdown at the bottom of the sidebar with user info and action items.
+- Legacy props (`navItems`, `showSidebar`, etc.) are maintained for backward compatibility but should be migrated to `navigationItems`.
+- Supports dark mode via CSS variables from the theme provider.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />

package/src/components/navbar/navbar.props.ts

@@ -1,37 +1,73 @@
 // navbar.props.ts
+
+/** Represents a navigation item in the sidebar. */
 export interface ITNavigationItem {
+  /** Unique identifier for the navigation item. */
   id: string;
+  /** Display label for the navigation item. */
   label: string;
+  /** Optional icon rendered next to the label. */
   icon?: React.ReactNode;
+  /** Callback fired when the item is clicked. */
   action?: () => void;
+  /** Whether the item is currently active and highlighted. */
   isActive?: boolean;
+  /** Optional nested sub-navigation items. */
   subitems?: ITNavigationSubItem[];
 }
 
+/** Represents a sub-navigation item within a parent navigation item. */
 export interface ITNavigationSubItem {
+  /** Unique identifier for the sub-item. */
   id: string;
+  /** Display label for the sub-item. */
   label: string;
+  /** Callback fired when the sub-item is clicked. */
   action: () => void;
+  /** Whether the sub-item is currently active and highlighted. */
   isActive?: boolean;
 }
 
+/** Props for the ITNavbar component. */
 export interface ITNavbarProps {
+  /** Logo element rendered in the sidebar header. */
   logo?: React.ReactNode;
+  /** Text displayed next to the logo. */
   logoText?: string;
+  /** Array of navigation items for the main sidebar menu. */
   navigationItems?: ITNavigationItem[];
+  /** User menu configuration including avatar, name, email, and dropdown items. */
   userMenu?: {
+    /** URL for the user's profile image. */
     userImage?: string;
+    /** Display name of the user. */
     userName: string;
+    /** Email address of the user. */
     userEmail: string;
+    /** Dropdown menu items for the user menu. */
     menuItems: Array<{
+      /** Display label for the menu item. */
       label: string;
+      /** Callback fired when the menu item is clicked. */
       onClick: () => void;
     }>;
   };
+  /** Content rendered in the main area next to the sidebar. */
   children?: React.ReactNode;
-  // Legacy props for backward compatibility
+  /** Legacy navigation items. Use `navigationItems` instead.
+   * @deprecated
+   */
   navItems?: React.ReactNode;
+  /** Legacy flag to show the sidebar.
+   * @deprecated
+   */
   showSidebar?: boolean;
+  /** Legacy flag to show the sidebar on mobile devices.
+   * @deprecated
+   */
   showSidebarOnMobile?: boolean;
+  /** Legacy sidebar items. Use `navigationItems` instead.
+   * @deprecated
+   */
   sidebarItems?: React.ReactNode;
 }

package/src/components/navbar/navbar.stories.tsx

@@ -0,0 +1,84 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import ITNavbar from './navbar';
+import { FaHome, FaChartBar, FaCog, FaUsers } from 'react-icons/fa';
+
+const meta = {
+  title: 'Components/Layout & Navigation/ITNavbar',
+  component: ITNavbar,
+  parameters: { layout: 'fullscreen' },
+  tags: ['autodocs'],
+  argTypes: {
+    logoText: { control: 'text', description: 'Text displayed next to the logo' },
+    navigationItems: { control: false, description: 'Navigation items with optional sub-items' },
+    userMenu: { control: false, description: 'User menu configuration' },
+    children: { control: false, description: 'Main content area' },
+  },
+} satisfies Meta<typeof ITNavbar>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const sampleNavigationItems = [
+  {
+    id: 'home',
+    label: 'Dashboard',
+    icon: <FaHome />,
+    action: () => {},
+    isActive: true,
+  },
+  {
+    id: 'analytics',
+    label: 'Analytics',
+    icon: <FaChartBar />,
+    action: () => {},
+    subitems: [
+      { id: 'reports', label: 'Reports', action: () => {} },
+      { id: 'metrics', label: 'Metrics', action: () => {} },
+    ],
+  },
+  {
+    id: 'users',
+    label: 'Users',
+    icon: <FaUsers />,
+    action: () => {},
+  },
+  {
+    id: 'settings',
+    label: 'Settings',
+    icon: <FaCog />,
+    action: () => {},
+  },
+];
+
+export const Default: Story = {
+  args: {
+    logoText: 'AXZY',
+    navigationItems: sampleNavigationItems,
+    userMenu: {
+      userName: 'John Doe',
+      userEmail: 'john@axzy.dev',
+      menuItems: [
+        { label: 'Profile', onClick: () => alert('Profile') },
+        { label: 'Logout', onClick: () => alert('Logout') },
+      ],
+    },
+    children: (
+      <div className="p-8">
+        <h1 className="text-2xl font-bold text-slate-800 dark:text-white">Welcome to AXZY</h1>
+        <p className="text-slate-500 dark:text-slate-400 mt-2">Main content area goes here.</p>
+      </div>
+    ),
+  },
+};
+
+export const NoUserMenu: Story = {
+  args: {
+    logoText: 'AXZY',
+    navigationItems: sampleNavigationItems,
+    children: (
+      <div className="p-8">
+        <h1 className="text-2xl font-bold text-slate-800 dark:text-white">Public View</h1>
+      </div>
+    ),
+  },
+};