@axzydev/axzy_ui_system 1.2.7 → 1.2.8

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

@@ -5,6 +5,29 @@ 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,
@@ -12,9 +35,13 @@ export default function ITLayout({
   className = "",
   contentClassName = "",
 }: ITLayoutProps) {
-  const [desktopCollapsed, setDesktopCollapsed] = useState(true);
+  const [internalCollapsed, setInternalCollapsed] = useState(true);
   const [mobileSidebarOpen, setMobileSidebarOpen] = useState(false);
 
+  const isControlled = sidebar.isCollapsed !== undefined;
+  const desktopCollapsed = isControlled ? sidebar.isCollapsed : internalCollapsed;
+  const handleToggleCollapse = isControlled ? (sidebar.onToggleCollapse ?? (() => {})) : () => setInternalCollapsed(v => !v);
+
   const layoutTokens = theme.layout;
 
   return (
@@ -36,7 +63,7 @@ export default function ITLayout({
             <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"
             />

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>
+    ),
+  },
+};

package/src/components/navbar/navbar.tsx

@@ -5,6 +5,33 @@ import { ITNavbarProps, ITNavigationItem } from "./navbar.props";
 import ITText from "@/components/text/text";
 import { theme } from "@/theme/theme";
 
+/**
+ * Full sidebar navigation shell with collapsible submenus, user menu dropdown, and themed styling.
+ *
+ * @example
+ * ```tsx
+ * <ITNavbar
+ *   logo={<LogoIcon />}
+ *   logoText="My App"
+ *   navigationItems={[
+ *     { id: 'home', label: 'Home', icon: <FaHome />, isActive: true },
+ *     {
+ *       id: 'settings',
+ *       label: 'Settings',
+ *       icon: <FaCog />,
+ *       subitems: [{ id: 'profile', label: 'Profile', action: () => {} }],
+ *     },
+ *   ]}
+ *   userMenu={{
+ *     userName: 'John Doe',
+ *     userEmail: 'john@example.com',
+ *     menuItems: [{ label: 'Logout', onClick: () => {} }],
+ *   }}
+ * >
+ *   <ITPage title="Dashboard">...</ITPage>
+ * </ITNavbar>
+ * ```
+ */
 export default function ITNavbar({
   logo,
   logoText,

package/src/components/page/page.doc.mdx

@@ -0,0 +1,80 @@
+import { Meta, Title, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import * as Stories from './page.stories';
+
+<Meta of={Stories} />
+
+# ITPage
+
+A page template component that wraps an ITPageHeader with content area and built-in state handling for loading, error, and empty states. Provides automatic skeleton placeholders during loading, an error boundary with retry action, and a customizable empty state with action.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | `undefined` | Page title passed to the header. |
+| `description` | `string` | `undefined` | Description text shown below the title. |
+| `breadcrumbs` | `ITBreadcrumbItem[]` | `undefined` | Breadcrumb navigation items. |
+| `actions` | `ReactNode` | `undefined` | Action buttons rendered in the header. |
+| `backAction` | `() => void` | `undefined` | Callback for the back button. |
+| `icon` | `ReactNode` | `undefined` | Icon displayed next to the title. |
+| `iconColor` | `string` | `undefined` | Custom color for the icon. |
+| `loading` | `boolean` | `false` | When true, shows skeleton placeholders instead of content. |
+| `error` | `string \| null` | `null` | Error message. When provided, shows an error state with retry button. |
+| `errorTitle` | `string` | `'Error'` | Custom title for the error state. |
+| `errorActionLabel` | `string` | `'Reintentar'` | Label for the retry button in the error state. |
+| `onRetry` | `() => void` | `undefined` | Callback when the retry button is clicked. |
+| `empty` | `boolean` | `false` | When true, shows an empty state placeholder. |
+| `emptyTitle` | `string` | `'Sin datos'` | Custom title for the empty state. |
+| `emptyDescription` | `string` | `undefined` | Custom description for the empty state. |
+| `emptyAction` | `ReactNode` | `undefined` | Custom action element for the empty state. |
+| `children` | `ReactNode` | required | Content rendered when no special state (loading/error/empty) is active. |
+| `maxWidth` | `'2xl' \| '3xl' \| '4xl' \| '5xl' \| '6xl' \| '7xl'` | `'7xl'` | Maximum width of the page content container. |
+| `noPadding` | `boolean` | `false` | When true, removes default padding from the page wrapper. |
+| `className` | `string` | `undefined` | Additional CSS classes for the page wrapper. |
+
+## Usage
+
+```tsx
+import { ITPage } from '@axzydev/axzy_ui_system';
+
+<ITPage title="Users" description="Manage system users" actions={<ITButton label="Add" />}>
+  <p>Your page content</p>
+</ITPage>
+
+<ITPage title="Dashboard" loading>
+  <p>Content not shown while loading</p>
+</ITPage>
+
+<ITPage
+  title="Orders"
+  error="Failed to load orders"
+  onRetry={() => refetch()}
+>
+  <p>Content not shown while error</p>
+</ITPage>
+
+<ITPage
+  title="Notifications"
+  empty
+  emptyTitle="No notifications"
+  emptyAction={<ITButton label="Refresh" />}
+>
+  <p>Content not shown while empty</p>
+</ITPage>
+```
+
+## Notes
+
+- State priority: `error` > `loading` > `empty` > `children`.
+- The loading state renders animated skeleton blocks matching common page patterns.
+- The error state renders a centered error icon, message, and a retry button.
+- The empty state renders a centered placeholder with optional title, description, and action.
+- All header props (`title`, `description`, `breadcrumbs`, `actions`, `backAction`, `icon`) are forwarded to ITPageHeader.
+- Content maximum width is controlled by Tailwind max-width classes via `maxWidth`.
+- `noPadding` is useful for full-bleed layouts like dashboards.
+
+## Stories
+
+<Primary />
+<Controls />
+<Stories />